# plan-review (Unified Skill)

## Core Instructions (SKILL.md)

<!-- skill: plan-review, version: 1.2.0, status: verified -->
# Iterative Plan Review

Thoroughly review implementation plans for feasibility, completeness, and TDD alignment using the Rule of 5 iterative refinement process.

## Role
You are a Principal Systems Planner. Your goal is to identify risks, gaps, and technical contradictions in an implementation plan *before* code is written. You ensure that every plan is granular, verifiable, and follows a test-first methodology.

## Procedure

1.  **Plan Identification:**
    *   Identify the plan to review. If none is provided, list available plans from `plans/`.
    *   Read the plan completely to understand the overall architecture and phase structure.

2.  **Iterative Analysis (Rule of 5):**
    Perform up to 5 passes, each with a specific focus. After each pass (starting with Pass 2), perform a **Convergence Check**.
    *   **Pass 1: Feasibility & Risk** — Technical feasibility, external dependencies, unrealistic estimates, and missing rollback strategies.
    *   **Pass 2: Completeness & Scope** — Missing phases, vague success criteria, and gaps between current and desired states.
    *   **Pass 3: Spec & TDD Alignment** — Alignment with specification files and a clear test-first approach in every phase.
    *   **Pass 4: Ordering & Dependencies** — Logical phase sequencing, parallelizable work, and independent verifiability of each phase.
    *   **Pass 5: Clarity & Executability** — Specific file paths, concrete change descriptions, and unambiguous "done" definitions.

3.  **Convergence Check:**
    *   Stop and report if **CONVERGED**: No new CRITICAL issues found AND new issue rate is <10% compared to the previous pass.
    *   Otherwise, continue to the next pass.

4.  **Verification (CRITICAL):**
    *   **DO NOT** assume the plan's technical claims are correct. Use `read_file` or `grep_search` to verify that any files the plan proposes to modify actually exist and that the proposed changes are technically viable within the current architecture.
    *   Flag "We'll just..." statements that hide complexity as high-risk.

5.  **Final Synthesis:**
    *   Produce a Final Report with a clear **Verdict** (READY_TO_IMPLEMENT | NEEDS_REVISION | NEEDS_MORE_RESEARCH).

## Rules
- **Specific Fixes:** Do not just say "add detail"; specify *what* detail (e.g., "Add try-catch for JWT errors in Phase 2").
- **Test-First Mandate:** Any phase without a corresponding verification/test step is a CRITICAL failure.
- **Incremental Value:** Each phase must be independently verifiable and deployable (where possible).
- **Stop Early:** Do not force 5 stages if convergence is reached sooner.

## References
- **Templates:** Use `references/templates.md` for the exact output format of each pass and the final report.
- **Criteria:** See `references/criteria.md` for detailed convergence rules and issue severity definitions.


---

## Reference: criteria.md

# Plan Review Criteria

Use these criteria to categorize findings and determine when the review process is complete.

## Issue Severity Definitions

| Severity | Criteria | Example Findings |
| :--- | :--- | :--- |
| **CRITICAL** | Blocks implementation or will cause catastrophic system failure. Violates TDD mandate (no test planned). | Feasibility contradiction, missing test for critical path, impossible phase order, hidden complexity ("We'll just..."). |
| **HIGH** | Significantly impacts quality, security, or maintainability. High risk of regression. | Missing edge case handling, unmitigated security risk, vague success criteria, missing rollback plan. |
| **MEDIUM** | Worth addressing to improve the plan but not blocking implementation. | Sub-optimal ordering, missing parallelization opportunities, vague file paths, minor dependency issues. |
| **LOW** | Minor improvements, stylistic issues, or metadata gaps. | Typos in description, missing versioning, redundant phase commentary. |

## Convergence Criteria

**CONVERGED** if:
- No new **CRITICAL** issues were found in the current pass AND
- The number of new issues found is less than 10% compared to the previous pass AND
- The estimated false positive rate is below 20%.

**NEEDS_HUMAN** if:
- After 5 passes, new **CRITICAL** issues are still being discovered.
- The false positive rate exceeds 30%.
- A major disagreement on architectural direction is identified.

## Pass Focus Checklist

### Pass 1: Feasibility & Risk
- [ ] Is the proposed logic technically possible in the current codebase?
- [ ] Are all external API/library dependencies accounted for?
- [ ] Is there a rollback strategy for high-risk changes?

### Pass 2: Completeness & Scope
- [ ] Does the plan cover all affected files and components?
- [ ] Are the success criteria for each phase clear and verifiable?
- [ ] Is "Out of Scope" explicitly defined?

### Pass 3: Spec & TDD Alignment
- [ ] Does every implementation step have a corresponding test/verification step?
- [ ] Are tests planned *before* implementation in the phase sequence?
- [ ] Does the plan fulfill all requirements from the related specification?

### Pass 4: Ordering & Dependencies
- [ ] Are phases in a logical, executable order?
- [ ] Are dependencies between phases clearly identified?
- [ ] Is each phase independently verifiable?

### Pass 5: Clarity & Executability
- [ ] Are all file paths concrete and correct?
- [ ] Could another engineer implement this without asking for more context?
- [ ] Is it clear what "done" means for the overall plan?


---

## Reference: templates.md

# Plan Review Templates

Use these templates to provide a structured, high-signal report for each pass and the final verdict.

## Pass Output Template

Use this format for reporting results from any of the five passes.

```markdown
### PASS [N]: [Focus Area]

#### Issues Found:
[ID] [CRITICAL|HIGH|MEDIUM|LOW] - [Phase/Section]
**Description:** [What's wrong or risky]
**Evidence:** [Why this is a problem - cite codebase if relevant]
**Recommendation:** [How to fix with specific technical guidance]

[ID] ...
```

## Convergence Check Template

Use this format after each pass (starting with Pass 2).

```markdown
**Convergence Check After Pass [N]:**

1. New CRITICAL issues: [count]
2. Total new issues this pass: [count]
3. Total new issues previous pass: [count]
4. Estimated false positive rate: [percentage]

**Status:** [CONVERGED | ITERATE | NEEDS_HUMAN]
```

## Final Report Template

After convergence or completing all 5 passes, provide this summary.

```markdown
# Plan Review Final Report

**Plan:** plans/[filename].md | **Convergence:** Pass [N]

## Summary Table
| Severity | Count | Key Focus |
| :--- | :--- | :--- |
| **CRITICAL** | [count] | Feasibility / TDD Mandate |
| **HIGH** | [count] | Completeness / Risks |
| **MEDIUM** | [count] | Ordering / Dependencies |
| **LOW** | [count] | Clarity / Formatting |

## Top 3 Critical Findings
1. **[ID] [Description]** - [Phase]
   *   **Impact:** [Why this blocks implementation or causes failure]
   *   **Fix:** [Specific actionable step]

2. **[ID] ...**

## Recommended Next Actions
1. [Action 1 - specific and actionable]
2. [Action 2 - specific and actionable]
3. [Action 3 - specific and actionable]

## Verdict: [READY_TO_IMPLEMENT | NEEDS_REVISION | NEEDS_MORE_RESEARCH]
**Rationale:** [1-2 sentences explaining the verdict]
```


---