# planning (Unified Skill) ## Core Instructions (SKILL.md) #### Core Instructions (content/distilled/planning/SKILL.md) # Planning Router Route planning work to the right mode, then read that mode's instructions before acting. ## Modes | Task signal | Mode | Read | |---|---|---| | design a phased implementation plan (TDD-oriented) from a goal | create-plan | `references/create-plan/SKILL.md` | | execute an existing plan phase by phase | implement-plan | `references/implement-plan/SKILL.md` | | review an implementation plan for gaps, risks, sequencing | plan-review | `references/plan-review/SKILL.md` | | refine an existing plan from feedback or new constraints | iterate-plan | `references/iterate-plan/SKILL.md` | ## Selection rules - No plan exists yet → **create-plan**. Plan exists and work is approved → **implement-plan**. - Plan exists but is under critique → **plan-review**; under revision → **iterate-plan**. Review first when feedback is vague, iterate when it is specific. - These modes chain: create-plan → plan-review → iterate-plan → implement-plan. ## Procedure 1. Identify the mode from the table above. 2. Read the referenced file (resolve paths against this skill's directory); follow its templates and verification steps. --- #### Reference: references/create-plan/references/plan-template.md ```markdown # [Feature Name] Implementation Plan Date: YYYY-MM-DD ## Overview [Brief description of what is being implemented] ## Related - Spec: `specs/...` [if applicable] - Research: `research/...` [if applicable] - Related issues or tickets: [references] ## Current State [What exists now and what is missing] ## Desired End State [What will exist after implementation] How to verify: - [Specific verification step] - [Expected behavior] ## Out of Scope [What is explicitly excluded] ## Risks & Mitigations [Key risks and mitigations] ## Phase 1: [Name] ### Changes Required File: `path/to/file.ext` - Changes: [Specific modifications needed] - Tests: [What to write first] ### Implementation Approach [How this phase should be implemented] ### Success Criteria Automated: - [ ] Tests pass - [ ] Type checking passes [if applicable] - [ ] Linting passes [if applicable] - [ ] Build succeeds [if applicable] Manual: - [ ] [Manual verification step] ### Dependencies [Dependencies or blockers] --- ## Testing Strategy Following TDD: 1. Write tests first. 2. Confirm they fail. 3. Implement the minimum to pass. 4. Refactor while staying green. Test types needed: - Unit tests: [What to cover] - Integration tests: [What to cover] - E2E tests: [If applicable] ## Rollback Strategy [How to back out safely] ## Related Links - [Documentation] - [Similar implementation] - [External resource] ``` --- #### Reference: references/create-plan/references/scenarios.md ## Example Scenarios ### Feature with spec - Read the spec. - Research existing patterns. - Propose a phased plan grounded in the codebase. ### No spec, only feature description - Research the current implementation. - Present viable options if there is a meaningful design choice. - Recommend one approach and then write the detailed plan. ### Complex feature with technical uncertainty - Research the architectural constraints first. - Present 2-3 options with tradeoffs. - Get user alignment before writing the final plan. --- #### Reference: references/create-plan/SKILL.md # Create Implementation Plan Create a detailed implementation plan for the requested feature. ## Procedure 1. Read any provided spec or task description fully. 2. Research the codebase and existing patterns. 3. If multiple approaches are viable, present options and get alignment before finalizing. 4. Write the plan using `references/plan-template.md`. 5. If needed, use `references/scenarios.md` for example interaction patterns. ## Rules - Be specific: include actual file paths and concrete changes. - Plan tests before implementation for each phase. - Keep phases independently verifiable. - Resolve open questions with normal user clarification, not tool-specific assumptions. - Prefer realistic plans over exhaustive but unusable plans. --- #### Reference: references/implement-plan/references/common-situations.md ## Common Situations ### Tests already pass - Verify the implementation really matches the plan. - Mark the phase complete if it does. ### The plan does not match reality Report: ```text Issue in Phase [N]: Expected (from plan): [What the plan says] Found (in codebase): [Actual situation] Why this matters: [Impact] Options: 1. Adapt implementation to current reality 2. Update the plan 3. Ask the user for guidance ``` ### A better approach appears mid-implementation - Explain the current plan. - Explain the alternative. - Summarize the tradeoffs. - Ask whether to continue or update the plan. ### External dependency is unavailable - State what is blocked. - Explain impact. - List available workarounds, if any. --- #### Reference: references/implement-plan/references/verification-template.md ```text Phase [N] Complete - Ready for Verification Automated verification: - [x] All tests pass - [x] Type checking passes - [x] Build succeeds - [x] File headers current: new files carry Purpose/Responsibilities/Rationale; changed files updated Rationale (see `file-headers`) Manual verification needed: - [ ] [Manual step 1] - [ ] [Manual step 2] Changes made: - [path:line] [What changed] - [path:line] [What changed] Let me know when verified so I can proceed to Phase [N+1]. ``` --- #### Reference: references/implement-plan/SKILL.md # Implement Plan Implement an approved plan using Red, Green, Refactor. ## Procedure 1. Read the plan completely and identify the first incomplete phase. 2. Read any related specs or documentation referenced by the plan. 3. For each phase: - Write failing tests first. - Implement the minimum code to pass. - Refactor while keeping tests green. - Run the success criteria checks. - Check file headers: new source files open with Purpose/Responsibilities/Rationale; files whose contract changed have a current Rationale (see `file-headers`). - Update the plan with progress. 4. Use `references/verification-template.md` when reporting phase completion. 5. Use `references/common-situations.md` when the plan and reality diverge. ## Rules - Never skip the red phase. - Complete one phase at a time. - Review file headers before declaring a phase complete: new files must carry them, and contract-changing edits must leave the Rationale current (see `file-headers`). - Do not blindly follow an outdated plan if the codebase contradicts it. - Wait for user confirmation before proceeding to the next phase. --- #### Reference: references/iterate-plan/references/change-template.md ```text Based on your feedback, I understand you want to: - [Change 1] - [Change 2] [If research was done] My research found: - [Relevant pattern or constraint] I plan to update the plan by: 1. [Specific modification] 2. [Specific modification] Does this align with your intent? ``` --- #### Reference: references/iterate-plan/references/common-scenarios.md ## Common Iteration Scenarios - Adding a new phase - Changing the implementation approach - Adding missing detail - Removing scope - Splitting an oversized phase - Correcting a technical error For each case: - identify the affected sections, - research only what changed, - update success criteria and dependencies if needed, - preserve completed work. --- #### Reference: references/iterate-plan/SKILL.md # Iterate Implementation Plan Update an existing implementation plan based on feedback and current codebase reality. ## Procedure 1. Read the current plan completely. 2. Understand the requested changes. 3. Research only if the requested change requires new technical context. 4. Confirm your understanding with the user before editing. 5. Make focused updates to the plan. 6. Present the changes and iterate until approved. ## Rules - Preserve completed work unless the user explicitly wants to revise it. - Prefer surgical edits over wholesale rewrites. - Ask normal clarifying questions if the request is ambiguous. - If the plan needs substantial restructuring, recommend creating a new plan. ## References - Use `references/change-template.md` when summarizing planned edits. - Use `references/common-scenarios.md` for common iteration patterns. --- #### Reference: references/plan-review/references/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: references/plan-review/references/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] ``` --- #### Reference: references/plan-review/SKILL.md # 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.