plan-delta

What this skill does

# 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