Vanessa-Ts · Vanessa-Ts · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026
diff --git a/.claude/skills/spec-feature/SKILL.md b/.claude/skills/spec-feature/SKILL.md
@@ -7,62 +7,168 @@
 
 ## Purpose
 
-Before writing a plan or any code, capture requirements through a structured interview. The output is a `docs/specs/<feature>.md` file that feeds into `/plan`.
+Before writing a plan or any code, capture requirements and design through a structured two-phase interview. The output is three files under `docs/specs/<feature>/`: `requirements.md`, `design.md`, and `tasks.md`.
 
 ---
 
-## Interview — 6 questions
+## EARS notation guide
+
+```
+EARS (Easy Approach to Requirements Syntax) — five stems:
+  Ubiquitous:   The system shall <action>.
+  Event-driven: When <trigger>, the system shall <action>.
+  Unwanted:     If <condition>, then the system shall <action>.
+  State-driven: While <state>, the system shall <action>.
+  Optional:     Where <feature included>, the system shall <action>.
+Use "When … the system shall …" for the majority of API feature stories.
+Never combine two stems in one sentence.
+```
+
+---
+
+## Interview — Phase 1: Requirements (questions 1–5)
 
 Ask these questions **one at a time** (wait for the answer before asking the next):
 
-1. **Who uses it?** — which user role or system actor triggers this feature?
-2. **What does it do?** — one sentence: "Given X, when Y, then Z."
-3. **Why now?** — what problem or opportunity drives this? What's the cost of not building it?
-4. **Acceptance criteria** — list 3–5 specific, testable conditions that mean "done". Format: "Given / When / Then."
-5. **Edge cases & constraints** — what inputs, states, or conditions must be explicitly handled or rejected?
-6. **Out of scope** — what related things will NOT be built in this iteration?
+1. **Actor** — Who uses it? Which user role or system trigger?
+2. **Behaviour** — What must it do? Use EARS stem: "When [condition], the system shall [behaviour]." (1–3 stories)
+3. **Motivation** — Why now? What is the business motivation and cost of deferral?
+4. **Acceptance criteria** — List 3–5 specific, testable conditions that mean "done". Format: "Given / When / Then."
+5. **NFRs + success metrics** — Latency target, auth/authz scope, error observability, and one measurable KPI.
+
+After question 5:
+
+- Write `docs/specs/<feature>/requirements.md` (see template below).
+- Show the path to the user.
+- Ask:
+  > "Does this capture the requirements correctly? Reply **yes** to continue to design, or correct anything above."
+- **Do not proceed to phase 2 until the user replies yes.**
 
 ---
 
