Drafting Plans
A plan is an implementation map, not a record of planning ceremony. Make it resumable and specific while including only sections the work needs.
Start With Evidence
- Inspect existing plan conventions and relevant code, docs, schemas, configuration, issue, or PR context before naming contracts or commands.
- Update an existing plan in place when it already owns the work.
- Put the plan where the user asked. Preserve repository metadata and formatting conventions; do not invent frontmatter, lifecycle fields, or dates when the repository does not require them.
- Verify cheap, drift-prone facts before presenting them as current state.
Default Shape
Follow repository convention first. Otherwise use the smallest useful subset of:
- Problem / why: the current limitation and why it matters.
- Proposed approach: the intended behavior, important contracts, and ownership boundaries.
- Scope and non-goals: what this work will and deliberately will not solve.
- Delivery slices: independently reviewable steps, starting with the smallest useful slice.
- Decisions, risks, or open questions: only items that affect implementation or sequencing.
Omit empty headings. Add rollout, migration, safety, compatibility, observability, verification, backend notes, or progress sections only when the change actually needs them.
Resolve Decisions
- Answer questions from repository evidence when practical.
- For blocking questions that need user judgement, recommend a default and explain the tradeoff briefly. Ask a small concrete batch rather than presenting an inert question list.
- Record settled decisions in the relevant part of the plan. Leave an open question only when it still affects later work, and say what must resolve it.
Pressure-Test Proportionally
Pressure-test when the user asks or when the plan is materially risky, cross-cutting, expensive to reverse, migration-heavy, security-sensitive, or operationally complex. Check whether the work should be smaller, deferred, deleted, or built on an existing mechanism.
Integrate useful findings into scope, approach, risks, or slices. Do not automatically add a “Key Learnings,” alternatives, risk matrix, or adversarial-review section.
Delivery And Maintenance
- Put prerequisites before dependent work and make each slice useful or correctness-preserving on its own.
- Keep the first slice boring and concrete. Do not design later phases in more detail than the next actionable slice.
- Include exact files, contracts, examples, commands, and checks only when they make implementation less ambiguous.
- Update the plan when implementation changes scope, contracts, risks, sequencing, or progress. Remove stale assumptions and resolved questions rather than appending a changelog.
- When asked for the first or next slice, identify it from the plan and proceed to implementation when authorized instead of reopening the design.
Style
Use direct engineering prose, short paragraphs, and focused bullets. Avoid generic architecture filler, speculative abstractions, decorative examples, and compatibility scaffolding without a present requirement.
1---2name: drafting-plans3description: Drafts and revises concise, durable engineering plans. Use for `docs/plans`, architecture, rollout or design docs, first-slice selection, open-question resolution, plan review, or plan maintenance during implementation.4---56# Drafting Plans78A plan is an implementation map, not a record of planning ceremony. Make it resumable and specific while including only sections the work needs.910## Start With Evidence1112- Inspect existing plan conventions and relevant code, docs, schemas, configuration, issue, or PR context before naming contracts or commands.13- Update an existing plan in place when it already owns the work.14- Put the plan where the user asked. Preserve repository metadata and formatting conventions; do not invent frontmatter, lifecycle fields, or dates when the repository does not require them.15- Verify cheap, drift-prone facts before presenting them as current state.1617## Default Shape1819Follow repository convention first. Otherwise use the smallest useful subset of:20211. **Problem / why**: the current limitation and why it matters.222. **Proposed approach**: the intended behavior, important contracts, and ownership boundaries.233. **Scope and non-goals**: what this work will and deliberately will not solve.244. **Delivery slices**: independently reviewable steps, starting with the smallest useful slice.255. **Decisions, risks, or open questions**: only items that affect implementation or sequencing.2627Omit empty headings. Add rollout, migration, safety, compatibility, observability, verification, backend notes, or progress sections only when the change actually needs them.2829## Resolve Decisions3031- Answer questions from repository evidence when practical.32- For blocking questions that need user judgement, recommend a default and explain the tradeoff briefly. Ask a small concrete batch rather than presenting an inert question list.33- Record settled decisions in the relevant part of the plan. Leave an open question only when it still affects later work, and say what must resolve it.3435## Pressure-Test Proportionally3637Pressure-test when the user asks or when the plan is materially risky, cross-cutting, expensive to reverse, migration-heavy, security-sensitive, or operationally complex. Check whether the work should be smaller, deferred, deleted, or built on an existing mechanism.3839Integrate useful findings into scope, approach, risks, or slices. Do not automatically add a “Key Learnings,” alternatives, risk matrix, or adversarial-review section.4041## Delivery And Maintenance4243- Put prerequisites before dependent work and make each slice useful or correctness-preserving on its own.44- Keep the first slice boring and concrete. Do not design later phases in more detail than the next actionable slice.45- Include exact files, contracts, examples, commands, and checks only when they make implementation less ambiguous.46- Update the plan when implementation changes scope, contracts, risks, sequencing, or progress. Remove stale assumptions and resolved questions rather than appending a changelog.47- When asked for the first or next slice, identify it from the plan and proceed to implementation when authorized instead of reopening the design.4849## Style5051Use direct engineering prose, short paragraphs, and focused bullets. Avoid generic architecture filler, speculative abstractions, decorative examples, and compatibility scaffolding without a present requirement.
lox