Skip to content
Skills Library
Programming · Planning

plan

/plan

Decompose the unified docs/specs/ artifact into parallelizable tasks — the ## Decomposition section of the same document whose ## Design & Rationale section holds the DR-N source. Triggers: 'plan implementation', 'create tasks from spec', or /plan. Applies the verification ladder: verification depth matches each task's blast radius — static analysis for low-risk tasks, scoped tests plus a kill-probe for medium, the integration suite on top for high-risk surfaces (judged test-after, not test-first ordering). Auto-chained from /ideate, or run directly to author the whole unified spec at thin/sta

Repository
exarchos ↗
Licence
Apache-2.0
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Decompose the unified docs/specs/ artifact into parallelizable tasks — the ## Decomposition section of the same document whose ## Design & Rationale section holds the DR-N source. Triggers: 'plan implementation', 'create tasks from spec', or /plan. Applies the verification ladder: verification depth matches each task's blast radius — static analysis for low-risk tasks, scoped tests plus a kill-probe for medium, the integration suite on top for high-risk surfaces (judged test-after, not test-first ordering). Auto-chained from /ideate, or run directly to author the whole unified spec at thin/sta

Triggers from the description

plan implementationcreate tasks from spec
Original author description

Decompose the unified docs/specs/ artifact into parallelizable tasks — the ## Decomposition section of the same document whose ## Design & Rationale section holds the DR-N source. Triggers: 'plan implementation', 'create tasks from spec', or /plan. Applies the verification ladder: verification depth matches each task's blast radius — static analysis for low-risk tasks, scoped tests plus a kill-probe for medium, the integration suite on top for high-risk surfaces (judged test-after, not test-first ordering). Auto-chained from /ideate, or run directly to author the whole unified spec at thin/sta

How it works

  1. Overview
  2. Triggers
  3. Revision Mode (--revise flag)
  4. The Verification Ladder
  5. Planning Process
  6. Anti-Patterns
  7. Rationalization Debunking
  8. State Management
  9. Completion Criteria
  10. Transition
Original SKILL.md headings · 308 lines, 2,468 words
SKILL.md preview
---
name: plan
description: "Decompose the unified docs/specs/ artifact into parallelizable tasks — the ## Decomposition section of the same document whose ## Design & Rationale section holds the DR-N source. Triggers: 'plan implementation', 'create tasks from spec', or /plan. Applies the verification ladder: verification depth matches each task's blast radius — static analysis for low-risk tasks, scoped tests plus a kill-probe for medium, the integration suite on top for high-risk surfaces (judged test-after, not test-first ordering). Auto-chained from /ideate, or run directly to author the whole unified spec at thin/standard depth. Do NOT use for brainstorming, debugging, or code review."
metadata:
  author: exarchos
  version: 2.0.0
  mcp-server: exarchos
  category: workflow
  phase-affinity: 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:

| Risk tier | What it adds | Why |
|-----------|--------------|-----|
| **low** | Static analysis (typecheck + lint) suffices | A docs/config/rename-only edit has near-zero blast radius; a test ceremony is pure overhead. |
| **medium** | Scoped tests + the `check_test_adequacy` kill-probe | The kill-probe recaptures test-first's one real guarantee — that a test can actually fail — at lower cost, judged test-after instead of mandating a failing test first on every commit. |
| **high** | The integration suite (and mutation-adequacy at the boundary) on top of medium | Schema/type/API/shared-contract surfaces span the codebase; here adequacy-judged coverage plus real-collaborator integration across the seam earns its cost. |

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). Pass `repoRoot: "auto"` and the worktree of the task. The probe reverts and then restores the source of the tree it runs in. Without these two fields, that tree is the directory of the server, usually your own checkout. Also pass `baseBranch`, the branch the task forked from. Without it, the gate blocks with `base-missing`:

```typescript
exarchos_orchestrate({
  action: "check_test_adequacy",
  featureId: "<featureId>",
  taskId: "<taskId>",
  branch: "feature/<name>",
  baseBranch: "<branch the task forked from>",
  repoRoot: "auto",
  worktreePath: "<worktreePath>",
  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):

```typescript
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):

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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

| Don't | Do Instead |
|-------|------------|
| Ship medium/high-tier behavior with no tests | Cover it with adequacy-judged tests (test-after is fine) |
| Mandate red-green-refactor on every task | Scale verification to the task's `riskTier`; RGR is a high-tier opt-in |
| Create large tasks | Break into 2-5 min chunks |
| Skip dependency analysis | Identify parallel opportunities |
| Vague test descriptions | Specific: Method_Scenario_Outcome |
| Assume your tests can fail | Let `check_test_adequacy` prove they can (revert source, re-run, expect red) |
| Add "nice to have" code | Only what the behavior requires |

## 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:

| Excuse | Reality |
|--------|---------|
| "This is too simple for a test" (on a medium/high-tier task) | If it touches a high-blast surface, its tier is not low. Test it at the tier the ladder assigns. |
| "I'll add tests after" | You won't. Or they'll be weak — and `check_test_adequacy` will catch tests that can't fail. |
| "Tests slow me down" | Debugging an untested medium/high-tier change is slower. |
| "The design is obvious" | Obvious to you now. Not in 3 months. |

## 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:

```text
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:

```typescript
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

| 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.
Files in this package (8)
  • SKILL.md 19 KB
  • references/plan-document-template.md 1 KB
  • references/rationalization-refutation.md 2 KB
  • references/spec-template.md 6 KB
  • references/spec-tracing-guide.md 2 KB
  • references/task-template.md 8 KB
  • references/testing-strategy-guide.md 14 KB
  • references/worked-example.md 4 KB

Versions

RepositoryScoreLicence
This page · lvlup-sw/exarchos100Apache-2.0
mlophez/polix-ai100Apache-2.0
jeremylongshore/tons-of-skills-marketplace100MIT
duronext/jig100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
xoai/sage100MIT
JoDi-27/JoDi-SDD100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version f105e8751cd9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ideate
    Collaborative design exploration that authors the Design & Rationale section of the one unified docs/specs/ spec. Triggers: 'brainstorm', 'ideate', 'explore options', or /ideate. Default is a one-pass design preamble; the deep rung gates the 2-3 approach divergent loop and the…
  • 100ideate
    Collaborative design exploration that authors the Design & Rationale section of the one unified docs/specs/ spec. Triggers: 'brainstorm', 'ideate', 'explore options', or /ideate. Default is a one-pass design preamble; the deep rung gates the 2-3 approach divergent loop and the…
  • 91create-tasks
    Generate Claude Code native Tasks from an existing spec. Use when user says "create tasks", "generate tasks from spec", "spec to tasks", "task generation", or wants to decompose a spec into implementation tasks.
  • 90qa-author-by-task
    QA-Author by-task mode procedure. Use when QA-Author is dispatched for a master-plan task after TL, and after design-confirmed for UI tasks, to author task-scoped structural/api/e2e/functional test cases under docs/test-cases/by-task/<task-id>/ and coordinate visual-spec generation for UI tasks.
  • 100spec
    Write the implementation spec for one feature or roadmap task at docs/specs/NNN_<feature>.md — problem, design, affected files, flag, and verification criteria with concrete inputs and outputs — and slice it into independently mergeable pieces when it is more than one concern.…
  • 90close-spec
    When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale — the why, the principles, the invariants — pointing back to the real code for…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.