plan-task

plan-task

Turn ambiguous engineering work into a concrete execution contract. Plan for a fresh implementer, not for the current chat.

Assume the plan will be followed strictly unless a human explicitly amends it. Assume implementation may happen in a clean context window with no access to prior conversation.

Read first

• ../references/task-packet-contract.md
• ../references/persistent-artifacts-contract.md
• ../references/compatibility-policy.md
• ../references/ownership-and-reuse-policy.md
• ../references/final-state-authoring-policy.md
• ../references/initiative-workflow-contract.md when planning an initiative child packet
• ../../references/communication-mode.md
• relevant tracked AGENTS.md chain
• applicable AGENTS.override.md only if local execution constraints matter

Planning workflow

1. Establish scope.
   • Clarify the exact task, desired outcome, constraints, and what is out of scope.
   • Prefer concrete deliverables over vague goals.
   • Name the real acceptance criteria early.
2. Identify the true change surface.
   • Find the owner modules, state transitions, APIs, persistence paths, tests, and tracked AGENTS.md constraints the task will affect.
   • Distinguish direct change points from incidental neighbors.
   • Distinguish internal boundaries from real external boundaries relative to the service.
   • If the task is lifecycle-heavy, treat restart, retry, cancellation, and recovery as first-class planning concerns.
3. Resolve ownership and reuse first.
   • Identify the current owner for each important behavior, invariant, or responsibility.
   • Prefer reusing, extending, or slightly refactoring that existing owner over introducing a parallel entity.
   • If existing code is close but awkward, plan a tidy-first refactor that makes reuse possible.
   • Only allow a new helper/service/adapter/store/module/type when the new boundary is explicitly different and non-overlapping.
   • If the plan would leave two same-purpose entities alive, treat that as a design problem and rewrite the plan.
4. Resolve compatibility policy correctly.
   • Backward compatibility is prohibited by default.
   • Do not add compatibility work to the plan unless the human explicitly asked for it.
   • If the task touches a real external boundary and compatibility requirements are unresolved, stop and ask the human explicitly whether backward compatibility is required.
   • For internal-only changes, do not ask; plan the clean internal change with no compatibility scaffolding.
5. Write the target state, not the migration story.
   • Describe the intended steady state directly: final owners, final vocabulary, final status model, final artifact layout.
   • Do not write canonical plan steps as old + new, keep this for now, add another path, or similar transition prose when the clean final design is already known.
   • If a real external boundary truly requires compatibility work, keep the steady-state owner and current contract obvious in the plan.
6. Bootstrap the packet.
   • Create or update .plans/<task-slug>/INDEX.md.
   • Create empty canonical placeholders for AMENDMENTS.md and ARTIFACT_CANDIDATES.md immediately, even if they are still empty.
   • Ensure INDEX.md points to those files from the first packet version.
   • BRIEF.md is optional. Use it only when discovery output needs to be normalized into a compact handoff artifact before writing PLAN.md.
   • grill-me may populate BRIEF.md; plan-task may normalize, complete, or create it if discovery context has not yet been captured cleanly.
7. Define success before steps.
   • State the observable behavior that must be true when the task is done.
   • Define validation early: tests, checks, smoke paths, or user-visible outcomes.
   • Call out unknowns, assumptions, and risky edges before finalizing sequencing.
8. Slice the work into low-risk increments.
   • Prefer steps that keep the system coherent after each increment.
   • Separate foundational refactors from behavior changes unless combining them is clearly safer.
   • Favor plans that are easy to review and easy to revert.
9. Plan for amendment, not improvisation.
   • State exact stop conditions.
   • Make it explicit that implementation must stop if the plan becomes unsafe, impossible, or contradicted by the codebase.
   • Require amendment flow: blocker, options, pros/cons, plan impact, human decision, packet update.
   • If a better but non-essential design appears during implementation, require a REVIEW_NOTE rather than silent deviation.
10. Optimize for human maintainability.

• Minimize how much context a human must hold at once.
• Prefer plans that centralize risky logic, reduce change amplification, and keep ownership obvious.
• Avoid plans that require many synchronized edits unless there is no safer alternative.

1. Make the plan self-sufficient for handoff.

• Name the concrete target models, contracts, files, artifact paths, and boundaries instead of relying on chat shorthand.
• Include exact terminology when names affect correctness.
• State failure behavior and unsupported-capability behavior explicitly when implementation would otherwise have to guess.

1. Produce the plan.

• Write PLAN.md as the canonical execution contract.
• Keep the steps ordered, imperative, and dependency-aware.
• If likely durable residue is already obvious, note it in ARTIFACT_CANDIDATES.md; do not write tracked AGENTS.md.