plan-changes

Plan Changes

Produce the smallest decision-complete plan that reaches the requested outcome. A good plan resolves meaningful choices, preserves explicit constraints, and gives every implementation step its own proof.

Establish the Planning Boundary

Determine from the request and repository:

• observable outcome and user or system impact;
• current implementation and owning boundary;
• hard constraints, compatibility promises, and authority limits;
• existing code, primitives, or patterns worth reusing;
• non-goals and adjacent work;
• irreversible operations or rollout concerns.

Ask the user only about product, policy, or architecture choices that code and available evidence cannot answer. Do not ask them to locate files or explain facts you can inspect.

For an active failure whose cause is unknown, use systematic-debugging before planning a fix.

Choose the Shape

Start with the direct version: what is the smallest coherent change that solves the stated problem?

For a non-trivial decision, compare only materially distinct approaches. Include the minimal approach and a more durable boundary when both are credible. Do not invent a third option to fill a template.

For each real option, state:

• what changes;
• what it reuses;
• the new coupling or concept it introduces;
• compatibility and rollout implications;
• the condition under which it is the better choice.

Recommend one and say what evidence would change the recommendation.

Write the Change Contract

Before the steps, summarize:

Outcome: <observable result>
Current boundary: <where behavior lives now>
Chosen approach: <one sentence>
Invariants: <behavior and contracts that must remain true>
Non-goals: <related work excluded>
Assumptions or decisions: <only material unresolved items>
Likely edit surfaces: <paths or components and why>

Use example inputs, outputs, schemas, or before/after code when a contract shape is otherwise ambiguous. Do not require code samples for mechanical changes.