-## Output — `docs/specs/<feature>.md`
+## Interview — Phase 2: Design (questions 6–8)
+
+Ask these questions **one at a time** (wait for the answer before asking the next):
+
+6. **API shape** — HTTP method(s), path(s), request fields, response fields.
+7. **Data model** — Entity fields and types (no code); relations to existing models.
+8. **Technical constraints** — Anything limiting implementation beyond project defaults (stack limits, third-party APIs, etc.).
+
+After question 8:
+
+- Write `docs/specs/<feature>/design.md` (see template below).
+- Immediately write `docs/specs/<feature>/tasks.md` (see template below).
+
+Final message (exact string):
+```
+Spec written to docs/specs/<feature>/ — run /plan <feature> to produce the implementation plan.
+```
+
+---
+
+## Output templates
+
+### `requirements.md`
 
 ```markdown
-# Spec: <feature name>
+# Requirements: <feature name>
 
 **Date**: <YYYY-MM-DD>
-**Author**: <from git config>
-**Status**: draft
-
-## Summary
-One sentence: Given X, when Y, then Z.
+**Author**: <from git config user.name>
+**Status**: approved
 
 ## Actor
-<who triggers this>
+<who triggers this feature>
 
 ## Motivation
-<why now — cost of not building>
+<why now — business motivation and cost of not building>
+
+## User stories (EARS)
+- When <condition>, the system shall <behaviour>.
+- ...
 
 ## Acceptance criteria
 - [ ] Given <state>, when <action>, then <outcome>
 - [ ] ...
 
-## Edge cases & constraints
-- <explicit handling required>
-- ...
+## Non-functional requirements
+- **Performance**: <latency target>
+- **Security**: <auth/authz scope>
+- **Observability**: <error logging / tracing hooks>
+
+## Success metrics / KPIs
+- <measurable metric, not a checkbox>
 
 ## Out of scope
-- <explicitly excluded>
-- ...
+- <explicitly excluded items>
 
 ## Open questions
-- <anything unresolved after the interview>
+- <anything unresolved from phase 1>
+```
+
+### `design.md`
+
+````markdown
+# Design: <feature name>
+
+## API contracts
+
+| Method | Path | Request | Response | Status codes |
+|---|---|---|---|---|
+| <METHOD> | <path> | <fields> | <fields> | 200, 404, 422 |
+
+## Pydantic model sketches
+
+**<ModelName>**
+- `<field>`: `<type>`
+- ...
+
+## BCE layer decisions
+- **Route**: <what the route handles>
+- **Service/Control**: <what business logic lives here>
+- **Store/Entity**: <what the store layer owns>
+
+## Sequence diagram
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Route
+    participant Service
+    participant Store
+    User->>Route: <request>
+    Route->>Service: <call>
+    Service->>Store: <call>
+    Store-->>Service: <result>
+    Service-->>Route: <result>
+    Route-->>User: <response>
+```
+
+## Technical constraints
+- Stack: FastAPI, Pydantic v2, uv, Python 3.11+, mypy --strict
+- <additional constraints from user>
+````
+
+### `tasks.md`
+
+```markdown
+# Tasks: <feature name>
+
+Ordered commit checklist — implement in this sequence:
+
+- [ ] **models** — define Pydantic models in `src/app/models/<feature>.py`
+- [ ] **store** — implement persistence layer in `src/app/store/<feature>.py`
+- [ ] **routes** — implement route handlers in `src/app/routes/<feature>.py`; wire into `main.py`
+- [ ] **tests** — write happy path, 422, and 404 tests in `tests/test_<feature>.py`
+- [ ] run `/plan <feature>` to produce the implementation plan
 ```
 
 ---
 
 ## Rules
 
 - Never invent requirements — only write what the user confirmed.
-- "Open questions" must list anything that could not be resolved in the interview.
-- After writing the spec, tell the user: `Spec written to docs/specs/<feature>.md — run /plan <feature> to produce the implementation plan.`
+- Ask questions one at a time; never batch multiple questions in one message.
+- Do not proceed to phase 2 until the user explicitly approves `requirements.md`.
+- "Open questions" in `requirements.md` must list anything unresolved after phase 1.
 - Do not start the plan or write any code.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -104,7 +104,7 @@ The `pre_push_quality_gate` hook enforces this inline on every `git push`.
 | `pytest-patterns` skill | Auto-loads for `tests/`, `conftest.py` |
 | `uv-workflows` skill | Auto-loads for `pyproject.toml`, `uv.lock` |
 | `infrastructure` skill | Auto-loads for `Dockerfile`, `docker-compose*`, CI workflows, Helm |
-| `spec-feature` skill | Structured interview → `docs/specs/<feature>.md` before planning |
+| `spec-feature` skill | 2-phase interview → `docs/specs/<feature>/{requirements,design,tasks}.md` before planning |
 | `openapi` skill | Auto-loads for `openapi*.yml/json`; spec authoring and codegen |
 | `review` skill | Inline BCE + FastAPI + Python checklist for ad-hoc code review |
 | `doc` skill | Reads source → writes project docs into `docs/` |

diff --git a/docs/inventory.md b/docs/inventory.md
@@ -19,7 +19,7 @@ External reference sources checked:
 | `skills/pytest-patterns/SKILL.md` | project-internal | proprietary | ✓ for any httpx+pytest-asyncio project | — | — | Bans `TestClient`, enforces `AsyncClient+ASGITransport`, documents fixture baseline and 3-test minimum. No project-specific logic; portable as-is. |
 | `skills/uv-workflows/SKILL.md` | project-internal | proprietary | ✓ for any uv-managed Python project | — | — | Documents `uv add`, `uv sync`, `uv run` idioms and bans `pip`/`poetry`. Fully generic; reuse verbatim in any Python project using uv. |
 | `skills/infrastructure/SKILL.md` | project-internal | proprietary | ✓ for any Python+uv project with Docker/CI | — | — | Multi-stage Dockerfile, docker-compose healthchecks, GitHub Actions with `astral-sh/setup-uv`, Helm chart structure. Stack-agnostic patterns; swap `pytest` for your test runner. |
-| `skills/spec-feature/SKILL.md` | project-internal | proprietary | ✓ | — | — | 6-question interview template producing `docs/specs/<feature>.md`. Fully generic; no framework coupling. |
+| `skills/spec-feature/SKILL.md` | project-internal | proprietary | — | — | ✓ | Rebuilt: 2-phase 8-question interview (requirements + design) with approval gate; produces 3 files under `docs/specs/<feature>/` (`requirements.md`, `design.md`, `tasks.md`). EARS notation embedded. |
 | `skills/openapi/SKILL.md` | project-internal | proprietary | ✓ for any FastAPI/Python project | — | — | OpenAPI 3.x YAML structure, `datamodel-codegen` and `fastapi-codegen` usage, spec export from running FastAPI app. |
 | `skills/review/SKILL.md` | project-internal | proprietary | — | ✓ | — | Inline BCE + FastAPI + Python checklist. Wrap: replace FastAPI-specific items for non-FastAPI stacks. |
 | `skills/doc/SKILL.md` | project-internal | proprietary | — | ✓ | — | Doc-generation workflow reading `main.py`, routes, models, config. Wrap: adjust source paths for non-FastAPI layouts. |