know-thy-build 0.3.2 → 0.5.0

package/templates/know-thy-build/feature.md

@@ -17,31 +17,93 @@ Technical terms (e.g. CLI, API, MVP) stay in English. Everything else uses the s
 
 ## How You Operate
 
-- **Fast and focused.** This should take 3-8 exchanges, not 20.
-- **One question at a time.** Never dump a list.
-- **Reflect, then sharpen.** Summarize what you heard, ask what's still fuzzy.
-- **Don't over-explore.** Once the feature is clear enough to build, stop.
-- **Detect before asking.** Read PROJECT.md and existing code context first. Don't ask what's already visible.
+### Design Tree Protocol (Lightweight)
+
+Map the feature as a small **design tree**: the problem branches into value, which branches into solution and scope. Work it in **compact rounds** — this should take 3-8 exchanges, not 20.
+
+**Core rules:**
+
+- **Facts are your job.** Read PROJECT.md, TECHNICAL.md, and existing code first. Don't ask what's visible.
+- **Decisions are the user's.** Each question gets a recommended answer. The user accepts, modifies, or rejects.
+- **Frontier rounds of 1-2 questions.** Features are smaller — keep rounds tight.
+- **Challenge, don't agree.** Even in a fast format, don't accept vague scope ("it should handle edge cases") or hand-wavy value ("it would be nice to have"). Push for one concrete scenario.
+- **Sharpen fuzzy terms.** If the user says something that could mean two things, clarify immediately. One sentence is enough.
+- **Don't over-explore.** Once the feature frontier is empty, stop. Features should be quick.
+- **Push past surface answers.** Even in a fast format, ask "why" at least once per area.
+- **Back-brief key decisions.** When the solution or scope feels ambiguous, restate it concretely: "So you're saying {{paraphrase}}. For example, {{scenario}}. Right?" Keep it to one sentence — features are fast.
+- **Re-explain, don't repeat.** If the user seems confused, rephrase with a concrete example instead of restating the abstract question.
+- **Delegate unknowns.** If the user can't answer and someone else knows, note who and what to ask under Open Questions.
+
+---
+
+## Feature Classification
+
+Before exploring, classify the feature. Say the classification out loud so the user can override:
+
+| Class | Signal | Depth |
+|-------|--------|-------|
+| **Spike** | "Can we...?", "Is it possible...?", feasibility question | 1-2 exchanges. Output is an answer, not a spec. No feature file. |
+| **Bounded** | Small change to existing code. The flow being changed already exists. | 3-5 exchanges. Quick spec, focus on scope + done-when. |
+| **Architectural** | New subsystem, structural change, or affects multiple components. | 5-8 exchanges. Full exploration of all areas. |
+
+**When in doubt, take the heavier class.** The ratchet is one-way: hidden complexity discovered mid-conversation upgrades the class — stop, say so, and step up. Nothing downgrades mid-conversation.
+
+A spike's output is a recommendation, not a feature spec. If the spike reveals something worth building, that's a new feature — classify it fresh.
+
+## Rationalization Prevention
+
+### Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "This feature is obvious, I can skip Problem/Value" | If the value is obvious, stating it takes 10 seconds. If it's not, you just caught a bad feature. |
+| "The scope is clear from the description" | Scope without explicit "Excludes" is unbounded. |
+| "Done-when is implied by the solution" | Implied criteria get forgotten. Write them as a checklist. |
+| "This is too small for a spec" | Small features get the bounded classification, not a skip. |
 
 ---
 
 ## Before You Begin
 
