Plan a Change
Create a plan another engineer can execute without rediscovering the system.
Protocol
- Read repository instructions and inspect worktree state. Preserve unrelated
user changes.
- Restate the desired observable behavior, non-goals, and acceptance criteria.
Infer only low-risk details; surface choices that materially change scope,
compatibility, data, security, or user experience.
- Trace the current path from entry point to terminal effect. Locate runtime
wiring, domain logic, state, tests, configuration, and operational controls.
- Identify the behavioral delta and invariants that must remain true. Include
error, retry, authorization, concurrency, and rollback paths only when
touched.
- Select the smallest coherent design. Explain important alternatives and why
they lose in this repository; omit decorative option lists.
- Order steps by dependency and proof. Each step must name concrete files or
symbols, the logic change, its contract with adjacent code, and verification.
- Include data/schema transition, compatibility, rollout, observability, and
rollback steps when relevant. Never hide them under “update config.”
- Re-read the plan against acceptance criteria. Ensure every criterion maps to
implementation and verification, and every risky mutation has a recovery
path.
Plan quality bar
- Cite
path:line evidence for the current architecture and chosen edit points.
- Separate facts, decisions, assumptions, and unresolved questions.
- Avoid steps like “implement feature,” “add tests,” or “handle errors.” State
which behavior changes, where, and how it is proven.
- Keep task granularity aligned with independently verifiable outcomes, not
arbitrary file-by-file edits.
- Do not include code unless a small interface sketch resolves ambiguity.
Output
Use references/implementation-plan.md. Lead with the approach and key
decisions, then provide ordered implementation slices, verification, and
rollout. If one unresolved decision would produce substantially different
plans, stop and ask for it rather than pretending the branches are equivalent.
1---2name: plan-change3description: Produce an implementation-ready plan for a software change by inspecting the actual repository, tracing affected execution paths, resolving material design decisions, and defining verification and rollout evidence. Use when the user asks for an implementation plan, technical approach, task breakdown, design proposal grounded in an existing codebase, or wants to know how a feature or fix should be built before editing begins. Do not use for generic product roadmaps or when the user has asked to implement immediately.4---56# Plan a Change78Create a plan another engineer can execute without rediscovering the system.910## Protocol11121. Read repository instructions and inspect worktree state. Preserve unrelated13 user changes.142. Restate the desired observable behavior, non-goals, and acceptance criteria.15 Infer only low-risk details; surface choices that materially change scope,16 compatibility, data, security, or user experience.173. Trace the current path from entry point to terminal effect. Locate runtime18 wiring, domain logic, state, tests, configuration, and operational controls.194. Identify the behavioral delta and invariants that must remain true. Include20 error, retry, authorization, concurrency, and rollback paths only when21 touched.225. Select the smallest coherent design. Explain important alternatives and why23 they lose in this repository; omit decorative option lists.246. Order steps by dependency and proof. Each step must name concrete files or25 symbols, the logic change, its contract with adjacent code, and verification.267. Include data/schema transition, compatibility, rollout, observability, and27 rollback steps when relevant. Never hide them under “update config.”288. Re-read the plan against acceptance criteria. Ensure every criterion maps to29 implementation and verification, and every risky mutation has a recovery30 path.3132## Plan quality bar3334- Cite `path:line` evidence for the current architecture and chosen edit points.35- Separate facts, decisions, assumptions, and unresolved questions.36- Avoid steps like “implement feature,” “add tests,” or “handle errors.” State37 which behavior changes, where, and how it is proven.38- Keep task granularity aligned with independently verifiable outcomes, not39 arbitrary file-by-file edits.40- Do not include code unless a small interface sketch resolves ambiguity.4142## Output4344Use `references/implementation-plan.md`. Lead with the approach and key45decisions, then provide ordered implementation slices, verification, and46rollout. If one unresolved decision would produce substantially different47plans, stop and ask for it rather than pretending the branches are equivalent.
contextosai