Prompt Engineering Review Checks

SSOT for review output format, severity criteria, and quality check procedures. Referenced by: commands/dev-prompt-review.md. Examples: Read @../prompt-examples/template.md for good vs bad prompt comparison — review agents should reference this when evaluating prompt quality.

Output Rules

Every issue MUST include six parts — no exceptions:

1. Current Behavior — What the prompt currently instructs agents to do. Describe the concrete agent behavior produced by the original text: which action the agent takes, which decision it makes, which output it produces. Include the verbatim quote (2-5 lines of surrounding context) so the reader can locate it. Never paraphrase — quote the actual text, then describe its behavioral effect.
2. Changed Behavior — What the prompt will instruct agents to do after the fix. Describe the concrete agent behavior the suggested text produces: how the action, decision, or output changes. Include the copy-pasteable replacement text. Never write vague suggestions like “clarify this” — write the actual improved text AND describe how agent behavior changes.
3. Why — A specific explanation of what failure, confusion, or risk the current behavior causes. Name the concrete failure mode: which agent gets confused, which phase breaks, which edge case is mishandled, which silent failure occurs. This answers: “What goes wrong today?”
4. Benefit — What concrete improvement the changed behavior provides. Name the specific outcome: “Prevents agent from applying wrong cached fix” or “Eliminates 50% false positive rate in P0 classification.” This answers: “What gets better after the change?” Every fix must justify its existence — if you cannot state a concrete benefit, the issue is not worth reporting.
5. Diff Summary — A one-line statement of the behavioral delta: “Agent currently does X → after fix, agent does Y instead.” This gives the reviewer an instant before/after comparison without reading the full details.
6. Location — File path and line number(s) where the issue exists. For cross-file issues, cite both files.

Rationale: The reviewer needs to see the current behavior vs. changed behavior side-by-side to evaluate whether each fix is correct and worthwhile. Without the current behavior description, they cannot understand what agents do today. Without the changed behavior, they cannot assess if the new behavior is actually better. Without the why, they cannot assess risk. Without the benefit, they cannot prioritize. Without the diff summary, they cannot quickly scan the report. Without the location, they cannot find the issue in the source files.

Output Format

After all agents complete, synthesize a unified report:

# Plugin Prompt Review Report

**Date**: {yyyy-MM-dd HH:mm}
**Files Reviewed**: {count}
**Total Issues**: {count}

## Summary

| Dimension | Issues | P0 | P1 | P2 |
|-----------|--------|----|----|-----|
| Semantic Conflicts | | | | |
| Stale Refs & Completeness | | | | |
| SSOT & Duplication | | | | |
| Workflow Integrity | | | | |
| Ambiguity | | | | |
| Sentence Precision | | | | |
| Edge Cases & Error Paths | | | | |
| Naming Consistency | | | | |
| Token-Level Quality | | | | |

## P0 — Must Fix (blocks correct execution)

### P0-{nn}: [{Dimension}] {short title}

**Location:** `{file}:{line}` (or `{file1}` vs `{file2}`)
**Verification:** {Verified | Downgraded from P{n} | False Positive}
**Diff Summary:** Agent currently {does X} → after fix, agent {does Y instead}.

**Current Behavior:**
> {Verbatim quote of the problematic text from the source file. Include enough surrounding context to locate it unambiguously.}

With this text, the agent {description of what the agent currently does — the concrete action, decision, or output this text produces}.

**Changed Behavior:**
> {The improved version — rewritten text that resolves the issue. Must be a concrete, copy-pasteable replacement, not a vague suggestion like "clarify this".}

With this text, the agent {description of what the agent will do instead — how the action, decision, or output changes}.

**Why:** {1-2 sentences explaining what goes wrong with the current behavior. Be specific — name the failure mode, the confused agent behavior, or the contradiction.}

**Benefit:** {What concrete improvement the changed behavior provides. Name the specific outcome: which failure is prevented, which agent behavior is corrected, which edge case is handled.}

---

## P1 — Should Fix (causes confusion or wrong behavior in edge cases)

### P1-{nn}: [{Dimension}] {short title}

**Location:** `{file}:{line}`
**Verification:** {Verified | Downgraded from P{n}}
**Diff Summary:** Agent currently {does X} → after fix, agent {does Y instead}.

**Current Behavior:**
> {Verbatim quote}

With this text, the agent {description of current behavior}.

**Changed Behavior:**
> {Improved version}

With this text, the agent {description of changed behavior}.

**Why:** {Explanation of the risk}

**Benefit:** {What concrete improvement the changed behavior provides}

---

## P2 — Nice to Fix (clarity improvement)

### P2-{nn}: [{Dimension}] {short title}

**Location:** `{file}:{line}`
**Diff Summary:** Agent currently {does X} → after fix, agent {does Y instead}.

**Current Behavior:**
> {Verbatim quote}

With this text, the agent {description of current behavior}.

**Changed Behavior:**
> {Improved version}

With this text, the agent {description of changed behavior}.

**Why:** {Explanation of the clarity improvement}

**Benefit:** {What concrete improvement the changed behavior provides}

Severity Criteria

Quality Check Categories

Checks are grouped by the model behavior they address. For each check, the agent must evaluate: (1) does this prompt correctly exploit or account for this behavior? (2) what specific failure occurs if the check fails?

Read @prompt-engineering-standards.md for the full principles behind each check category.

Category A: Clarity & Directness (Claude follows explicit instructions; infers poorly from vague ones)

Category B: Examples & Demonstration (few-shot is the most reliable steering mechanism)

Category C: Structure & Sequencing (Claude follows numbered sequences; skips prose-embedded steps)

Category D: Contracts & Boundaries (agents at context boundaries share nothing implicitly)

Category E: Verification & Grounding (agents rationalize success without executable checks)

Category F: Composition & Scale (context window is the #1 constraint)

Category G: Backward Compatibility (existing features must not break)

Category H: Token-Level Quality Patterns (per @../prompt-examples/prompt-engineering-for-skills.md — reduces conditional entropy at decision points)