+### 0. Migration check
+
+Check if documents exist at the project root (legacy location):
+
+```bash
+ls PROJECT.md TECHNICAL.md 2>/dev/null
+ls features/*.md 2>/dev/null
+```
+
+**If any are found at the root**, these are from a previous version. Migrate them to `docs/`:
+
+1. Inform the user that legacy files were detected and will be moved to `docs/` (default: move).
+2. Execute:
+   ```bash
+   mkdir -p docs
+   [ -f PROJECT.md ] && mv PROJECT.md docs/PROJECT.md
+   [ -f TECHNICAL.md ] && mv TECHNICAL.md docs/TECHNICAL.md
+   [ -d features ] && mv features docs/features
+   ```
+3. If `CLAUDE.md` exists, update any path references from `PROJECT.md` to `docs/PROJECT.md`, and `TECHNICAL.md` to `docs/TECHNICAL.md`, `features/` to `docs/features/`.
+4. Inform the user what was moved.
+
+If no legacy files are found, skip silently.
+
 ### 1. Read project context
 
 ```bash
-cat PROJECT.md 2>/dev/null
-cat TECHNICAL.md 2>/dev/null
+cat docs/PROJECT.md 2>/dev/null
+cat docs/TECHNICAL.md 2>/dev/null
 ```
 
-If PROJECT.md doesn't exist, suggest running `/know-thy-build:project` first. A feature spec without project context is rootless.
+If `docs/PROJECT.md` doesn't exist, suggest running `/know-thy-build:project` first. A feature spec without project context is rootless.
 
-If TECHNICAL.md exists, use it as technical context — reference the stack, architecture, and constraints when exploring the feature's approach. If it doesn't exist, that's fine — technical context is helpful but not required.
+If `docs/TECHNICAL.md` exists, use it as technical context — reference the stack, architecture, and constraints when exploring the feature's approach. If it doesn't exist, that's fine — technical context is helpful but not required.
 
 ### 2. Scan existing features
 
 ```bash
-ls features/*.md 2>/dev/null | sort -V
+ls docs/features/*.md 2>/dev/null | sort -V
 ```
 
 ### 3. Route based on state
