implementation-planning

Implementation Planning Skill

Overview

Transform design documents into TDD-based implementation plans with granular, parallelizable tasks. Ensures complete spec coverage through explicit traceability.

For a complete worked example, see references/worked-example.md.

Triggers

Activate this skill when:

• User runs /plan command
• User wants to break down a design into tasks
• A design document exists and needs implementation steps
• User says "plan the implementation" or similar
• Auto-chained from /ideate after design completion
• Auto-chained from plan-review with --revise flag (gaps found)

Revision Mode (--revise flag)

When invoked with --revise, plan-review found gaps. Read .planReview.gaps from state, re-read the design, add tasks to address each gap, update the plan file, then clear gaps via mcp__exarchos__exarchos_workflow action: "set".

Revision Loop Guard

Max revisions: 3 per plan.

After 3 failed revisions:

1. Set planReview.revisionsExhausted = true
2. Output: "Plan revision failed after 3 attempts. Design may be incomplete."
3. Escalate: Suggest /ideate --redesign to revisit design

MANDATORY: Before accepting any rationalization for skipping tests, planning, or TDD steps, consult references/rationalization-refutation.md. Every common excuse is catalogued with a counter-argument and the correct action.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Every implementation task MUST:

1. Start with writing a failing test
2. Specify the expected failure reason
3. Only then implement minimum code to pass

Verify TDD compliance in git history after implementation:

exarchos_orchestrate({
  action: "check_tdd_compliance",
  featureId: "<featureId>",
  taskId: "<taskId>",
  branch: "feature/<name>"
})

• passed: true — All commits have test files before or alongside implementation
• passed: false — Violations found; commits have implementation without corresponding tests

Planning Process

Step 1: Analyze Design Document

Read the design document thoroughly. For each major section, extract:

• Problem Statement — Context (no tasks, but informs scope)
• Chosen Approach — Architectural decisions to implement
• Technical Design — Core implementation requirements
• Integration Points — Integration and glue code tasks
• Testing Strategy — Test coverage requirements
• Open Questions — Decisions to resolve or explicitly defer

Step 1.5: Spec Tracing (Required)

Create a traceability matrix mapping design sections to planned tasks. Consult references/spec-tracing-guide.md for the methodology and template.

Pre-populate the matrix using the traceability generator script:

exarchos_orchestrate({
  action: "generate_traceability",
  designFile: "docs/designs/<feature>.md",
  planFile: "docs/plans/<date>-<feature>.md",
  output: "docs/plans/<date>-<feature>-traceability.md"
})

• passed: true — Matrix generated; review and fill in "Key Requirements" column
• passed: false — Parse error; design document may lack expected ##/### headers

Step 2: Decompose into Tasks

Each task follows the TDD format in references/task-template.md.

Granularity Guidelines:

• Each task: 2-5 minutes of focused work
• One test = one behavior
• Prefer many small tasks over few large ones

Assign a testingStrategy to each task using references/testing-strategy-guide.md to control which verification techniques agents apply. Auto-determine propertyTests and benchmarks flags by matching each task's description and file paths against the category tables — do not leave these for the implementer to decide.

Task Ordering:

1. Foundation first (types, interfaces, data structures)
2. Core behaviors second
3. Edge cases and error handling third
4. Integration and glue code last

Step 3: Identify Parallelization

Analyze dependencies to find sequential chains and parallel-safe groups that can run simultaneously in worktrees.

Step 4: Generate Plan Document

Save to: docs/plans/YYYY-MM-DD-<feature>.md Use the template from references/plan-document-template.md.

Step 5: Plan Verification

Run deterministic verification scripts instead of manual checklist review.

5a. Design-to-plan coverage — verify every Technical Design subsection maps to a task:

exarchos_orchestrate({
  action: "check_plan_coverage",
  featureId: "<id>",
  designPath: "docs/designs/<feature>.md",
  planPath: "docs/plans/<date>-<feature>.md"
})

• passed: true — All design sections covered; proceed to 5a-ii
• passed: false — Gaps found; add tasks for uncovered sections or defer with rationale
• error — Usage error or empty design; check arguments

5a-ii. Provenance chain verification — verify every DR-N requirement maps to a task via Implements: field:

exarchos_orchestrate({
  action: "check_provenance_chain",
  featureId: "<id>",
  designPath: "docs/designs/<feature>.md",
  planPath: "docs/plans/<date>-<feature>.md"
})

• passed: true — All DR-N requirements traced; proceed to 5b
• passed: false — Block: gaps or orphan references found. Add **Implements:** DR-N to tasks for each uncovered requirement before proceeding. Every DR-N requirement MUST trace to at least one task.
• error — No DR-N identifiers in design (exit 2); if design doesn't use DR-N identifiers, this check is skipped (exempt)

5a-iii. D5: Task decomposition quality (advisory) — verify each task has clear description, file targets, and test expectations; dependency graph is a valid DAG; parallelizable tasks don't modify the same files:

exarchos_orchestrate({
  action: "check_task_decomposition",
  featureId: "<id>",
  planPath: "docs/plans/<date>-<feature>.md"
})

