Writing Plans

Indexed Reference Map

• @[SKILL.md#L1-L104] Frontmatter, trigger rules, SOP, output contract.
• @[references/INDEX.md#L1-L20] Reading order and reference inventory.
• @[references/plan-template.md#L1-L42] Canonical plan structure and required sections.
• @[references/plan-quality-checklist.md#L1-L23] Quality gates for a usable plan.
• @[references/scope-control.md#L1-L19] Scope lock, sequencing, and anti-expansion rules.
• @[references/examples.md#L1-L35] Good plan patterns and concise examples.

Scope

• In-scope:
  • Writing implementation plans before code/config/runtime changes.
  • Breaking a broad request into ordered steps, checkpoints, and verification points.
  • Converting a vague technical request into an executable plan with bounded scope.
• Out-of-scope:
  • Direct implementation without planning.
  • Open-ended brainstorming with no intention to produce an actionable plan.
  • Final verification after changes are already complete.

KB Mode Notes

• Reading order:
  1. references/INDEX.md
  2. references/plan-template.md
  3. references/plan-quality-checklist.md
  4. references/scope-control.md
  5. references/examples.md
• Coverage Matrix:
  • Plan structure -> plan-template.md
  • Quality gates -> plan-quality-checklist.md
  • Scope containment -> scope-control.md
  • Example shapes -> examples.md
• Portability note:
  • The workflow is local-first and methodology-focused. Example plan items are illustrative and should be adapted to the actual repo/runtime context.

Trigger Rules

• Positive:
  • User asks for a plan, roadmap, implementation plan, step-by-step approach, migration plan, execution breakdown, approach, or wants to split the task into steps.
  • The task is multi-step, non-trivial, or risky enough that coding immediately would be premature.
  • Prompt contains intent like: write a plan, break this down, outline steps, plan first, roadmap, execution plan, how should we approach this, draft a plan, split steps, do it in phases, what are the next steps.
  • A task needs explicit sequencing, checkpoints, or rollback notes before implementation.
• Negative:
  • The request is a tiny mechanical edit with obvious scope and no meaningful sequencing need.
  • The user explicitly wants direct implementation right now without a separate planning artifact.
  • The task is primarily debugging an already broken system rather than planning new work.
  • The task is final verification, not pre-implementation planning.
  • The prompt is mainly asking to check whether something already works/fixed, not to design execution.
• Escalation:
  • If requirements are too ambiguous for a reliable plan, first request the minimum missing constraints.
  • If the plan would require external/sensitive actions beyond current approval scope, include approval checkpoints explicitly.

SOP

1. Define the objective
   • Restate the target outcome in one precise sentence.
   • Separate desired outcome from possible implementation choices.
2. Lock scope
   • State what is included, excluded, and deferred.
   • Prevent hidden expansion from adjacent nice-to-haves.
3. Identify constraints
   • Capture environment, safety boundaries, runtime assumptions, approvals, and dependencies.
4. Choose the plan shape
   • Use references/plan-template.md and select the smallest plan structure that still controls risk.
5. Sequence the work
   • Order steps by dependency, safety, and observability.
   • Put high-signal discovery/checkpoints before irreversible changes.
6. Define verification per phase
   • Each meaningful phase must have an explicit proof/check, not just an action item.
7. Add rollback or stop points when relevant
   • For risky steps, specify how to stop, revert, or hold before continuing.
8. Run the quality checklist
   • Use references/plan-quality-checklist.md before presenting the plan.
9. Present the plan cleanly
   • Keep steps actionable, bounded, and free of speculative filler.

Error Handling

• Requirements too vague:
  • Ask targeted clarifying questions for the missing constraint that blocks a reliable plan.
• Scope keeps expanding:
  • Split into phase 1 vs later work using references/scope-control.md.
• User asks for implementation during plan drafting:
  • Finish the minimum usable plan first unless the task is clearly trivial.
• Multiple valid strategies exist:
  • Present the recommended one and mention alternatives only if they materially affect risk or cost.
• No safe plan under current constraints:
  • State the blocker and required approval/decision explicitly.

Output Contract

• Deliverable:
  • Objective: target outcome.
  • Scope: in / out / deferred.
  • Constraints: safety, runtime, dependency, approval notes.
  • Plan: ordered execution steps.
  • Verification: checks tied to the plan.
  • Rollback/Stop Points: when relevant.
  • Open Questions: only if they block execution.
• Validation:
  • Plan must be actionable, sequenced, and bounded.
  • Avoid vague verbs like “handle”, “deal with”, or “fix stuff” without specifics.
• Compliance Verdict:
  • PASS when plan is executable and scoped; otherwise PARTIAL or FAIL with reason.