writing-plans

Writing Plans

Produce a plan that a zero-context engineer could execute without guessing.

Use this skill when the user asked for a plan, or when the work is large, risky, or multi-stage enough that implementation should be decomposed first. Do not force a plan for every trivial change.

When the user already named concrete files, subsystems, or design docs, inspect those directly before drafting the plan and ground the plan in what you actually read. Do not ask for "the patch" or "more context" first when the relevant repo files are already named and available from the attached workspace.

Planning Standard

The plan should include:

• the goal and scope
• explicit acceptance gates
• the existing checks to reuse before inventing new ones
• the files or subsystems likely to change
• ordered tasks with narrow outcomes
• verification for each major step, including broader proof where it matters
• docs, migration, or rollout follow-ups when relevant

For any non-trivial plan, include these section labels explicitly in the written output:

• Acceptance Gates
• Existing Checks To Reuse

If you do not yet know the exact repo checks, still include Existing Checks To Reuse and say what must be inspected or reused before inventing narrower coverage. Do not block the first draft plan on repo inspection or tool use just to discover those checks.

Task Granularity

Prefer tasks that are small enough to execute and verify independently.

Good task shape:

• add or update one focused test
• implement one bounded behavior
• run the relevant verification
• update the affected docs or configuration if needed

Acceptance Gates

Every non-trivial plan should name the concrete conditions that must be true before the work can be called done.

Good acceptance gates are observable and specific:

• the archive view renders completed routines
• existing dashboard flows still work
• the persisted data shape stays backward-compatible

Bad acceptance gates are vague:

• works well
• code is cleaned up
• tests pass