create-plan

Purpose

Generates architecturally rigorous, tactically concrete, safe-to-execute, and independently auditable implementation plans. Forces structural completeness so plan quality does not vary with the underlying model.

Use this skill when

• The user asks for a "plan", "design doc", "migration plan", or "refactor plan".
• Work spans multiple files, introduces architectural change, or has real tradeoffs between approaches.
• A pre-existing plan must be reviewed, upgraded, or standardized.
• Comparing multiple plans and producing a synthesized "best of" plan.
• The user wants a planning output they can hand to another engineer without follow-up questions.

Do not use for: single-line fixes, typos, obvious one-file changes, or pure "what/where is X?" research queries.

Inputs

Required

• task: string — the specific implementation task the plan addresses. Must include enough context for the plan author to determine scope, current state, and target state.

Optional

• codebase_root: path (default: current working directory) — directory to inventory before writing the plan.
• reference_plans: list of paths (default: none) — prior plans to synthesize from. When present, the Plan Provenance section (15) becomes mandatory.
• runtime_targets: list (default: inferred) — explicit target runtime / versions that become hard constraints.
• out_of_scope: list (default: none) — items the user has already declared non-goals.

Outputs

Required

Write plan to: <plan_dir>/<slug>-<YYYY-MM-DD>.plan.md

• plan_dir default: .snowflake/cortex/plans/ if it exists, else docs/plans/, else ./ with a note.
• slug: lowercase-hyphens summary of the task (max 48 chars).
• No overwrites: if file exists, append -01.md, -02.md, etc.
• End file with the literal line **End of plan.**.

Workflow

Execute phases in order. Do not skip any.

Phase 1 — Research (mandatory before writing)

1. Read the current state of the codebase relevant to task. Inventory every file that will be created, modified, or deleted. Record paths.
2. Identify every caller / consumer of the thing being changed (grep for it). Note downstream breakage points.
3. Identify the current runtime, package manager, test framework, CI system, and container base image. Do not assume — verify by reading config files.
4. Surface orphan / missing files referenced by config (e.g., bin entries pointing at nonexistent files). Flag them for Phase 0 of the plan.
5. If reference_plans provided, read each and note distinctive strengths / weaknesses per plan for Section 15.
6. Cite findings inline in the plan. Phase 1 discoveries (verified runtime versions, orphan config entries, downstream consumers, current base images) must appear explicitly in Sections 2 (Hard Constraints), 3 (Target Architecture), 9 (Risk Register), or 10 (Phase 0 tasks) — not just inform the plan silently. A reader must be able to trace every non-trivial claim back to a file path or command output.