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:

Set
```
planReview.revisionsExhausted = true
```
Output: "Plan revision failed after 3 attempts. Design may be incomplete."
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:

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

Verify TDD compliance in git history after implementation:

typescript

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:

typescript

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:

Foundation first (types, interfaces, data structures)
Core behaviors second
Edge cases and error handling third
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:

typescript

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:

typescript

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:

typescript

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:

typescript

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:

typescript

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.

implementation-planning

NPX Install

Tags

SKILL.md Content

Implementation Planning Skill

Overview

Triggers

Revision Mode (--revise flag)

Revision Loop Guard

The Iron Law

Planning Process

Step 1: Analyze Design Document

Step 1.5: Spec Tracing (Required)

Step 2: Decompose into Tasks

Step 3: Identify Parallelization

Step 4: Generate Plan Document

Step 5: Plan Verification

Anti-Patterns

Rationalization Debunking

State Management

Phase Transitions and Guards

Schema Discovery

Completion Criteria

Transition

Exarchos Integration

Troubleshooting

Performance Notes