plan

Implementation Planning Skill

Overview

Author the ## Decomposition section of the one unified `docs/specs/` artifact — granular, parallelizable tasks tracing to the DR-N requirements in the same document's ## Design & Rationale section. There is no second file: traceability resolves within one doc. Ensures complete coverage through explicit, internal traceability. The artifact shape is owned by references/spec-template.md — author against it.

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

Triggers

Activate this skill when:

• User runs plan command
• User wants to break a spec into tasks
• A unified docs/specs/ artifact's Design & Rationale section needs decomposition
• User says "plan the implementation" or similar
• Auto-chained from ideate after the Design & Rationale section is written
• Run directly (no prior ideate): at thin/standard depth, author the whole unified spec — light/standard Design & Rationale section plus Decomposition — in one pass
• 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 exarchos:exarchos_workflow action: "update".

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 Verification Ladder

Verification depth matches blast radius. The deeper rungs add tests, an adequacy kill-probe, and integration coverage — judged by outcome, test-after, not by a universal failing-test-first law. Each task gets the cheapest verification that still captures its risk:

The planner stamps each task's riskTier (and boundaryTouching); the classifier derives it from blast radius when the planner does not override. The dispatched implementer prompt and the gate sequence both scale off that stamp — so the verification effort is data-driven, not a blanket rule.

For a high-tier task, the discipline is outcome-based (write the behavior and its tests in whatever order is natural — test-after is fine):

1. Cover the new/changed behavior with scoped tests that pin its contract
2. Let the check_test_adequacy kill-probe prove the tests can actually fail (it reverts your source and asserts at least one test goes red)
3. Add real-collaborator integration coverage across the seam

Verify high-tier test adequacy after implementation — the keeper gate (the test-FIRST ordering gate check_tdd_compliance was retired):

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

• `passed: true` — Reverting the task's source makes at least one new/changed test fail: the tests are not vacuous
• `passed: false` — A test still passes against the reverted source; strengthen it

Planning Process

Step 1: Analyze the Design & Rationale section

Read the unified spec's ## Design & Rationale section thoroughly (if ideate ran, it is already written; otherwise author it at thin/standard depth now, per references/spec-template.md). From it, extract:

• Problem Statement — Context (no tasks, but informs scope)
• Chosen Approach — Architectural decisions to implement
• Requirements (DR-N) — the provenance anchors every task must trace to
• Technical Design — Core implementation requirements
• Integration Points — Integration and glue code tasks
• Open Questions — Decisions to resolve or explicitly defer

Step 1.5: Spec Tracing (Required)

Create a traceability matrix mapping DR-N requirements to planned tasks within the unified document. Consult references/spec-tracing-guide.md for the methodology and template.

