| name | implementation-plan-authoring |
| description | Create precise, implementation-ready, persistent software engineering plans from requirements, project context, documentation, code, tests, architecture, and repository evidence. Use only when the user explicitly asks to create, formalize, or replan a plan, or explicitly asks to author a plan before implementation. Do not activate merely because work is non-trivial. Produces living execution documents under docs/public/plans with explicit scope, decisions, invariants, dependencies, verification gates, progress state, checkpoints, handoff state, and replan triggers so another agent can execute the work without rediscovering hidden decisions. |
Implementation Plan Authoring
Create implementation plans that function as persistent execution contracts.
A plan is not:
- a short checklist;
- a conversational summary;
- a brainstorm;
- a list of files to edit;
- a temporary planning response.
A plan must preserve enough verified context, decisions, execution state, and validation criteria for a different agent to continue the work correctly after a long interruption or context reset.
Core principle
Plan explicitly enough that execution requires implementation judgment, not architectural rediscovery.
The planner owns ambiguity reduction.
The executor may make local implementation decisions only inside boundaries explicitly left open by the plan.
Activation contract
This skill is opt-in. Activate it only when the user explicitly requests plan
authoring, plan formalization, replanning, or a plan-first workflow. Do not
create a plan automatically because a task is complex, cross-cutting,
long-running, or risky.
If the user requests work without providing a plan and the task cannot be
executed safely without one, ask whether they want a plan authored or want to
provide one. Do not author and execute a plan in the same step unless the user
explicitly authorizes both actions.
Authoring ends at READY; implementation belongs to the separate
plan-conformance-execution skill after explicit execution authorization.
1. Plan storage architecture
Use:
docs/public/plans/
├── INDEX.md
├── active/
│ ├── 2026-08-11--audio-device-recovery.md
│ └── 2026-08-14--renderer-lifecycle-refactor.md
└── archive/
├── completed/
│ └── 2026/
│ └── 08/
├── superseded/
│ └── 2026/
│ └── 08/
└── cancelled/
└── 2026/
└── 08/
Only non-terminal plans belong in active/.
Terminal plans must be archived.
Do not allow active/ to become a historical dump.
Terminal states
These states must be archived:
COMPLETEDSUPERSEDEDCANCELLED
These states remain in active/:
DRAFTREADYIN_PROGRESSBLOCKEDREPLANNING
Legacy archive exception
The root of docs/public/plans/archive/ may contain historical files whose
names begin with deprecated--. They are read-only artifacts from the former
planning system:
deprecated is a filename prefix, not a lifecycle state;- these files are not candidates for discovery, resumption, extension,
replacement, or execution;
- they remain at the archive root rather than entering a terminal-state
category;
- never apply this prefix to a new plan.
2. Plan discovery before creation
Before creating a new plan:
-
Inspect docs/public/plans/INDEX.md.
-
Inspect relevant plans under docs/public/plans/active/.
-
Search for plans matching:
- the same objective;
- the same feature;
- the same bug;
- the same subsystem;
- the same architectural migration;
- a previous version of the same work.
Do not create a new plan when an existing active plan represents the same work.
Ignore deprecated--* files during executable-plan discovery. They may be read
only as historical context when explicitly relevant.
Prefer:
- resuming it;
- extending it;
- formally replanning it.
Create a replacement only if the previous plan is no longer the correct execution contract.
When replacing a plan:
- mark the old plan
SUPERSEDED;
- record
Superseded by;
- create the replacement;
- record
Supersedes;
- move the old plan to
archive/superseded/YYYY/MM/;
- update
INDEX.md.
One-workstream rule
There should normally be only one active plan for one coherent implementation objective.
Do not create:
fix-audio-1.md
fix-audio-new.md
fix-audio-final.md
fix-audio-final-2.md
Use the plan lifecycle instead.
3. Naming
Use:
YYYY-MM-DD--short-descriptive-slug.md
Example:
2026-08-11--wasapi-device-recovery.md
Keep the filename stable while the plan remains active.
The date represents initial plan creation, not every revision.
Use a durable internal Plan ID:
PLAN-20260811-WASAPI-DEVICE-RECOVERY
The Plan ID does not change during replanning.
4. INDEX.md policy
docs/public/plans/INDEX.md is the entry point for discovering plan state.
It is a catalog, not a complete history.
Maintain:
# Implementation Plans
## Active
| Plan | Status | Area | Updated | Current step |
|---|---|---|---|---|
| [...] | IN_PROGRESS | Audio | ... | Step 4 |
## Blocked / Replanning
| Plan | Status | Reason | Updated |
|---|---|---|---|
## Recently completed
Keep only the most recent 10 completed plans here.
| Plan | Completed | Outcome |
|---|---|---|
## Archive
- Completed: `archive/completed/`
- Superseded: `archive/superseded/`
- Cancelled: `archive/cancelled/`
Do not list every historical plan individually in INDEX.md.
Historical discovery belongs to the archive hierarchy and repository search.
Whenever a plan is:
- created;
- renamed;
- started;
- blocked;
- replanned;
- completed;
- superseded;
- cancelled;
update INDEX.md in the same coherent change.
5. Public-document safety
Plans are stored under docs/public/plans.
Therefore never persist:
- passwords;
- secrets;
- access tokens;
- private keys;
- credentials;
- private customer data;
- sensitive production values;
- unnecessary machine-specific private paths.
Refer to protected information symbolically.
Example:
Use the configured signing credential.
Do not copy the credential into the plan.
6. Planning mode
Unless explicitly authorized to implement:
- inspect but do not modify production implementation;
- do not convert investigation into opportunistic coding;
- prefer read-only repository operations;
- builds, tests, analyzers, searches, diagnostics, and repository history may be used to establish facts;
- creating or updating the plan and plan index is allowed.
7. Establish authoritative context
Before designing the plan, identify and inspect the sources governing the work.
Prefer evidence in this order when applicable:
- explicit user requirements;
- project agent instructions;
- project policies;
- specifications;
- architecture documentation;
- domain documentation;
- development conventions;
- implementation;
- tests;
- build and deployment infrastructure;
- issue/history information relevant to the behavior.
Do not assume documentation and implementation agree.
When they conflict:
- record the conflict;
- determine the authoritative source using project policy;
- incorporate the resolution into the plan.
8. Separate facts, assumptions, and unknowns
Every material planning premise belongs conceptually to one of:
Confirmed
Directly supported by evidence.
Assumed
Reasonable but not yet proven.
Material assumptions should be verified before the plan becomes READY.
Unknown
Cannot currently be established.
An unresolved unknown is acceptable only if:
- it cannot reasonably be resolved during planning;
- execution can resolve it safely;
- the plan gives an explicit resolution procedure;
- different outcomes would not require materially different architecture.
Otherwise keep the plan in DRAFT or BLOCKED.
Never disguise assumptions as verified facts.
9. Reconstruct current state
Do not plan from filenames alone.
Trace the relevant behavior.
Identify as applicable:
- entry points;
- call paths;
- data flow;
- state transitions;
- ownership;
- lifecycle;
- threading;
- concurrency;
- synchronization;
- public contracts;
- internal contracts;
- persistence;
- configuration;
- external APIs;
- framework integration;
- platform behavior;
- error handling;
- tests;
- build paths;
- packaging;
- deployment consequences.
Understand why the existing implementation has its current shape before proposing its replacement.
10. Establish the repository baseline
When version control is available, record the planning baseline.
At minimum:
Branch:
HEAD revision:
Working tree state:
Baseline validation:
Do not assume a clean working tree.
Distinguish:
- pre-existing changes;
- planner-created documentation changes;
- unrelated concurrent modifications.
This baseline allows a future executor to determine whether repository reality has drifted since planning.
11. Translate requirements into obligations
Every material requirement must map through:
Requirement
↓
Design decision
↓
Implementation step
↓
Validation
↓
Completion evidence
If a requirement has no implementation consequence, explain why.
If a proposed implementation step maps to no requirement, architectural necessity, or validation requirement, reconsider whether it belongs in scope.
Assign identifiers:
R1
R2
R3
for traceability.
12. Define the execution contract
Before creating steps, define:
Objective
Describe the observable final state.
In scope
Explicit implementation surfaces and behaviors.
Out of scope
Adjacent work that must not be performed.
Design decisions
For each important decision record:
- decision;
- rationale;
- evidence;
- affected boundaries;
- consequences.
Use identifiers:
D1
D2
D3
Do not delegate major design choices to execution.
Invariants
Record properties that must remain true.
Use:
I1
I2
I3
Examples:
- public API compatibility remains unchanged;
- audio callbacks remain non-blocking;
- persistence format remains backward compatible;
- renderer ownership remains unchanged;
- no new dependency is introduced.
Executor discretion
Explicitly separate:
Allowed without replanning
Examples:
- local variable naming;
- private helper extraction;
- equivalent internal control flow;
- assertion organization;
- formatting;
- minor private implementation choices.
Locked by the plan
Normally includes:
- architecture;
- ownership;
- public APIs;
- dependency strategy;
- persistence formats;
- threading model;
- security semantics;
- lifecycle;
- externally observable behavior.
13. Build the change map
Use exact verified locations whenever possible.
| ID | Area | Location | Expected change | Requirement |
|---|---|---|---|---|
| C1 | Audio lifecycle | `AudioEngine.cs` / `RecoverAsync` | Centralize recovery sequencing | R2 |
Do not fabricate paths or symbols for specificity.
When exact location cannot yet be identified, define a bounded discovery target.
14. Determine execution dependencies
Before ordering steps determine:
- compilation dependencies;
- interface-before-implementation requirements;
- migrations;
- test baselines;
- compatibility requirements;
- generated-code dependencies;
- deployment dependencies;
- integration ordering.
Steps must follow technical dependency order.
Identify genuinely parallel work when useful.
Do not label tightly coupled changes as parallel merely because different files are involved.
15. Milestones and steps
Long plans should be divided into milestones.
Example:
Milestone 1 — Establish behavioral baseline
Milestone 2 — Introduce lifecycle contract
Milestone 3 — Migrate recovery implementation
Milestone 4 — Remove obsolete path
Milestone 5 — Full validation
Each milestone must define:
- outcome;
- included steps;
- entry conditions;
- exit conditions;
- validation gate.
Every material step must include:
Step N — Specific outcome
Status
NOT_STARTED | IN_PROGRESS | DONE | BLOCKED | INVALIDATED
Objective
Concrete result.
Requirements
IDs implemented by this step.
Location
Verified files, symbols, components, tests, configuration, or bounded discovery locations.
Changes
Actual behavior to implement.
Rationale
Why this design belongs here.
Dependencies
Previous steps or contracts required.
Invariants
Relevant invariant IDs.
Validation
Specific checks proving this step.
Completion evidence
What must be demonstrably true before marking DONE.
Allowed discretion
Local choices available to the executor.
Replan triggers
Discoveries that invalidate the step or plan.
16. Ban vague planning
Do not use standalone instructions such as:
- update the service;
- fix error handling;
- refactor;
- add tests;
- ensure compatibility;
- integrate the behavior;
- clean up implementation.
Describe:
- what changes;
- where;
- how behavior changes;
- why;
- what must not change;
- how correctness is proven.
Specificity is information density, not arbitrary verbosity.
Do not shorten a step if compression removes information required by a future executor.
17. Validation strategy
Validation is part of the implementation contract.
Plan:
- targeted tests;
- regression tests;
- integration tests;
- negative cases;
- failure paths;
- boundary conditions;
- static analysis;
- compilation;
- linting;
- packaging;
- deployment checks;
- platform-specific checks;
- manual validation when unavoidable.
For bug fixes, include a regression test whenever reasonably possible.
For behavior-preserving refactors, validation must establish behavioral parity.
Avoid relying exclusively on:
Run all tests.
Specify targeted validation first.
18. Requirement compliance matrix
Create and maintain:
## Compliance matrix
| Requirement | Implementation | Validation | State | Evidence |
|---|---|---|---|---|
| R1 | Steps 1, 2 | V1 | PENDING | — |
| R2 | Step 3 | V2, V3 | PENDING | — |
Allowed states:
PENDINGPARTIALVERIFIEDFAILEDBLOCKED
A plan cannot become COMPLETED while a required requirement remains anything other than VERIFIED.
19. State verification model
The plan must distinguish implementation status from verification status.
Use:
Repository verification state
VERIFIED
Current repository state has been reconciled with the latest checkpoint and required validation is current.
STALE
Work occurred after the latest verification checkpoint.
The repository may be correct, but the recorded evidence is no longer sufficient.
DIVERGED
Repository state differs materially from the state expected by the plan/checkpoint and has not yet been reconciled.
FAILING
Relevant validation currently fails.
BLOCKED
Verification cannot currently be completed.
Never present a plan as fully verified while its verification state is STALE, DIVERGED, FAILING, or BLOCKED.
20. Current State Snapshot
Every active plan must contain a small, continuously updated control section near the top.
Use:
## Current State Snapshot
- **Plan ID:** PLAN-...
- **Status:** READY
- **Verification state:** VERIFIED
- **Created:** YYYY-MM-DD
- **Last updated:** YYYY-MM-DD HH:MM
- **Branch/worktree:** ...
- **Baseline revision:** ...
- **Current revision:** ...
- **Active milestone:** ...
- **Active step:** ...
- **Completed steps:** 0 / N
- **Last checkpoint:** CP-...
- **Last validated checkpoint:** CP-...
- **Next action:** ...
- **Current blockers:** None
- **Open plan deviations:** None
- **Supersedes:** —
- **Superseded by:** —
This snapshot is the first place a resuming agent should inspect.
Do not make the executor reconstruct current state by reading the entire plan history.
21. Checkpoint strategy
Plans for long-running tasks must use explicit checkpoints.
Create checkpoints at least:
- when planning becomes
READY;
- before implementation starts;
- after every completed material step;
- after each milestone;
- after material validation;
- when a plan discrepancy is discovered;
- after replanning;
- before handing work to another agent or ending an execution session;
- before final completion.
Checkpoint IDs:
CP-001
CP-002
CP-003
Each checkpoint records:
### CP-003 — 2026-08-11 17:42
- **Plan status:** IN_PROGRESS
- **Verification state:** VERIFIED
- **Active milestone:** M2
- **Active step:** Step 4
- **Repository revision:** ...
- **Working tree:** ...
- **Changes since previous checkpoint:** ...
- **Validation performed:** ...
- **Validation result:** PASS
- **Conformance state:** CONFORMING
- **Open issues:** None
- **Next exact action:** ...
Do not paste full build/test logs into routine checkpoints.
Record:
- command;
- result;
- meaningful summary;
- location of external logs/artifacts when applicable.
Detailed evidence belongs only where needed.
22. Checkpoint compaction
Long-running plans may accumulate many checkpoints.
Preserve auditability without allowing routine records to dominate the document.
After completing a milestone:
- retain milestone boundary checkpoints;
- retain checkpoints associated with failures;
- retain checkpoints associated with decisions;
- retain checkpoints associated with deviations;
- retain replanning checkpoints;
- retain the latest checkpoint;
- routine successful intermediate checkpoints may be compacted into a concise milestone summary if project policy permits it.
Never compact away evidence needed to explain why a decision or deviation occurred.
23. Required living-state sections
Every long-running plan must contain:
Progress
Current milestone/step status.
Current State Snapshot
Authoritative resumability state.
Compliance Matrix
Requirements versus verified evidence.
Checkpoint Ledger
Execution snapshots.
Surprises & Discoveries
Unexpected repository or runtime facts.
Decision Log
Material decisions made after initial planning.
Plan Deviations
Conformance exceptions and their resolution.
Validation Evidence
Meaningful verification results.
Handoff Snapshot
Exact resumption instructions.
Outcomes & Retrospective
Final result after completion.
These sections are execution state, not optional commentary.
24. Surprises & Discoveries
Record material discoveries.
Use:
### DISC-003 — <short description>
**Observed:**
...
**Evidence:**
...
**Impact:**
...
**Plan effect:**
None | Local variation | Replan required
Do not record every trivial implementation observation.
Record discoveries that could matter to:
- architecture;
- correctness;
- future execution;
- validation;
- scope;
- ownership;
- lifecycle;
- compatibility.
25. Decision Log
Record post-planning material decisions.
### DEC-004 — <decision>
**Date:**
...
**Context:**
...
**Decision:**
...
**Rationale:**
...
**Affected requirements/steps:**
...
**Plan amendment required:** Yes | No
Do not silently change an original design decision.
26. Plan deviation ledger
Use:
### DEV-002 — <description>
**Detected during:** Step 4
**Classification:**
LOCAL_VARIATION | PLAN_GAP | DEVIATION_REQUIRED | PLAN_INVALID
**Expected:**
...
**Observed:**
...
**Impact:**
...
**Resolution:**
...
**Plan amendment:**
...
**Status:**
OPEN | RESOLVED
DEVIATION_REQUIRED and PLAN_INVALID normally require replanning before affected execution continues.
27. Handoff Snapshot
Before pausing long-running work or transferring execution to another agent, update:
## Handoff Snapshot
**Last safe checkpoint:** CP-...
**Current repository state:**
...
**Completed:**
...
**In progress:**
...
**Next exact action:**
...
**Do not repeat:**
...
**Pending validation:**
...
**Open discoveries:**
...
**Open decisions:**
...
**Open deviations:**
...
**Known blockers:**
...
**Files currently relevant:**
...
**Commands needed to resume verification:**
...
Avoid vague handoffs such as:
Continue Step 4.
The next action must be specific enough to resume directly.
28. Replan triggers
Explicitly identify conditions requiring replanning.
Typical triggers:
- required abstraction does not exist;
- ownership differs materially;
- API lacks necessary capability;
- dependency strategy fails;
- public API must change unexpectedly;
- migration becomes necessary;
- tests establish an incompatible invariant;
- concurrency assumptions are invalid;
- performance constraints invalidate design;
- security constraints invalidate design;
- lifecycle differs from expected;
- significant out-of-scope work becomes mandatory.
Replanning is a valid state transition, not execution failure.
29. Plan lifecycle
Use:
DRAFT
↓
READY
↓
IN_PROGRESS
├──→ BLOCKED
├──→ REPLANNING
│ ↓
│ READY / IN_PROGRESS
├──→ SUPERSEDED
├──→ CANCELLED
↓
COMPLETED
DRAFT → READY
Allowed only after the quality gate passes.
READY → IN_PROGRESS
Occurs when execution begins.
IN_PROGRESS → REPLANNING
Use when plan validity must be reconsidered.
IN_PROGRESS → COMPLETED
Allowed only after final validation and compliance audit.
30. Archival policy
When a plan reaches a terminal state, remove it from active/.
Completed
Move:
docs/public/plans/active/<plan>.md
to:
docs/public/plans/archive/completed/YYYY/MM/<plan>.md
Superseded
Move to:
archive/superseded/YYYY/MM/
Cancelled
Move to:
archive/cancelled/YYYY/MM/
Then update INDEX.md.
Do not create a separate archival copy while leaving the original active file behind.
The terminal plan itself remains the historical source of truth.
Historical deprecated--* files at the archive root are a migration exception
only. They are not completed, superseded, or cancelled plans under this
lifecycle and must never be moved into those categories by authoring work.
31. Completion requirements
A plan may become COMPLETED only if:
- all required steps are
DONE;
- all requirements are
VERIFIED;
- final targeted validation passes;
- required regression validation passes;
- relevant invariants are confirmed;
- no unresolved
PLAN_GAP exists;
- no unresolved
DEVIATION_REQUIRED exists;
- no unresolved
PLAN_INVALID exists;
- required documentation is complete;
- outcomes are recorded;
- final checkpoint exists;
- verification state is
VERIFIED.
32. Required plan structure
Use this structure unless project policy defines a stricter one.
# Plan: <name>
## Current State Snapshot
...
## Objective
...
## Context and Evidence
...
## Repository Baseline
...
## Requirements
...
## In Scope
...
## Out of Scope
...
## Design Decisions
...
## Invariants
...
## Executor Discretion
### Allowed without replanning
...
### Locked by the plan
...
## Change Map
...
## Dependency Map
...
# Execution Plan
## Milestone 1 — ...
...
### Step 1 — ...
...
# Verification and State
## Validation Strategy
...
## Compliance Matrix
...
## Replan Triggers
...
## Risks
...
# Living Execution Record
## Progress
...
## Checkpoint Ledger
...
## Surprises & Discoveries
...
## Decision Log
...
## Plan Deviations
...
## Validation Evidence
...
## Handoff Snapshot
...
# Completion
## Completion Criteria
...
## Outcomes & Retrospective
...
33. Initial READY checkpoint
Before handing the plan to execution:
- complete the plan;
- run the quality gate;
- set status
READY;
- set verification state
VERIFIED;
- create
CP-001;
- populate the Handoff Snapshot;
- update
INDEX.md.
The plan is then safe for another agent to consume.
Authoring ends at this boundary. When implementation is authorized, hand the
persisted active plan to plan-conformance-execution; do not execute the plan
inside this authoring workflow.
34. Quality gate
Before marking READY, verify:
The final test is:
Could a new executor resume this work after losing the planner's conversation context without reconstructing a missing architectural or behavioral decision?
If not, the plan is not ready.
