Lifecycle: draft
Implementation Planning
Purpose and scope
Choose an efficient, bounded path from acceptance criteria to a verified repository change. This skill covers decomposition, sequencing, risk, and handoffs; it does not authorize work beyond the request, replace technical design, or make an uncertain requirement disappear through planning language.
Triggers and prerequisites
Trigger when a task spans multiple files or components, has dependencies or migrations, carries security/data/release risk, or has more than one plausible implementation path. Prerequisites: stable or explicitly provisional acceptance criteria, repository model, constraints, baseline, available verification, and required approvals.
Decision criteria
- Every step must serve an acceptance criterion or reduce a stated uncertainty; activity is not progress.
- Sequence discovery and reversible experiments before expensive or irreversible changes.
- Prefer the smallest plan that covers dependencies, failure paths, verification, and recovery; do not plan speculative extensibility.
- A plan is a hypothesis about the path, not evidence that the change will work. Revise it when observations contradict its assumptions.
Procedure
- Restate the outcome, constraints, non-goals, assumptions, and evidence required for success. Resolve material ambiguity with
requirements-to-acceptance first.
- Map the change surface: files, callers, interfaces, data, dependencies, workflows, permissions, generated artifacts, and owners. Identify coupling and ordering constraints.
- Break the work into small steps with one purpose each. Mark each step as discovery, implementation, migration, verification, review, or cleanup; define its output and completion evidence.
- Identify risks and disconfirming observations for each step: hidden consumers, incompatible versions, data loss, security exposure, performance change, concurrency, irreversibility, or unavailable verification.
- Choose the sequence: baseline/reproduction, smallest safe change, focused verification, boundary checks, broader verification, review, and cleanup. Put approval gates before high-impact actions.
- Define alternatives and decision points. State when to stop, ask, revert, split the work, or route to another skill rather than continuing a failing plan.
- Implement only the current step, inspect the result, and update the plan from evidence. Do not pre-commit to later steps that the new evidence invalidates.
- At completion, compare the final diff with the plan and acceptance criteria. Record skipped steps, changed assumptions, residual uncertainty, and the next review trigger.
Examples and counterexamples
Good: For an API change with a schema migration, plan contract clarification, consumer inventory, compatible schema expansion, application change, backfill verification, rollout, and cleanup with separate evidence for each.
Bad: Plan “update API, migrate database, update tests, deploy” without ordering, compatibility, rollback, consumer, or failure criteria.
Good: If the first experiment shows the issue is dependency behavior, stop the application-code plan and route to dependency review.
Bad: Continue implementing the original plan because changing direction would make the task look incomplete.
Failure modes and recovery
If acceptance criteria are unstable, pause planning and clarify them. If dependencies or callers are unknown, add bounded discovery rather than guessing. If a step cannot be verified, narrow its claim or obtain the required environment/approval. If the plan grows with speculative branches, return to the stated outcome and remove steps that do not reduce a demonstrated risk or satisfy a criterion.
Validation evidence and provenance
Claims in this skill map to graded findings in docs/research.md:
- Explicit success definition before acting (F2, Strong): instruction misreading is the largest documented agent failure cluster (FAROS); plans restating observable outcomes counteract it.
- Staged execution with checkpoints (Q10, Moderate): mirrors release-engineering practice where staged change limits incident blast radius.
- Keeping plans selective and current (F3, Moderate): context quality beats volume.
Source boundary: planning-granularity choices are design decisions informed by these findings, not evaluated interventions.
Confidence: medium. Freshness: review when the cited findings or agent-planning evidence change.
Disconfirmation: evidence that plan overhead reduces task completion rates without improving correctness would require narrowing the procedure to high-risk changes only.
Related skills and conflicts
Related: requirements-to-acceptance, repository-exploration, skill-composition-and-routing, epistemic-coding, repository-change-verification, safe-git-workflow, and skill-quality-review. This skill does not authorize scope expansion, irreversible actions without approval, or claiming completion because a plan was written.
1---2name: implementation-planning3description: Turn verified coding requirements into a minimal, dependency-aware implementation plan with risks, verification evidence, and stopping conditions. Use before multi-file, cross-boundary, risky, or ambiguous AI coding-agent changes.4---56Lifecycle: `draft`78# Implementation Planning910## Purpose and scope1112Choose an efficient, bounded path from acceptance criteria to a verified repository change. This skill covers decomposition, sequencing, risk, and handoffs; it does not authorize work beyond the request, replace technical design, or make an uncertain requirement disappear through planning language.1314## Triggers and prerequisites1516Trigger when a task spans multiple files or components, has dependencies or migrations, carries security/data/release risk, or has more than one plausible implementation path. Prerequisites: stable or explicitly provisional acceptance criteria, repository model, constraints, baseline, available verification, and required approvals.1718## Decision criteria1920- Every step must serve an acceptance criterion or reduce a stated uncertainty; activity is not progress.21- Sequence discovery and reversible experiments before expensive or irreversible changes.22- Prefer the smallest plan that covers dependencies, failure paths, verification, and recovery; do not plan speculative extensibility.23- A plan is a hypothesis about the path, not evidence that the change will work. Revise it when observations contradict its assumptions.2425## Procedure26271. Restate the outcome, constraints, non-goals, assumptions, and evidence required for success. Resolve material ambiguity with `requirements-to-acceptance` first.282. Map the change surface: files, callers, interfaces, data, dependencies, workflows, permissions, generated artifacts, and owners. Identify coupling and ordering constraints.293. Break the work into small steps with one purpose each. Mark each step as discovery, implementation, migration, verification, review, or cleanup; define its output and completion evidence.304. Identify risks and disconfirming observations for each step: hidden consumers, incompatible versions, data loss, security exposure, performance change, concurrency, irreversibility, or unavailable verification.315. Choose the sequence: baseline/reproduction, smallest safe change, focused verification, boundary checks, broader verification, review, and cleanup. Put approval gates before high-impact actions.326. Define alternatives and decision points. State when to stop, ask, revert, split the work, or route to another skill rather than continuing a failing plan.337. Implement only the current step, inspect the result, and update the plan from evidence. Do not pre-commit to later steps that the new evidence invalidates.348. At completion, compare the final diff with the plan and acceptance criteria. Record skipped steps, changed assumptions, residual uncertainty, and the next review trigger.3536## Examples and counterexamples3738Good: For an API change with a schema migration, plan contract clarification, consumer inventory, compatible schema expansion, application change, backfill verification, rollout, and cleanup with separate evidence for each.3940Bad: Plan “update API, migrate database, update tests, deploy” without ordering, compatibility, rollback, consumer, or failure criteria.4142Good: If the first experiment shows the issue is dependency behavior, stop the application-code plan and route to dependency review.4344Bad: Continue implementing the original plan because changing direction would make the task look incomplete.4546## Failure modes and recovery4748If acceptance criteria are unstable, pause planning and clarify them. If dependencies or callers are unknown, add bounded discovery rather than guessing. If a step cannot be verified, narrow its claim or obtain the required environment/approval. If the plan grows with speculative branches, return to the stated outcome and remove steps that do not reduce a demonstrated risk or satisfy a criterion.4950## Validation evidence and provenance51Claims in this skill map to graded findings in [`docs/research.md`](../../docs/research.md):5253- Explicit success definition before acting (F2, Strong): instruction misreading is the largest documented agent failure cluster (FAROS); plans restating observable outcomes counteract it.54- Staged execution with checkpoints (Q10, Moderate): mirrors release-engineering practice where staged change limits incident blast radius.55- Keeping plans selective and current (F3, Moderate): context quality beats volume.5657Source boundary: planning-granularity choices are design decisions informed by these findings, not evaluated interventions.5859Confidence: medium. Freshness: review when the cited findings or agent-planning evidence change.6061Disconfirmation: evidence that plan overhead reduces task completion rates without improving correctness would require narrowing the procedure to high-risk changes only.62## Related skills and conflicts6364Related: `requirements-to-acceptance`, `repository-exploration`, `skill-composition-and-routing`, `epistemic-coding`, `repository-change-verification`, `safe-git-workflow`, and `skill-quality-review`. This skill does not authorize scope expansion, irreversible actions without approval, or claiming completion because a plan was written.
ChloeVPin