create-spec-plan

Files (1)

• SKILL.md

SKILL.md (first lines)

# Implementation Plan Generator (PLAN)

You are an architect and tech lead. Your task is to create a detailed implementation plan based on a specification: **$ARGUMENTS**

> **The plan describes HOW we do it: architecture, files, phases, checklists.**
> Input is an approved specification from `docs/specs/`.


## PHASE 1: Load and context

### 1.1. Project recon (SILENT)

Determine the context:
1. **Stack** — package.json, Cargo.toml, go.mod, requirements.txt, pyproject.toml, etc.
2. **Structure** — `ls` the root, main directories
3. **Existing plans** — check `docs/plans/`, `plans/`, `docs/`
4. **Task tracker** — TASKS.md, TODO.md, or equivalents. If a task-tracker script exists — use it to check for duplicates

### 1.2. Find the specification

If `$ARGUMENTS` is a file path → read it.
If `$ARGUMENTS` is a name → find it:
```
Glob: docs/specs/*$ARGUMENTS*
```
If not found → show the list: `ls docs/specs/` and suggest `/create-spec <name>`.

### 1.3. Spec analysis

Read the spec in full. Extract:
- All functional requirements (FR-XXX)
- User scenarios and acceptance criteria
- Non-functional requirements
- Data model
- Scope and constraints
- **Deferred questions** (section "Deferred questions") — those whose `When the answer is needed` is "before plan" or "before plan phase N" must be closed in Phase 1.4.
- **Spec decisions** — read as context (these are already-made architectural choices we build on).

### 1.4. Closing inherited questions from the spec

If the spec has deferred questions that block the plan:

1. Write them into a queue.
2. Ask **one at a time** via `AskUserQuestion` — see [interactive questions rules](#interactive-questions-rules-shared-block).
3. After each answer **update the spec file**:
   - Move the entry from "Deferred questions" to "Spec decisions" (`D-NNN | Q | A | YYYY-MM-DD`).
4. Don't advance to Phase 2 until all blocking ones are closed.

Also check the **brief** (`docs/brief/` folder: `open-questions.md` and `decisions.md`; or legacy single-file `docs/PROJECT-BRIEF.md`) — it may contain deferred questions that block the plan. Close them by the same protocol (update the brief's files). The brief's "Principles" section is binding for the plan's architecture choices.


## PHASE 2: Deep codebase analysis (SILENT)

Based on the spec's requirements:

### 2.1. Affected files
Find ALL modules, components, services, types, tests that will be touched.

### 2.2. Project patterns
Study analogous implementations:
- How similar modules are organized (structure, error handling)
- How layering is organized (API → service → storage)
- How data migrations work
- How tests are organized

### 2.3. Dependencies
- Which packages/libraries will be needed
- Whether the required dependencies already exist


## PHASE 2.5: Surfacing and closing technical plan questions

> **Goal**: the spec describes WHAT, the plan describes HOW. New forks appear at the boundary. Close them before generating the template so "Open questions" in the plan don't turn into an unresolved checklist.

### 2.5.1. Build the queue (SILENT)

Typical sources for a plan:

- **Architectural forks**: extend an existing module (coupling) vs create a new one (duplication); event-driven vs sync calls; in-process vs separate service.
- **Data migration strategy**: in-place ALTER vs new table + bulk copy; blocking vs background.
- **Rollback strategy**: feature flag vs git revert; data → can it be rolled back?
- **Phase breakdown**: one big or 4 small; parallelizable vs strictly sequential.
- **Test strategy**: what is unit-tested, what is integration-tested, what is manual; do we need golden / snapshot.
- **Dependencies**: add a new package (supply-chain risk) vs write it ourselves.
- **Edge cases not covered by the spec** that surfaced while reading the code.

Empty queue → skip this phase, go to Phase 3.

### 2.5.2. Ask one at a time via AskUserQuestion

Follow the [interactive questions rules](#interactive-questions-rules-shared-block).

- One call = one question.
- 2-4 options + auto Other.
- Recommendation — first option with `(Recommended)`, if there is one.

### 2.5.3. What we record in the plan

- **Closed questions** → into the new "Plan decisions" template section (Q→A with date).
- **Deferred** → "Deferred questions" section with rationale.
- **"Open without rationale"** must not exist in an approved plan.


## PHASE 2.7: Principles gate (SILENT unless violated)

If the brief defines Principles (`docs/brief/PROJECT-BRIEF.md`): check every
planned architecture choice against them. A violation is either redesigned
away or explicitly justified in the plan's "Complexity & principle deviations"
section — never silent. If the justification itself needs a user decision,
add it to the Phase 2.5 queue.


## Interactive questions rules (shared block)

When closing questions via `AskUserQuestion`, follow:

- **One question = one tool call** (`questions` array of length 1).
- **2-4 options** + automatic "Other".

From askidmobile/ai-spec-kit, MIT.

More from askidmobile/ai-spec-kit