plan-delta

# Implementation Plan Workflow Create an implementation plan for a specific delta. ## Input Delta ID from: $ARGUMENTS (e.g., "DLT-001") ## Context **You must load the following skills and read the following files before proceeding.** ### Skills - `katachi:framework-core` - Workflow principles - `katachi:working-on-delta` - Per-feature workflow - `katachi:research-docs` - Awareness of documentation research workflow ### Delta inventory - `docs/planning/DELTAS.md` - Delta definitions ### Delta documents - `docs/delta-specs/$ARGUMENTS.md` - What to build (requirements) - `docs/delta-designs/$ARGUMENTS.md` - Why/how (design rationale) ### Project decisions - `docs/architecture/README.md` - Architecture decisions (ADRs) - `docs/design/README.md` - Design patterns (DES) ### Feature documentation (for reconciliation planning) - Read affected feature specs from delta-spec's "Detected Impacts" section - Read affected feature designs from delta-design's "Detected Impacts" section - Plan should note which feature docs will need reconciliation after implementation ### Existing plan (if present) - `docs/delta-plans/$ARGUMENTS.md` - Current plan to update or create ### Template - `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/implementation-plan.md` - Structure to follow ## Pre-Check Verify spec and design exist: - If `docs/delta-specs/$ARGUMENTS.md` doesn't exist, suggest `/katachi:spec-delta $ARGUMENTS` first - If `docs/delta-designs/$ARGUMENTS.md` doesn't exist, suggest `/katachi:design-delta $ARGUMENTS` first - Plan requires both spec and design ## Process ### 1. Check Existing State If `docs/delta-plans/$ARGUMENTS.md` exists: - Read current plan - Check for drift: Have spec or design changed? - Summarize: batches, steps, context entries - Ask: "What aspects need refinement? Or should we review the whole plan?" - Enter iteration mode as appropriate If no plan exists: proceed with initial creation Update status: ```bash python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status set $ARGUMENTS "⧗ Plan" ``` ### 2. Research Phase (Silent) - Read delta spec (`docs/delta-specs/$ARGUMENTS.md`) - Read delta design (`docs/delta-designs/$ARGUMENTS.md`) - Read relevant ADRs and DES patterns (not just indexes) - Read dependency code as needed - Explore codebase for implementation patterns - Build complete understanding without asking questions ### 3. Scope Batches (Present All at Once) Identify natural implementation boundaries and define all batches. Present them together to the user for validation before expanding any steps. For each batch, define: - **Scope name**: What part of the feature it covers (model layer, service logic, API endpoint, frontend, etc.) - **Context & Research list**: Specific entries with reasoning — project docs (spec sections, design sections, ADRs, DES), code files to read, and external research pointers (library docs, existing patterns to investigate). Each entry must explain *why* it's needed for this batch. When a batch involves external libraries or frameworks, include a research pointer directing the implementing agent to follow the `katachi:research-docs` skill guidance for those libraries to verify current APIs before writing code. - **Out of scope**: What this batch explicitly does not cover - **Dependencies**: Which batches must complete before this one starts (`Depends on:` field) Present the batch definitions to the user. The user validates: - Batch boundaries make sense (logical grouping, clear scope) - Context is appropriately scoped (not too broad, not missing obvious things) - Dependencies and ordering are correct - Research pointers are concrete and relevant Iterate on batch definitions until the user approves them. ### 4. Expand Steps and Research (Silent) For each batch, draft the implementation details: **Steps:** - Draft implementation steps following the same granularity rules as before (atomic, verifiable, in dependency order) - Each step specifies: files to create/modify, what to do, how to verify **Research pointers:** - Identify where the implementing agent should look things up (library docs, patterns to extend, design questions to investigate) - Add these as entries in the batch's Context & Research list - Re-check: does this batch's context actually match its steps? Add missing entries, remove entries that don't apply **Code snippets:** - Use snippets to indicate implementation points (where to add code) - Include brief comments explaining what should happen at each point - Do NOT include complete implementation logic - The implementation agent has access to spec, design, ADRs, and DES patterns — the plan provides structural guidance, not code Example of appropriate snippet usage: ```python # In src/services/auth.py, after the existing validate_token function: # Add new function here to handle token refresh # - Should follow DES-002 error handling pattern # - Must validate refresh token expiry per spec AC-3 ``` ### 5. External Validation (Silent) Dispatch the plan-reviewer agent to validate the complete plan: ```python Task( subagent_type="katachi:plan-reviewer", prompt=f""" Review this implementation plan. ## Delta Spec {spec_content} ## Delta Design {design_content} ## Implementation Plan {plan_content} ## Relevant ADR/DES Summaries {adr_des_summaries} """ ) ``` ### 6. Apply Validation Feedback (Silent) Review the plan-reviewer findings and apply improvements: - Address coverage gaps (missing acceptance criteria) - Fix dependency ordering issues between steps and between batches - Fix batch context scoping issues (over-scoped or under-scoped entries) - Resolve ADR/DES conflicts - Incorporate suggested improvements If the reviewer identified critical issues that require clarification, note them for discussion with the user. ### 7. Finalize Save the plan to `docs/delta-plans/$ARGUMENTS.md`. Update status: ```bash python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status set $ARGUMENTS "✓ Plan" ``` Present summary of the completed plan: ``` "Delta plan complete for $ARGUMENTS. Batches: - [Batch 1 scope name]: [one-line description] - [Batch 2 scope name]: [one-line description] - ..." ``` ## Workflow **This is a validate-first process with progressive disclosure:** - Research silently, then scope batches - Present all batches for user validation - Expand steps silently for all batches - Validate complete plan (batches + steps) with plan-reviewer agent - Apply validation feedback - Save and present summary