workflows-plan

What this skill does

# Create a plan for a new feature or bug fix

## Runtime Tools

When this skill needs user questions, todo/progress tracking, subagents, or another skill, use the active runtime equivalents in [RUNTIME_TOOLS.md](../RUNTIME_TOOLS.md).


Adhere to the Builder Ethos (ETHOS.md): Boil the Lake, Search Before Building, User Sovereignty.

## Introduction

**Note: The current year is 2026.** Use this when dating plans and searching for recent documentation.

Transform feature descriptions, bug reports, or improvement ideas into:
1. **spec.md** - Human-readable plan with rationale, context, and design decisions
2. **prd.json** - Machine-executable story breakdown for systematic implementation

## Feature Description

<feature_description> $ARGUMENTS </feature_description>

**If the feature description above is empty, ask the user:** "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind."

Do not proceed until you have a clear feature description from the user.

### 0. Idea Refinement

**Check for existing plan folder or brainstorm first:**

Before asking questions, look for existing plan folders that match this feature:

```bash
ls -la docs/plans/*/brainstorm.md 2>/dev/null
ls -la docs/plans/*/spec.md 2>/dev/null
```

**Relevance criteria:** A brainstorm is relevant if:
- The folder name or brainstorm content semantically matches the feature description
- Created within the last 14 days
- If multiple candidates match, use the most recent one

**If a relevant brainstorm exists:**
1. Read the brainstorm document
2. Announce: "Found brainstorm from [date]: [topic]. Using as context for planning."
3. **Check for shaping format** — look for `shaping: true` in frontmatter, R table, shapes, fit check
4. **Skip the idea refinement questions below** — the brainstorm already answered WHAT to build

**If shaping format detected:**
- Extract R table → primary source for acceptance criteria
- Extract selected shape + parts table → technical approach structure
- Extract flagged unknowns (!) → open questions / spike candidates
- Extract Frame (Source, Problem, Outcome) → spec problem statement
- Use R table as input to SpecFlow and story generation

**If standard brainstorm format:**
- Extract key decisions, chosen approach, and open questions
- Use brainstorm decisions as input to the research phase

**If multiple brainstorms could match:**
Use **structured user-question tool** to ask which brainstorm to use, or whether to proceed without one.

**If no brainstorm found (or not relevant), run idea refinement:**

Refine the idea through collaborative dialogue using the **structured user-question tool**; making sure to interview me relentlessly until we reach a shared understanding - walk down each branch of the design tree, resolving dependencies between decisions one-by-one.

- Ask questions one at a time to understand the idea fully
- Prefer multiple choice questions when natural options exist
- Focus on understanding: purpose, constraints and success criteria
- Continue until the idea is clear OR user says "proceed"

**Gather signals for research decision.** During refinement, note:

- **User's familiarity**: Do they know the codebase patterns? Are they pointing to examples?
- **User's intent**: Speed vs thoroughness? Exploration vs execution?
- **Topic risk**: Security, payments, external APIs warrant more caution
- **Uncertainty level**: Is the approach clear or open-ended?

**Skip option:** If the feature description is already detailed, offer:
"Your description is clear. Should I proceed with research, or would you like to refine it further?"

## Main Tasks

### 1. Local Research (Always Runs - Parallel)

You MUST run this agent to gather local context. Do not skip:

- Launch subagent `repo-research-analyst` with prompt (feature_description)

**What to look for:**
- Existing patterns, active project instructions (AGENTS.md, CLAUDE.md, README.md, OPENCODE.md), technology familiarity, pattern consistency

These findings inform the next step.

### 1.5. Research Decision

Based on signals from Step 0 and findings from Step 1, decide on external research.

**High-risk topics → always research.** Security, payments, external APIs, data privacy. The cost of missing something is too high. This takes precedence over speed signals.

**Strong local context → skip external research.** Codebase has good patterns, project instructions have guidance, user knows what they want. External research adds little value.

**Uncertainty or unfamiliar territory → research.** User is exploring, codebase has no examples, new technology. External perspective is valuable.

**Announce the decision and proceed.** Brief explanation, then continue. User can redirect if needed.

Examples:
- "Your codebase has solid patterns for this. Proceeding without external research."
- "This involves payment processing, so I'll research current best practices first."

### 1.5b. External Research (Conditional)

**Only run if Step 1.5 indicates external research is valuable.**

Run these agents in parallel:

- Launch subagent `best-practices-researcher` with prompt (feature_description)
- Launch subagent `framework-docs-researcher` with prompt (feature_description)

### 1.6. Consolidate Research

After all research steps complete, consolidate findings:

- Document relevant file paths from repo research (e.g., `src/services/exampleService.ts:42`)
- Note external documentation URLs and best practices (if external research was done)
- List related PRs discovered
- Capture active project instruction conventions

**Briefly summarize findings to the user and ask if anything looks off or missing before proceeding to planning.**

### 1.7. Choose Detail Level

Use the **structured user-question tool** to determine how comprehensive the spec should be. This decision affects how much work goes into subsequent steps.

**Question:** "What level of detail do you want for this spec?"

**Options:**
1. **MINIMAL** — Quick spec. Problem + solution + acceptance criteria. Best for simple bugs, small improvements, clear features.
2. **STANDARD** — Most features. Adds background, technical considerations, success metrics, dependencies/risks.
3. **COMPREHENSIVE** — Major features, architectural changes. Produces 5 documents: ADR, backend spec, DTO contract, UI design spec, frontend spec. Uses a decision cascade model where you make key architectural decisions and everything else derives automatically.

**Default recommendation:** STANDARD unless the feature is trivially small (MINIMAL) or involves major architecture, multiple system layers, or complex integrations (COMPREHENSIVE).

**If user picks COMPREHENSIVE:** The planning steps below still run, but Step 4 will trigger an extended collaborative decision-making process that produces 5 spec documents instead of a single spec.md.

### 2. Planning & Structure

**Ticket & Branch:**

First, extract or ask for the ticket number:

- [ ] Check if feature description contains a ticket URL (e.g., `https://yourorg.atlassian.net/browse/PROJ-1222`)
- [ ] If URL found, extract ticket number (e.g., `PROJ-1222`)
- [ ] If no URL/ticket, use **structured user-question tool**: "Is there a ticket for this work? (e.g., PROJ-1234, or 'none')"

**Branch Naming Convention:**

Format: `[ticket-number]-[description-kebab-case]`

Examples:
- `PROJ-1222-user-authentication`
- `PROJ-1456-fix-checkout-race-condition`
- `PROJ-890-refactor-api-client`

If no ticket: use `type/description-kebab-case` (e.g., `feat/user-authentication`, `fix/checkout-race-condition`)

**Folder & Title:**

- [ ] Draft clear, searchable title using conventional format (e.g., `feat: Add user authentication`, `fix: Cart total calculation`)
- [ ] Determine type: feat, fix, refactor
- [ ] Create folder name: `YYYY-MM-DD-<type>-<descriptive-kebab-name>`
  - Example: `feat: Add User Authentication` → `2026-01-21-feat-user-authentication/`
  - Keep it descriptive (3-5 words) so plans are findable