Pre-populate the matrix using the traceability generator — pass the unified docs/specs/ artifact as both designFile and planFile (DR-N is parsed from its ## Design & Rationale region, tasks from its ## Decomposition region — one file):

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

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

Step 2: Decompose into Tasks

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

Implements: DR-N and the task id are fields of the spec and of the task.completed event — that is where the provenance chain reads them. They must not be carried into code comments, which state their constraint in words and name no planning ordinal; see Ordinals are artifact metadata, not code in references/task-template.md. Write each task's verification prose as a description of the behavior to produce, so an implementer echoing that language writes the constraint rather than the ordinal.

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: Author the Decomposition section

Write the ## Decomposition section into the unified spec at docs/specs/YYYY-MM-DD-<feature>.md, using references/spec-template.md. Its ## Decomposition carries the task breakdown, with traceability resolved within this single document against the ## Design & Rationale DR-N source above it.

The legacy two-file split (references/plan-document-template.md → docs/plans/) is retained only for in-flight workflows already on the old path; new features author the one docs/specs/ artifact.

Step 5: Plan Verification

Run deterministic verification scripts instead of manual checklist review. Each takes the unified `docs/specs/` artifact as both designPath and planPath — the handlers parse DR-N from its design region and tasks from its decomposition region.

5a. Coverage — verify every Design & Rationale requirement maps to a task (the folded design-completeness acceptance-criteria check rides here now):

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

• passed: true — All requirements covered; proceed to 5a-ii
• passed: false — Gaps found; add tasks for uncovered requirements or defer with rationale
• error — Usage error or empty spec; 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/specs/<date>-<feature>.md",
  planPath: "docs/specs/<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/specs/<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 — validate the planned test paths as declarations:

exarchos_orchestrate({
  action: "spec_coverage_check",
  featureId: "<feature-id>",
  planFile: "docs/specs/<date>-<feature>.md",
  repoRoot: ".",
  coveragePhase: "plan"
})

Pass coveragePhase: "plan" here. At planning time a declared test file does not exist yet, so the check validates the path is a well-formed test-path declaration rather than requiring it on disk. Omitting the parameter falls back to post-implementation, which demands every declared file exist and its tests run — a bar no plan can clear.

• `passed: true` — Every declared test path is a valid forward declaration; plan verification complete
• `passed: false` — A declared path is not a well-formed test path; fix the paths in the plan

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

Anti-Patterns

Rationalization Debunking

The ladder already prices in genuinely low-risk work — so these excuses apply to medium/high-tier tasks, where they are rationalizations rather than reasonable tier choices:

State Management

On spec save, record the artifact and transition phase based on workflowType: feature → plan-review, refactor → overhaul-plan-review. Set artifacts.plan to the unified `docs/specs/` path — this is the key the planArtifactExists guard reads, and it points at the one unified doc (the same path ideate recorded as artifacts.spec). Artifacts and phase are two separate calls — update is non-phase mutation only; phase changes go through the HSM-guarded transition action:

action: "update", featureId: "<id>", updates: {
  "artifacts": { "plan": "docs/specs/<date>-<feature>.md" },
  "tasks": [{ "id": "001", "title": "...", "status": "pending", "branch": "...", "blockedBy": [] }, ...]
}
action: "transition", featureId: "<id>", target: "<plan-review-phase>"

Phase Transitions and Guards

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

Quick reference: The plan → plan-review transition requires guard plan-artifact-exists — set artifacts.plan to the unified docs/specs/ path before the transition call.

Schema Discovery

Use exarchos_workflow({ action: "describe", actions: ["update", "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 carries a riskTier (and boundaryTouching) stamp; medium/high-tier tasks carry adequacy-judged tests (test-after), high-tier adds the integration suite
• [ ] 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", featureId: "<feature-id>" }) passed: true
• [ ] Coverage thresholds met — exarchos_orchestrate({ action: "check_coverage_thresholds", featureId: "<feature-id>" }) passed: true:

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

• [ ] Unified spec saved to docs/specs/ (Design & Rationale + Decomposition in one doc)
• [ ] State file updated with artifacts.plan = unified spec path and tasks

Transition

After decomposition completes, auto-continue to plan-review. Transition to the appropriate review phase (feature: plan-review, refactor: overhaul-plan-review). Plan-review is no longer an inline plan-vs-design delta (one artifact now) — it is a dispatched, fresh-context, adversarial read-only pass over the unified artifact (DR-10): a clean reviewer provisioned with only {artifact + spec} (never this authoring transcript), prompted to refute the plan, its adversarial depth scaled by the frozen designDepth. Provision it via exarchos_orchestrate({ action: "prepare_review", scope: "plan", artifact: "docs/specs/<...>", designDepth: "<frozen>" }).

• Refuted (gaps): set .planReview.gaps, auto-loop back to plan --revise
• Survives: present to user for approval (the single human checkpoint)
• On approval: set .planReview.approved = true, invoke delegate

REQUIRED: Run exarchos_orchestrate({ action: "check_plan_coverage" }) over the unified artifact. If passed: false → auto-invoke plan --revise. If passed: true → transition to the plan-review phase 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

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.