spec-driven-planning

What this skill does

# Spec-Driven Planning Skill

## Purpose

Guide feature planning in one of two modes:

- **Quick mode** — single `docx/features/[NN-name]/plan.md` with bite-sized tasks. No EARS, no RGR. For solo work, ≤3 days, no compliance/handoff. Derived from the superpowers writing-plans pattern.
- **Full mode** — three files (`requirements.md` EARS + `design.md` + `tasks.md`) with three approval gates and TDD enforcement downstream. For team work, multi-week, compliance/audit, or stakeholder review.

The skill picks a mode (or asks when ambiguous), then runs the matching playbook.

## Activation Triggers

Activate this skill when:
- User says "create a new feature", "plan a feature", "I need to build [X]"
- User mentions "requirements", "specifications", "specs", "architecture", "technical design"
- User uses `/dev-workflow:spec` command (any sub-arg)

---

## Mode Selection (ALWAYS DO THIS FIRST)

Before writing anything, decide Quick vs Full.

### Auto-pick Quick when ALL true:
- Estimated effort ≤ 3 days OR ≤ 8 tasks
- Solo developer; no stakeholder approval needed
- No compliance, audit, or regulatory requirement
- No major architectural decision (no "X vs Y?" trade-off)
- Requirements clear from the user's request
- No cross-team handoff
- User said "quick", "lightweight", "simple plan", or `/dev-workflow:spec quick`

### Auto-pick Full when ANY true:
- Effort > 1 week OR > 15 tasks
- Stakeholders ≠ engineers must approve scope
- Compliance / audit / regulatory traceability required
- Architecture choice with long-term consequences
- Requirements ambiguous; need elicitation
- Multi-developer or handoff likely
- User said "full spec", "EARS", "requirements doc", or `/dev-workflow:spec full`

### Otherwise, treat as ambiguous

The thresholds above are deliberately gapped — 4-7 days of effort, 9-15 tasks, or any partial signal match falls in the middle zone. If you don't get a clean **all-true** Quick or **any-true** Full match, the feature is ambiguous by definition. Ask the user.

### Ambiguous? Ask once with this menu:

```
This feature could go either way. Pick a planning mode:

1. Quick — single plan.md, no EARS, no RGR (recommended for solo, ≤3 days)
2. Full — 3-file spec with EARS + TDD enforcement (recommended for team, >1 week, compliance)

Default if you don't pick: Quick.
```

**Announce the chosen mode:**
> "Using [Quick/Full] mode. [One-sentence reason from signals above.]"

Then run the matching playbook below.

---

## Quick Mode Playbook

**Output:** `docx/features/[NN-feature-name]/plan.md` (single file)

### Step 1: Create feature directory

1. `ls docx/features/` to find next NN number
2. `mkdir -p docx/features/[NN-feature-name]`
3. Read `dev-workflow/templates/plan.md`
4. Write to `docx/features/[NN-feature-name]/plan.md`, replacing `[Feature Name]` with the actual name

### Step 2: Fill in the plan

Audience assumption: an engineer with zero context for this codebase. Be exact.

Required sections:
- **Goal** — one sentence
- **Architecture** — 2-3 sentences, what goes where and why
- **Tech Stack** — key libraries / files
- **Out of Scope** — keeps scope honest
- **Tasks** — bite-sized (2-5 min steps), with:
  - **Files:** exact paths (Create / Modify with line ranges)
  - **Steps:** numbered, each one action. Include complete code, not "add validation here". Include exact verification commands with expected output. End with a commit step.

Granularity rule: if a step takes longer than 5 minutes, split it.

### Step 3: One approval gate

> "Quick plan saved to `docx/features/[NN-feature-name]/plan.md`. Review and approve to proceed to implementation. Run `/dev-workflow:spec execute` when ready."

That's it. No EARS, no design alternatives, no RGR. Implementation is handled by `spec-driven-implementation` (which auto-detects `plan.md` and runs in Quick execution mode).