• passed: true — All tasks well-decomposed; proceed to 5b
• passed: false — Findings recorded as D5 gate events for the ConvergenceView. Present findings to the user for awareness but do not block plan approval.
• error — Input error (missing file, no task headers); check arguments

Advisory: This gate verifies task structure quality but does not block plan approval. Findings are recorded for convergence tracking.

5b. Spec coverage check — verify planned test files exist and pass:

exarchos_orchestrate({
  action: "spec_coverage_check",
  planFile: "docs/plans/<date>-<feature>.md",
  repoRoot: ".",
  threshold: 80
})

• passed: true — All planned tests found and passing; plan verification complete
• passed: false — Missing test files or test failures; create missing tests or fix failures

For reference, consult references/spec-tracing-guide.md for the underlying methodology.

Anti-Patterns

Don't	Do Instead
Write implementation first	Write failing test first
Create large tasks	Break into 2-5 min chunks
Skip dependency analysis	Identify parallel opportunities
Vague test descriptions	Specific: Method_Scenario_Outcome
Assume tests pass	Verify each test fails first
Add "nice to have" code	Only what the test requires

Rationalization Debunking

Excuse	Reality
"This is too simple for tests"	Simple code breaks too. Test it.
"I'll add tests after"	You won't. Or they'll be weak.
"Tests slow me down"	Debugging without tests is slower.
"The design is obvious"	Obvious to you now. Not in 3 months.

State Management

On plan save, transition phase based on workflowType: feature → plan-review, refactor → overhaul-plan-review.

action: "set", featureId: "<id>", phase: "<plan-review-phase>", updates: {
  "artifacts": { "plan": "<plan-file-path>" },
  "tasks": [{ "id": "001", "title": "...", "status": "pending", "branch": "...", "blockedBy": [] }, ...]
}

Phase Transitions and Guards

For the full transition table, consult @skills/workflow-state/references/phase-transitions.md.

Quick reference: The plan → plan-review transition requires guard plan-artifact-exists — set artifacts.plan in the same set call as phase.

Schema Discovery

Use exarchos_workflow({ action: "describe", actions: ["set", "init"] }) for parameter schemas and exarchos_workflow({ action: "describe", playbook: "feature" }) (or "debug", "refactor") for phase transitions, guards, and playbook guidance. Use exarchos_orchestrate({ action: "describe", actions: ["check_plan_coverage", "check_provenance_chain"] }) for orchestrate action schemas.

Completion Criteria

• Design document read and understood
• Spec traceability table created (exarchos_orchestrate({ action: "generate_traceability" }))
• Scope declared (full or partial with rationale)
• Tasks decomposed to 2-5 min granularity
• Each task starts with failing test
• Dependencies mapped
• Parallel groups identified
• Plan verification passed — exarchos_orchestrate({ action: "check_plan_coverage" }) returns passed: true
• Provenance chain checked — exarchos_orchestrate({ action: "check_provenance_chain" }) passed (blocking; gaps must be resolved before proceeding)
• Task decomposition checked — exarchos_orchestrate({ action: "check_task_decomposition" }) run (advisory; findings presented but non-blocking)
• Spec coverage check passed — exarchos_orchestrate({ action: "spec_coverage_check" }) passed: true
• Coverage thresholds met — exarchos_orchestrate({ action: "check_coverage_thresholds" }) passed: true:

exarchos_orchestrate({
  action: "check_coverage_thresholds",
  coverageFile: "coverage/coverage-summary.json",
  lineThreshold: 80,
  branchThreshold: 70,
  functionThreshold: 100
})

• Plan saved to docs/plans/
• State file updated with plan path and tasks

Transition

After planning completes, auto-continue to plan-review (delta analysis). Set .phase to the appropriate review phase (feature: plan-review, refactor: overhaul-plan-review). Plan-review compares design sections against planned tasks:

• Gaps found: set .planReview.gaps, auto-loop back to /plan --revise
• No gaps: present to user for approval (human checkpoint)
• On approval: set .planReview.approved = true, invoke /delegate

REQUIRED: Run exarchos_orchestrate({ action: "check_plan_coverage" }). If passed: false → auto-invoke /plan --revise. If passed: true → continue to the plan-review phase (feature: plan-review, refactor: overhaul-plan-review) and only invoke /delegate after plan-review approval.

Exarchos Integration

Phase transitions auto-emit workflow.transition events via exarchos_workflow set. No manual exarchos_event append needed.

Troubleshooting

Issue	Cause	Resolution
check_plan_coverage returns passed: false	Design sections not mapped to tasks	Add tasks for uncovered sections or add explicit deferral rationale
spec_coverage_check passed: false	Planned test files missing or failing	Create missing test stubs, verify file paths in plan match actual paths
generate_traceability passed: false	Design doc missing expected ##/### headers	Verify design uses standard Markdown headings
Revision loop (3+ attempts)	Persistent gaps between design and plan	Set planReview.revisionsExhausted = true, suggest /ideate --redesign

Performance Notes

• Complete each step fully before advancing — quality over speed
• Do not skip validation checks even when the change appears trivial
• Trace every design section to at least one task. Do not leave uncovered sections without explicit rationale.