Structured Prompt Template

Ad-hoc prompts lack consistency, reusability, and clear contracts for what goes in and what comes out. A six-section template gives every prompt a predictable shape so agents know exactly what to read, what to fill in, and what to produce.

Background

This pattern extends IndyDevDan's Four Level Framework for Prompt Engineering, which progresses through four maturity levels:

1. Ad-hoc prompt -- quick natural language for one-off tasks
2. Structured prompt -- reusable format with XML/markdown sections and static variables
3. Structured prompt with example output -- adds example output to guide format consistency
4. Structured prompt with dynamic content -- production-ready prompts with filled programmatically

The template below operates at Level 4: a production-ready skeleton with dynamic variables, plus Workflow and Report sections for end-to-end agent execution.

Pattern

Structure every prompt file with YAML frontmatter and five body sections:

Frontmatter

Metadata that lets tooling discover and invoke the prompt without reading its body.

---
description: One-line summary of what the prompt accomplishes
argument-hint: <required-arg> [optional-arg]
---

• description -- shown in listings and search results; write it as a verb phrase ("Review a pull request", "Generate a migration plan")
• argument-hint -- documents positional arguments the caller must supply; angle brackets for required, square brackets for optional

Purpose

State what the prompt accomplishes and why it exists. One to three sentences. This is the prompt's contract with the caller -- if the purpose doesn't match the task, the caller should look elsewhere.

Variables

Declare every dynamic input the prompt accepts. For each variable, specify its name, type, whether it is required, and a default if applicable.

## Variables

- `{{pr_url}}` (string, required) -- URL of the pull request to review
- `{{focus_areas}}` (list, optional, default: all) -- aspects to prioritize
  (security, performance, readability)
- `{{max_comments}}` (integer, optional, default: 10) -- cap on review comments

Instructions

Specific guidelines the agent must follow while executing. These are constraints and policies, not steps. Use imperative sentences.

## Instructions

- Read the full diff before writing any comments
- Flag security issues as blocking; flag style issues as non-blocking
- Never suggest changes that alter public API signatures without discussion
- Cite file path and line number in every comment

Workflow

Ordered steps the agent executes from start to finish. Number each step. The workflow is the procedural backbone -- it references variables and respects instructions.

## Workflow

1. Fetch the diff from `{{pr_url}}`
2. Identify changed files and categorize by type (source, test, config)
3. For each changed source file, review against `{{focus_areas}}`
4. Draft up to `{{max_comments}}` comments, prioritized by severity
5. Write the Report

Report

Define the exact output the agent produces when finished. Specify format, required sections, and any structured data. The report is the prompt's deliverable -- callers depend on its shape.

## Report

Produce a markdown summary with:

- **Overview:** one-paragraph assessment of the PR
- **Blocking issues:** numbered list (empty if none)
- **Suggestions:** numbered list of non-blocking improvements
- **Verdict:** APPROVE, REQUEST_CHANGES, or COMMENT

Example

A complete prompt file for reviewing a pull request:

---
description: Review a pull request for code quality and security
argument-hint: <pr-url> [focus-areas]
---

## Purpose

Review a GitHub pull request and produce a structured summary of issues,
suggestions, and an overall verdict. Ensures every PR gets consistent,
thorough feedback regardless of who triggers the review.

## Variables

- `{{pr_url}}` (string, required) -- URL of the pull request to review
- `{{focus_areas}}` (list, optional, default: all) -- aspects to prioritize
  (security, performance, readability)
- `{{max_comments}}` (integer, optional, default: 10) -- cap on review comments

## Instructions

- Read the full diff before writing any comments
- Flag security issues as blocking; flag style issues as non-blocking
- Never suggest changes that alter public API signatures without discussion
- Cite file path and line number in every comment
- If the diff exceeds 500 lines, summarize by file group before detailed review

## Workflow

1. Fetch the diff and metadata from `{{pr_url}}`
2. List changed files and categorize as source, test, config, or docs
3. Review each source file against `{{focus_areas}}`
4. Cross-check that tests cover new or changed behavior
5. Draft up to `{{max_comments}}` comments, ordered by severity
6. Write the Report

## Report

Produce a markdown summary:

- **Overview:** one-paragraph assessment
- **Blocking issues:** numbered list with file:line references (empty if none)
- **Suggestions:** numbered list of non-blocking improvements
- **Verdict:** APPROVE, REQUEST_CHANGES, or COMMENT

Checks

• Frontmatter has both description and argument-hint
• Purpose section exists and is three sentences or fewer
• Every in Workflow and Instructions is declared in Variables
• Variables include type and required/optional for each entry
• Workflow steps are numbered and reference variables by name
• Report specifies the output format and required sections
• No step in Workflow contradicts a rule in Instructions