### Quick mode is wrong if you find yourself...

- Writing requirements that need approval from non-engineers → switch to Full
- Comparing 2+ architectural approaches → switch to Full
- Listing > 15 tasks → switch to Full
- Needing traceability from requirement → task → test → switch to Full

To upgrade, see "Upgrade path" at the bottom of this skill.

---

## Full Mode Playbook

Three phases, three approval gates. Use this when signals say Full.

### Phase 1: Feature Creation

**Goal:** Establish feature structure and placeholder files

**Process:**
1. Parse feature name from user input
2. Check existing features using Bash tool: `ls docx/features/`
3. Determine next number (NN) for feature directory
4. Create directory using Bash tool: `mkdir -p docx/features/[NN-feature-name]`
5. Copy templates from plugin to feature directory:
   - Use Read tool: `dev-workflow/templates/requirements.md`
   - Use Write tool: `docx/features/[NN-feature-name]/requirements.md` (replace [Feature Name] with actual name)
   - Use Read tool: `dev-workflow/templates/design.md`
   - Use Write tool: `docx/features/[NN-feature-name]/design.md` (replace [Feature Name] with actual name)
   - Use Read tool: `dev-workflow/templates/tasks.md`
   - Use Write tool: `docx/features/[NN-feature-name]/tasks.md` (replace [Feature Name] with actual name)

**Output:**
```
Created feature: docx/features/[NN-feature-name]/
- requirements.md (from template)
- design.md (from template)
- tasks.md (from template)

Next step: Define requirements using EARS format
```

**User Confirmation:**
> "Feature structure created. Ready to define requirements?"

---

### Phase 2: Requirements Definition (EARS Format)

**Goal:** Capture clear, testable requirements using EARS methodology

**Scope Decomposition Check (do FIRST):**

Before eliciting requirements, scan the request. If it describes multiple independent subsystems (e.g., "auth + billing + admin dashboard"), STOP and decompose into separate features before refining any one. Don't burn elicitation questions on a feature that should be three.

> 🗣 Say: "This request covers [N] independent subsystems. I'll create separate features for each before eliciting requirements."

**No Placeholders Rule:**

Requirements and downstream plans MUST NOT contain:
- "TBD" / "to be determined" / "to be defined later"
- "add appropriate X" / "handle errors as needed" / "validate as required"
- "similar to [other thing]" / "see above" without specifics
- vague verbs without objects: "update", "improve", "fix", "enhance"
- "etc." or trailing ellipses in requirement text
- references to undefined names (REQ-IDs that don't exist, modules not yet specified)
If you cannot specify a requirement concretely, ask the user. Don't write a placeholder.

**Brainstorming Integration (Optional):**
- If user has rough idea but unclear requirements, use Skill tool to invoke: `dev-workflow:brainstorming`
- Helps clarify what to build vs. what's out of scope
- Explores different feature scopes through collaborative questioning
- Determines must-haves vs. nice-to-haves

**How to activate:**
```
Use Skill tool: Skill(skill: "dev-workflow:brainstorming")
```

**EARS Format Explained:**

EARS (Easy Approach to Requirements Syntax) provides five templates for unambiguous requirements:

1. **Ubiquitous Requirements** - Always true
   - Template: "The system SHALL [requirement]"
   - Example: "The system SHALL validate all user inputs before processing"

2. **Event-Driven Requirements** - Triggered by events
   - Template: "WHEN [trigger] THEN the system SHALL [response]"
   - Example: "WHEN user clicks submit THEN the system SHALL validate form data"

3. **State-Driven Requirements** - Active during specific states
   - Template: "WHILE [state] the system SHALL [requirement]"
   - Example: "WHILE processing payment the system SHALL display loading indicator"

4. **Conditional Requirements** - Based on conditions
   - Template: "IF [condition] THEN the system SHALL [requirement]"
   - Example: "IF user role is admin THEN the system SHALL show management panel"

5. **Optional Requirements** - Feature toggles