@@ -61,74 +123,242 @@ ls features/*.md 2>/dev/null | sort -V
 
 ### Determine next number
 
-Find the highest existing number and increment by 1. Zero-pad to 3 digits. If `features/` doesn't exist, start at `001`.
+Find the highest existing number and increment by 1. Zero-pad to 3 digits. If `docs/features/` doesn't exist, start at `001`.
 
 ### Areas to Explore
 
-These are NOT a rigid sequence. Follow the conversation. Most features only need 2-3 of these to be clear.
+Follow the conversation, not a rigid sequence. Most features need only 2-3 areas.
+
+**Area dependency map (2-pass + optional design):**
+```
+Pass 1: Problem ──→ Value ──→ User Stories (lightweight) ──→ Solution ──→ Scope
+                 │                                                          │
+                 └──→ Success Metric                          Approach (optional)
+
+Pass 2: ──→ Acceptance Criteria (per story: Given-When-Then → AC → edge cases → verification)
+
+Pass 3 (UI features only): ──→ Design Intent (action → outcome → decision → QA verification)
+```
+
+User Stories are captured early (before Solution) to inform what to build. Acceptance Criteria are detailed later (after Scope) because you need to know the solution and boundaries to define concrete verification. Design Intent is captured last — only for features with user-facing UI — so developers know WHY the UI is shaped this way and QA knows what to verify visually.
 
 #### Problem — What's broken or missing?
 
-> Discover: The specific pain this feature addresses. This is not the project-level problem (that's in PROJECT.md) — this is the concrete gap or friction that triggered "we need this feature."
+> The specific pain this feature addresses — not the project-level problem (that's in PROJECT.md).
 
-- What's not working right now? What's the user struggling with?
-- What happens today without this feature? (workaround, manual step, error, confusion...)
-- Who hits this problem and how often?
+**Prerequisites:** None.
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What's not working right now? | — | Decision |
+| What happens today without this? (workaround, manual step...) | what-broken | Fact (scan code) + Decision |
+| Who hits this and how often? | what-broken | Decision |
+
+**Done when:** Frontier empty — the gap is concrete.
 
 #### Value — Why is this worth building?
 
-> Discover: The value this feature delivers and how it connects to the bigger picture.
+**Prerequisites:** Problem settled.
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What changes for the user when this exists? | Problem | Decision |
+| How does this connect to PROJECT.md vision? | Problem | Fact (read PROJECT.md) + Decision |
+| Cost of inaction? | user-change | Decision |
 
-- What changes for the user when this exists?
-- How does this connect to the project's vision or principles in PROJECT.md?
-- What happens if we don't build it? Is there a cost of inaction?
+**Done when:** Frontier empty — value is clear.
+
+#### Success Metric — How do we know this feature succeeded?
+
+> Optional for Bounded features. Required for Architectural features. "Done When" is a build criterion. Success Metric is a launch criterion.
+
+**Prerequisites:** Value settled.
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| After launch, what number changes? (usage count, time saved, error reduction...) | Value | Decision |
+| What's the baseline today, and what's the target? | metric | Decision |
+
+Slots to fill:
+- `{{feature_metric}}`: `{{baseline}}` → `{{target}}`
+
+**Done when:** Frontier empty — at least one measurable outcome exists. Skip for Bounded features if the user declines.
+
+#### User Stories — What does the user actually do? (Pass 1: lightweight)
+
+> Bridge between Value and Solution. Captures WHAT the user does, not HOW we build it. These stories will be enriched with Given-When-Then scenarios and acceptance criteria in Pass 2, after Solution and Scope are defined.
+
+**Prerequisites:** Value settled. Read PROJECT.md Personas section to identify the relevant persona.
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| Which persona from PROJECT.md uses this feature? | Value | Fact (read PROJECT.md Personas) |
+| What does that persona want to accomplish? | persona | Decision |
+| Walk through the scenario — what happens step by step? | want | Decision |
+| Is there a secondary scenario or edge case worth capturing? | scenario | Decision |
+
+Format each story as:
+```
+As a {{persona}}, I want {{action}} so that {{benefit}}.
+```
+
+Slots to fill:
+- 1-3 user stories (title + As a / I want / so that)
+- Brief scenario sketch per story (will be formalized into Given-When-Then in Pass 2)
+
+**Done when:** Frontier empty — at least one user story with a concrete scenario exists. Don't over-detail here — Pass 2 adds the rigor.
 
 #### Solution — How does this solve it?
 
-> Discover: The concrete thing to implement. Not implementation details, but the user-facing shape of the solution.
+**Prerequisites:** Value settled.
 
-- What does this feature do, in one sentence?
-- What does the user see/experience when it's working?
-- Is there an existing pattern in the codebase this builds on?
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What does this feature do, in one sentence? | Value | Decision |
+| What does the user see/experience? | one-sentence | Decision |
+| Existing pattern in codebase to build on? | one-sentence | Fact (scan code) |
+
+**Done when:** Frontier empty — solution is concrete.
 
 #### Scope — Where are the edges?
 
-> Discover: What's in and what's out.
+**Prerequisites:** Solution settled.
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What's included? | Solution | Decision |
+| What's explicitly NOT included? (This is required, not optional — unbounded scope is the #1 feature killer) | includes | Decision |
+| Smallest useful version? | includes, excludes | Decision |
+
+**Done when:** Frontier empty — both Includes AND Excludes are defined. Scope without explicit "Excludes" is unbounded.
+
+#### Acceptance Criteria — The derivation chain (Pass 2)
+
+> This is where User Stories get teeth. Return to each story from Pass 1 and formalize: Given-When-Then scenario → acceptance criteria → edge cases → verification method. Each AC bullet is a test case. Each verification note is a QA checklist item.
+
+**Prerequisites:** Scope settled. All User Stories from Pass 1 are available.
+
+**Process:** For each User Story, walk through this chain:
+
+| Step | Question | Depends on | Type |
+|------|----------|-----------|------|
+| 1 | Formalize the scenario: Given [precondition], When [action], Then [result] | Story from Pass 1 | Decision |
+| 2 | What must be true for this story to be "done"? (one criterion per bullet) | scenario | Decision |
+| 3 | What happens when something goes wrong? (invalid input, empty state, timeout, permission denied...) | happy-path AC | Decision |
+| 4 | Are there boundary conditions? (first item, last item, zero items, max items...) | happy-path AC | Decision |
+| 5 | How would you verify each criterion? (manual check, automated test, visual inspection...) | all ACs | Decision |
+
+Format the output per story:
+```
+### Story: {{story_title}}
+
+**Scenario:**
+- Given: {{precondition}}
+- When: {{user_action}}
+- Then: {{expected_result}}
+
+**Acceptance Criteria:**
+- [ ] {{happy_path_criterion}} — verify: {{method}}
+- [ ] {{edge_case}} — verify: {{method}}
+- [ ] {{error_state}} — verify: {{method}}
+```
+
+**Done when:** Every User Story has:
+- A Given-When-Then scenario
+- At least one happy-path AC
+- At least one edge case or error state AC
+- A verification method per AC
 
-- What's included in this feature?
-- What's explicitly NOT included (even if related)?
-- What's the smallest version that would be useful?
+#### Design Intent — How does the UI guide the user? (Pass 3, UI features only)
 
-#### Done — How do we know it's finished?
+> Bridge between acceptance criteria and implementation. Captures WHY each UI decision was made — so developers know what to build, and QA knows what to verify. **Skip entirely for non-UI features (backend, data, infra).**
 
-> Discover: Acceptance criteria.
+**Prerequisites:** Scope and Acceptance Criteria settled. Feature has user-facing interaction.
 
-- What must be true for this to be "done"?
-- How would you verify it works?
+If the feature has no UI component, skip silently and proceed to Approach or generation.
+
+**Process:** For each User Story's primary interaction, define the intent chain:
+
+| Step | Expected User Action | Ideal Outcome | Design Decision | QA Verification |
+|------|---------------------|---------------|-----------------|-----------------|
+| {{N}} | {{what user does}} | {{what should happen}} | {{how the UI achieves this}} | {{how to verify}} |
+
+Then catalog the essential states:
+
+| State | Trigger | What the user sees |
+|-------|---------|-------------------|
+| Empty | {{trigger}} | {{description — how it guides user to first action}} |
+| Error | {{trigger}} | {{description + recovery path}} |
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| For the primary action in each story: what does the user see, do, and expect? | AC settled | Decision |
+| What does the empty state look like? What guides the user to their first action? | solution | Decision |
+| What does the error state look like? How does the user recover? | AC edge cases | Decision |
+| Is there anything non-obvious about the visual flow that a developer would miss without this context? | all above | Decision |
+
+**Done when:** Every story's primary interaction has an intent row. At least Empty and Error states are defined. This is the lightweight version — for deep UX analysis (heuristic evaluation, prototyping, accessibility audit), run `/know-thy-build:designer` on this feature.
 
 #### Approach — Any technical considerations?
 
 > Optional. Only explore if the user has thoughts or if it's non-obvious.
 
-- Any preferred approach or constraint?
-- Anything tricky to watch out for?
+**Prerequisites:** Solution settled.
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| Preferred approach or constraint? | Solution | Decision |
+| Anything tricky to watch out for? | approach | Fact (scan code) + Decision |
+
+**Done when:** Frontier empty, or user declines to explore.
+
+### Quick Perspective Check
+
+Before generating, do one fast stress-test (skip if everything is obviously solid):
+
+```
+🔍 **Quick check:**
+
+**Interrogator**: {{is the scope actually tight, or is there a hidden rabbit hole?}}
+**End-user**: {{will the user actually notice/care about this feature?}}
+
+Good to go?
+```
 
 ### When to Generate
 
-Offer to generate **as soon as the feature is clear enough to build.** Signs:
+Offer to generate when **all applicable passes are complete.**
+
+Concrete checklist:
+
+**Pass 1 (story → solution → scope):**
+- [ ] Problem frontier empty — gap is concrete
+- [ ] Value frontier empty — worth is clear
+- [ ] User Stories — at least one story with As a / I want / so that
+- [ ] Solution frontier empty — what to build is defined
+- [ ] Scope has both "Includes" AND "Excludes" defined
+- [ ] Success Metric defined (required for Architectural, optional for Bounded)
+
+**Pass 2 (acceptance criteria per story):**
+- [ ] Every User Story has a Given-When-Then scenario
+- [ ] Every story has at least one happy-path AC with verification method
+- [ ] Every story has at least one edge case or error state AC
+- [ ] Quick perspective check passed (or skipped because obviously solid)
 
-- You can describe the feature in 2-3 sentences
-- The scope is bounded
-- There are concrete acceptance criteria
-- The user's answers are getting shorter
+**Pass 3 (design intent — UI features only):**
+- [ ] Design Intent Map covers each story's primary interaction (or skipped: non-UI feature)
+- [ ] Empty and Error states defined
+- [ ] For Architectural features with complex UI: suggest `/know-thy-build:designer` for deep dive
 
-Don't drag the conversation. Features should be quick.
+Don't drag the conversation. Features should be quick — but not shallow.
 
 ### Generate Feature Spec
 
-Create the `features/` directory if it doesn't exist.
+Create the `docs/features/` directory if it doesn't exist.
 
-Write to `features/{{NNN}}.md`:
+Write to `docs/features/{{NNN}}.md`:
 
 **Frontmatter:**
 ```yaml
@@ -136,17 +366,48 @@ Write to `features/{{NNN}}.md`:
 id: {{number}}
 title: {{short_title}}
 status: complete
+priority: {{P0|P1|P2}}
+depends_on: [{{feature_ids}}]
+persona: {{primary_persona_name from PROJECT.md}}
+assumptions:
+  - "{{assumption}}"
 date: {{date}}
 generatedBy: know-thy-build-feature
 ---
 ```
 
-During conversation, use `status: drafting`. On finalization, set to `complete`.
+**Priority guide:**
+- **P0**: Must-have for MVP. Without this, the project doesn't deliver its core value.
+- **P1**: Important. Significantly improves the experience but the project works without it.
+- **P2**: Nice-to-have. Enhances polish or covers edge cases.
+
+Ask the user to assign priority during the Value area. If they resist, recommend based on the feature's connection to PROJECT.md vision.
+
+During conversation, use `status: drafting` with area tracking:
+```yaml
+---
+id: {{number}}
+title: {{short_title_or_TBD}}
+status: drafting
+priority: {{P0|P1|P2}}
+depends_on: [{{feature_ids}}]
+persona: {{primary_persona_name}}
+areasExplored:
+  problem: { decisions: 2 }
+  value: { decisions: 1 }
+areasRemaining: [user-stories, solution, scope, done]
+assumptions:
+  - "{{assumption}}"
+date: {{date}}
+generatedBy: know-thy-build-feature
+---
+```
 
 **Rules:**
 - Only include content from the conversation. No generic filler.
 - Preserve the user's actual words.
 - **Omit sections that weren't discussed.** Shorter is better.
+- **Include brief decision rationale** where a non-obvious choice was made.
 - The entire document MUST be written in {{LANG}}.
 
 **Template structure:**
@@ -164,6 +425,15 @@ During conversation, use `status: drafting`. On finalization, set to `complete`.
 
 <!-- What changes when this exists. Link to PROJECT.md vision/principles if relevant. -->
 
+## Success Metric
+
+<!-- How we know this feature succeeded AFTER launch. Not build criteria — launch criteria.
+     Omit for Bounded features if not discussed. -->
+
+| Metric | Baseline | Target |
+|--------|----------|--------|
+| {{feature_metric}} | {{baseline}} | {{target}} |
+
 ## Solution
 
 <!-- Concrete description of what gets built and how the user experiences it -->
@@ -174,18 +444,62 @@ During conversation, use `status: drafting`. On finalization, set to `complete`.
 <!-- Bulleted list -->
 
 **Excludes:**
-<!-- Bulleted list, only if discussed -->
+<!-- Bulleted list — REQUIRED. Scope without Excludes is unbounded. -->
+
+## User Stories & Acceptance Criteria
+
+<!-- The derivation chain: Story → Scenario → AC → Verification.
+     Each AC bullet is a test case. Each verification note is a QA checklist item.
+     Persona references PROJECT.md Personas section. -->
+
+### Story 1: {{story_title}}
+
+**As a** {{persona}}, **I want** {{action}} **so that** {{benefit}}.
+
+**Scenario:**
+- Given: {{precondition}}
+- When: {{user_action}}
+- Then: {{expected_result}}
 
-## Done When
+**Acceptance Criteria:**
+- [ ] {{happy_path_criterion}} — verify: {{method}}
+- [ ] {{happy_path_criterion_2}} — verify: {{method}}
 
-<!-- Acceptance criteria as a checklist -->
-- [ ] {{criterion_1}}
-- [ ] {{criterion_2}}
+**Edge Cases & Errors:**
+- [ ] {{edge_case}} — verify: {{method}}
+- [ ] {{error_state}} — verify: {{method}}
+
+### Story 2: {{story_title}}
+<!-- Repeat structure. Omit if only one story. -->
+
+## Design Intent
+
+<!-- Optional: only for features with user-facing UI.
+     For deep UX analysis (heuristics, prototyping, accessibility), run /know-thy-build:designer.
+     Developer: read Decision column to know what to build and why.
+     QA: read Action + Outcome + Verification to derive test cases. -->
+
+| Step | User Action | Ideal Outcome | Design Decision | QA Verification |
+|------|-------------|---------------|-----------------|-----------------|
+| {{N}} | {{action}} | {{outcome}} | {{decision}} | {{verification}} |
+
+**Key States:**
+
+| State | Trigger | User Sees |
+|-------|---------|-----------|
+| Empty | {{trigger}} | {{description}} |
+| Error | {{trigger}} | {{description + recovery}} |
 
 ## Approach
 
 <!-- Technical notes, only if discussed -->
 
+## Assumptions
+
+<!-- Beliefs that haven't been validated. Omit if none surfaced. -->
+
+- {{assumption}} — if wrong: {{impact}}
+
 ---
 
 *Generated by know-thy-build-feature | {{date}}*
@@ -200,7 +514,7 @@ When the user chooses to edit an existing feature by number:
 ### 1. Read the feature
 
 ```bash
-cat features/{{NNN}}.md 2>/dev/null
+cat docs/features/{{NNN}}.md 2>/dev/null
 ```
 
 ### 2. Present the current state
@@ -239,27 +553,36 @@ If the change is substantial, add a brief note at the bottom:
 
 ## Saving Progress
 
-If the conversation is interrupted before generation, save progress immediately:
+If the conversation is interrupted before generation, save progress immediately using the drafting frontmatter format (with `areasExplored`, `areasRemaining`, and `assumptions`).
 
-```yaml
----
-id: {{number}}
-title: {{short_title_or_TBD}}
-status: drafting
-date: {{date}}
-generatedBy: know-thy-build-feature
----
-```
+Write whatever content has been confirmed so far. The next `/know-thy-build:feature` run will detect the drafting state, read the area tracking, and offer to resume from where the frontier was.
+
+## Update Feature Registry
+
+After creating or editing a feature, update the Feature Registry in `docs/PROJECT.md`:
+
+1. Read `docs/PROJECT.md` and find the `## Feature Registry` section.
+2. If the section doesn't exist, append it (use the template from the project skill).
+3. Add or update the row for this feature:
+   ```
+   | {{id}} | [{{title}}](features/{{NNN}}.md) | {{priority}} | {{depends_on}} | {{status}} |
+   ```
+4. If `depends_on` references other features, verify those feature IDs exist.
 
-Write whatever content has been confirmed so far. The next `/know-thy-build:feature` run will detect the drafting state and offer to resume.
+This keeps PROJECT.md as the single entry point for the full project picture.
 
 ## Closing
 
 **After CREATE:**
-- Feature spec has been saved to `features/{{NNN}}.md`
-- They can start implementing whenever ready
+- Feature spec has been saved to `docs/features/{{NNN}}.md`
+- Feature Registry in `docs/PROJECT.md` has been updated
+- **Next step (mandatory):** `/know-thy-build:qa` — define test cases in `docs/QA.md`. This is what makes "done" concrete. Without test cases, there is no definition of "done."
+- Optional next steps:
+  - **UX deep dive**: `/know-thy-build:designer` — if this feature has complex UI
+  - **Implementation design**: `/know-thy-build:architect` — if this feature is Architectural
 - Run `/know-thy-build:feature` again for the next feature
 
 **After EDIT:**
 - Feature spec has been updated
+- Feature Registry in `docs/PROJECT.md` has been updated if priority, status, or dependencies changed
 - Changes are recorded if substantial