Planning Skill

When to use

Modes

quick-plan

• task is small/medium and non-breaking
• no migrations and no multi-phase rollout

• 3–8 Work Items (WI-###), each with tests + acceptance

full-plan

(default)

• migrations/persistence changes
• API/contract changes (public tools, schemas, SDKs)
• multi-phase roadmaps
• performance-sensitive work

• structured plan sections (see “Plan file template”)

Process

1. Clarify outcomes
   • Restate desired behaviors and constraints.
   • Identify ambiguities and propose defaults if the user doesn’t decide.
   • Capture constraints & dependencies (runtime versions, OS, external services, feature flags, required tools).
   • Capture gaps: list requirement/behavior gaps or missing decisions revealed here.
2. Inventory current behavior
   • Trace entry points → state/store → side effects → persistence.
   • List key files/modules and the invariants they rely on.
   • Note ownership/priority rules (windows, workspaces, files).
   • Capture gaps: list where current behavior diverges from the stated outcomes.
3. Define target rules
   • Convert outcomes into explicit rules and precedence.
   • For each rule, include: trigger/context, expected behavior, scope, constraints, and exclusions.
   • Edge-case pass: cover empty/none, invalid/malformed, boundary sizes, conflicting state, multi-surface coordination, persistence/restore, and I/O failures.
   • Capture gaps: list rules that lack implementation support or current behavior conflicts.
   • Create a Decision Log:
     • decision, options considered, rationale, and why alternatives were rejected.
   • Create an Open Questions list:
     • questions that block correctness, who decides, and what the default is if not decided.
4. Structure the plan
   • Break into Work Items (WI-###), each with:
     • Goal
     • Acceptance (measurable) (correctness + performance + UX where relevant)
     • Tests (first) (file names + test intent; unit/integration/e2e as applicable)
     • Touched areas (file paths + key functions/classes/symbols)
     • Dependencies (other WIs, external tools/services)
     • Risks + mitigations
     • Rollback / revert strategy
   • Add priority + estimates (S/M/L) and explicit ordering/dependencies between WIs.
   • Capture gaps: map each gap to at least one WI (or record as “out of scope”).
   • Plan lint (required):
     • Sections present (Outcomes, Constraints, Current Behavior, Target Rules, Work Items, Testing).
     • WI numbering is sequential and referenced consistently.
     • Every WI includes tests + acceptance.
5. Write the plan file
   • Use the template at

     templates/TEMPLATE.md

     (bundled with this skill) if available, otherwise follow the structure above.
   • Write plans to a local directory (e.g.

     dev-docs/plans/YYYYMMDD-HHMM-<topic>.md

     — local, not in repo).
   • Always report the saved plan path.

Testing Requirements

• Every WI must include explicit tests to write before implementation (file names and test intent).
• If tests cannot be written, call it out explicitly and propose the smallest test seam to enable them.
• Include a Testing Procedures section in the plan with required commands and when to run them.
• End the plan with a short Manual Test Checklist.

Acceptance Criteria Guidance

• Good: “Search returns v1 schema with

  locator_v1

  for every result (unit test).”
• Bad: “Search feels better.”

Plan → Verify Handoff (required)

• Evidence to collect per WI (tests, logs, manual steps).
• Any required fixtures or sample data.

Migration / persistence requirements (when applicable)

• Add a Data Model section (tables/columns/keys, versions).
• Add a Migration Plan:
  • forward migration steps
  • rollback steps
  • compatibility guarantees (old clients vs new server)
• Add Invariants + validation queries (what to check post-migration).
• Add a Backfill / reindex strategy if needed.

Observability requirements (when applicable)

• Define metrics (latency, throughput, memory, DB size growth).
• Define where logs go and how to enable verbose tracing.
• Add acceptance thresholds (e.g. “index 1000 docs < X minutes on machine Y”).

Rollout requirements (when applicable)

• Add a Rollout Plan (feature flags, staged enablement, default-off vs default-on).
• Define “kill switch” conditions and how to revert quickly.

Output Requirements

• Always produce a plan file and include its path in the response.
• Ask at most 1–2 clarifying questions only when they change the rules.