why-review Skill | Agent Skills

[BLOCKING] This is a validation gate. MUST ATTENTION use AskUserQuestion to present review findings and get user confirmation. Completing without asking at least one question is a violation.

[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.

Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof.

Cite file:line, grep results, or framework docs for EVERY claim

Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend

Cross-service validation required for architectural changes

"I don't have enough evidence" is valid and expected output

BLOCKED until: - [ ] Evidence file path (file:line) - [ ] Grep search performed - [ ] 3+ similar patterns found - [ ] Confidence level stated

Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because" If incomplete → output: "Insufficient evidence. Verified: [...]. Not verified: [...]."

Deep Multi-Round Review — THREE mandatory escalating-depth rounds. NEVER combine. NEVER PASS after Round 1 alone.

Round 1: Normal review building understanding. Read all files, note issues. Round 2: MANDATORY re-read ALL files from scratch. Focus on:

Cross-cutting concerns missed in Round 1

Interaction bugs between changed files

Convention drift (new code vs existing patterns)

Missing pieces (what should exist but doesn't)

Round 3: MANDATORY adversarial simulation (for >3 files or cross-cutting changes). Pretend you are using/running this code RIGHT NOW:

"What input causes failure? What error do I get?"

"1000 concurrent users — what breaks?"

"After deployment rollback — backward compatible?"

"Can I debug issues from logs/monitoring output?"

Rules: NEVER rely on prior round memory — re-read everything. NEVER declare PASS after Round 1. Final verdict must incorporate ALL rounds. Report must include ## Round 2 Findings and ## Round 3 Findings sections.

Graph Impact Analysis — When .code-graph/graph.db exists, run blast-radius --json to detect ALL files affected by changes (7 edge types: CALLS, MESSAGE_BUS, API_ENDPOINT, TRIGGERS_EVENT, PRODUCES_EVENT, TRIGGERS_COMMAND_EVENT, INHERITS). Compute gap: impacted_files - changed_files = potentially stale files. Risk: <5 Low, 5-20 Medium, >20 High. Use trace --direction downstream for deep chains on high-impact files.

Critical Purpose: Ensure quality — no flaws, no bugs, no missing updates, no stale content. Verify both code AND documentation.

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

OOP & DRY Enforcement: MANDATORY IMPORTANT MUST ATTENTION — flag duplicated patterns that should be extracted to a base class, generic, or helper. Classes in the same group or suffix (ex *Entity, *Dto, *Service, etc...) MUST ATTENTION inherit a common base (even if empty now — enables future shared logic and child overrides). Verify project has code linting/analyzer configured for the stack.

Quick Summary

Goal: Validate that a plan contains sufficient design rationale (WHY, not just WHAT) before implementation begins.

Applies to: Features and refactors only — bugfixes and trivial changes exempt.

Why this exists: AI code generation optimizes mechanics but misses conceptual quality. This skill ensures the human thinking happened before the mechanical coding starts.

Your Mission

<task> $ARGUMENTS </task>

Review Mindset (NON-NEGOTIABLE)

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Do NOT accept plan rationale at face value — verify alternatives were genuinely considered
Every pass/fail must include evidence (section reference, specific text quoted)
If rationale is vague or hand-wavy, flag it — "we chose X" without WHY is a fail
Question assumptions: "Is this really the best approach?" → check if alternatives have real trade-offs listed
Challenge completeness: "Are all risks identified?" → think about what could go wrong that isn't mentioned
No "looks fine" without proof — state what you verified and how

Plan Resolution

If arguments contain a path → use that plan directory
Else check ## Plan Context in injected context → use active plan path
If no plan found → tell user: "No active plan found. Run /plan or /plan-hard first."

Validation Checklist

Read the plan's plan.md and all phase-*.md files. Check each item below. Report pass/fail for each.

Required Sections (in plan.md or phase files)

| # | Section | What to Check | Pass Criteria | | --- | --------------------------- | ---------------------------------------------- | ------------------------------------------------- | | 1 | Problem Statement | Clearly states WHAT problem is being solved | 2-3 sentences describing the problem | | 2 | Alternatives Considered | 2+ approaches with pros/cons | Minimum 2 alternatives with trade-offs | | 3 | Design Rationale | Explains WHY chosen approach over alternatives | Explicit reasoning linking decision to trade-offs | | 4 | Risk Assessment | Risks identified with likelihood and impact | At least 1 risk per phase | | 5 | Ownership | Clear who maintains code post-merge | Implicit OK (author owns), explicit better |

Optional (Flag if Missing, Don't Fail)

| # | Section | When Required | | --- | ------------------------ | --------------------------------------- | | 6 | Operational Impact | Service-layer or API changes | | 7 | Cross-Service Impact | Changes touching multiple microservices | | 8 | Migration Strategy | Database schema or data changes |

Output Format

## Why-Review Results

**Plan:** {plan path}
**Date:** {date}
**Verdict:** PASS / NEEDS WORK

### Checklist

| #   | Check                   | Status | Notes     |
| --- | ----------------------- | ------ | --------- |
| 1   | Problem Statement       | ✅/❌  | {details} |
| 2   | Alternatives Considered | ✅/❌  | {details} |
| 3   | Design Rationale        | ✅/❌  | {details} |
| 4   | Risk Assessment         | ✅/❌  | {details} |
| 5   | Ownership               | ✅/❌  | {details} |

### Missing Items (if any)

- {specific item to add before implementation}

### Recommendation

{Proceed to /cook | Add missing sections first}

Round 2: Focused Re-Review (MANDATORY)

Protocol: Deep Multi-Round Review (inlined via SYNC:double-round-trip-review above)

After completing Round 1 checklist evaluation, execute a second full review round:

Re-read the Round 1 verdict and checklist results
Re-evaluate ALL checklist items — do NOT rely on Round 1 memory
Challenge Round 1 PASS items: "Is this really PASS? Did I verify with evidence?"
Focus on what Round 1 typically misses:
- Implicit assumptions that weren't validated
- Missing acceptance criteria coverage
- Edge cases not addressed in the artifact
- Cross-references that weren't verified
Update verdict if Round 2 found new issues
Final verdict must incorporate findings from BOTH rounds

Scope

Applies to: Features, refactors, architectural changes
Exempt: Bugfixes, config changes, single-file tweaks, documentation-only
Enforcement: Advisory (soft warning) — does not block implementation

Important Notes

Review only — do NOT modify plan files or implement changes
Keep output concise — actionable in <2 minutes
If plan is simple and clear, a short "PASS" is sufficient

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use AskUserQuestion to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

"/cook (Recommended)" — Begin implementation after design rationale is validated
"/code" — If implementing a simpler change
"Skip, continue manually" — user decides

Closing Reminders

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST ATTENTION validate decisions with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality. MANDATORY IMPORTANT MUST ATTENTION READ the following files before starting:

IMPORTANT MUST ATTENTION cite file:line evidence for every claim. Confidence >80% to act, <60% do NOT recommend.
IMPORTANT MUST ATTENTION execute TWO independent review rounds. Report must include ## Round 2 Findings.
IMPORTANT MUST ATTENTION run graph blast-radius on changed files to find potentially stale consumers/handlers (when graph.db exists).

Agent Skills: why-review

Install this agent skill to your local

Skill Files