jettypod 4.4.118 → 4.4.121

package/skills-templates/feature-planning/SKILL.md

@@ -11,7 +11,7 @@ Guides Claude through feature planning including UX approach exploration, option
 
 When this skill is activated, you are helping discover the best approach for a feature. Follow this structured approach:
 
-## 🔑 Critical Command Distinction
+## Critical Command Distinction
 
 **Six commands in workflow order:**
 
@@ -32,9 +32,9 @@ When this skill is activated, you are helping discover the best approach for a f
 - `work tests merge` = Land BDD tests on main
 - `work start` = Creates worktree/branch for chore implementation
 
-**🛑 STOP GATE:** DO NOT run `work start` until Step 13. Tests must be merged to main first.
+**STOP GATE:** DO NOT run `work start` until Step 13. Tests must be merged to main first.
 
-**🛑 HANDOFF REQUIREMENT:** After `work start`, you MUST invoke speed-mode using the Skill tool. See Step 13.
+**HANDOFF REQUIREMENT:** After `work start`, you MUST invoke speed-mode using the Skill tool. See Step 13.
 
 ---
 
@@ -58,7 +58,7 @@ This returns: title, description, parent epic (if any), mode, phase, and any exi
 
 **If the feature is not found**, ask the user to verify the ID or run `jettypod backlog` to find it.
 
-**🔄 WORKFLOW INTEGRATION: Start workflow tracking**
+**WORKFLOW INTEGRATION: Start workflow tracking**
 
 After getting the feature context, register this skill execution:
 
@@ -87,10 +87,10 @@ This outputs any architectural decisions recorded for the parent epic. If no dec
 Display the context with decisions:
 
 ```
-✨ Planning Feature: [Feature Name]
+Planning Feature: [Feature Name]
 Epic: [Epic Name]
 
-🎯 **Epic Architectural Decisions:**
+**Epic Architectural Decisions:**
 [If decisions exist:]
 - **[Aspect]:** [Decision]
   *Rationale:* [Why this was chosen]
@@ -114,25 +114,25 @@ Propose exactly 3 approaches with varying complexity/trade-offs:
 Here are 3 different approaches for [feature name]:
 
 **Option 1: [Simple/Minimal approach name]**
-- **Pros**: ✅ [2-3 advantages]
-- **Cons**: ❌ [2-3 trade-offs]
+- **Pros**: [2-3 advantages]
+- **Cons**: [2-3 trade-offs]
 - **Experience**: [What it feels like to use]
 
 **Option 2: [Balanced approach name]**
-- **Pros**: ✅ [2-3 advantages]
-- **Cons**: ❌ [2-3 trade-offs]
+- **Pros**: [2-3 advantages]
+- **Cons**: [2-3 trade-offs]
 - **Experience**: [What it feels like to use]
 
 **Option 3: [Advanced/Comprehensive approach name]**
-- **Pros**: ✅ [2-3 advantages]
-- **Cons**: ❌ [2-3 trade-offs]
+- **Pros**: [2-3 advantages]
+- **Cons**: [2-3 trade-offs]
 - **Experience**: [What it feels like to use]
 
 **Additional approaches considered but not recommended:**
 - *[Alternative 1]*: [Brief] - Not selected because [reason]
 - *[Alternative 2]*: [Brief] - Not selected because [reason]
 
-**💡 Recommendation:** [State which option you recommend and why - 2-3 sentences explaining the reasoning]
+**Recommendation:** [State which option you recommend and why - 2-3 sentences explaining the reasoning]
 
 Would you like me to create working prototypes of these approaches?
 ```
@@ -140,7 +140,7 @@ Would you like me to create working prototypes of these approaches?
 **After presenting approaches, emit a question gate so the narrated UI can render an interactive choice card:**
 
 ```bash
-jettypod ui gate question --data='{"question":"Which approach should we take for [feature name]?","options":[{"id":"option-1","emoji":"🎯","label":"[Simple approach name]","description":"[1-line summary of what it does]"},{"id":"option-2","emoji":"⚖️","label":"[Balanced approach name]","description":"[1-line summary of what it does]"},{"id":"option-3","emoji":"🛡️","label":"[Advanced approach name]","description":"[1-line summary of what it does]"}]}'
+jettypod ui gate question --data='{"question":"Which approach should we take for [feature name]?","options":[{"id":"option-1","emoji":"","label":"[Simple approach name]","description":"[1-line summary of what it does]"},{"id":"option-2","emoji":"","label":"[Balanced approach name]","description":"[1-line summary of what it does]"},{"id":"option-3","emoji":"","label":"[Advanced approach name]","description":"[1-line summary of what it does]"}]}'
 ```
 
 **WAIT for user response.**
@@ -165,10 +165,16 @@ jettypod work prototype start 42 simple-form
 
 This creates a worktree at `.jettypod-work/prototype-<id>-<slug>-<approach>/` where prototypes can be safely built and committed.
 
-**🛑 STOP AND CHECK:** Verify worktree was created successfully before proceeding.
+**STOP AND CHECK:** Verify worktree was created successfully before proceeding.
 
 **Sub-step 2: Build prototypes in the worktree**
 
+**Design system check:** Before building, check if a design system directory is configured:
+```bash
+node -e "const c=JSON.parse(require('fs').readFileSync('.jettypod/config.json','utf-8')); c.designSystemDir && console.log(c.designSystemDir)"
+```
+If a path is returned, read the files in that directory and apply the project's design tokens (colors, typography, spacing, border radii, component patterns) to all prototypes. Prototypes should look like they belong to the product, not use generic browser defaults.
+
 1. **Build prototypes** using **absolute paths** to the worktree:
    - `<worktree_path>/prototypes/feature-[id]-[approach-name]/`
 2. **Name format**: `YYYY-MM-DD-[feature-slug]-[option].ext`
@@ -176,7 +182,7 @@ This creates a worktree at `.jettypod-work/prototype-<id>-<slug>-<approach>/` wh
 4. **Add visible banner header at TOP of page** (for HTML/web prototypes):
    ```html
    <div style="background: #f0f0f0; border: 2px solid #333; padding: 16px; margin-bottom: 24px; font-family: monospace;">
-     <strong>🧪 PROTOTYPE</strong><br>
+     <strong>PROTOTYPE</strong><br>
      Feature: [feature name]<br>
      Option: [option number/name]<br>
      Created: [YYYY-MM-DD]<br>
@@ -208,7 +214,7 @@ jettypod work cleanup ${FEATURE_ID}
 This merges prototype files to main (in `/prototypes/` directory) and cleans up the worktree.
 
 <details>
-<summary><strong>📋 Prototyping Guidelines (click to expand)</strong></summary>
+<summary><strong>Prototyping Guidelines (click to expand)</strong></summary>
 
 **Use fastest tech to demonstrate UX:**
 - Quick HTML+JS for web UX
@@ -241,12 +247,65 @@ Which approach works best?
 
 User picks winner. Note their choice - you'll record it formally in Step 11 when transitioning to implementation.
 
-**🔄 WORKFLOW CHECKPOINT: Winner chosen**
+**WORKFLOW CHECKPOINT: Winner chosen**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=5
 ```
 
+**Proceed to Step 5B.**
+
+### Step 5B: UX States Inventory
+
+**CRITICAL:** Before defining scenarios, enumerate every UI state the feature will need. Features fail QA when states like loading, empty, and transition are left unspecified — Claude implements the literal happy path and skips everything else.
+
+**For each screen/view/component the chosen approach touches, list:**
+
+```
+UX States Inventory
+
+**[Screen/View/Component 1: e.g., Login Form]**
+| State | What the user sees |
+|-------|-------------------|
+| Default | [Initial state when user arrives] |
+| Loading | [What shows during async operations — spinner, skeleton, disabled button, etc.] |
+| Success | [Feedback after successful action — toast, redirect, animation, message] |
+| Empty | [What shows when there's no data — illustration, CTA, placeholder text] |
+| Partial | [What shows when some data is loaded but not all — progressive loading] |
+
+**[Screen/View/Component 2: e.g., Dashboard after login]**
+| State | What the user sees |
+|-------|-------------------|
+| Default | [...] |
+| Loading | [...] |
+| ... | ... |
+
+**Micro-interactions:**
+- [Button click] → [immediate visual feedback: disable + spinner? ripple? color change?]
+- [Form submission] → [what happens between click and response?]
+- [Data appears] → [instant swap? fade in? skeleton → content?]
+- [Navigation] → [instant page swap? transition animation?]
+```
+
+**What to inventory (checklist):**
+- [ ] Every screen/view the feature adds or modifies
+- [ ] Loading states for every async operation (API calls, file uploads, data fetches)
+- [ ] Success feedback for every user action (toasts, redirects, inline messages)
+- [ ] Empty states where data might not exist yet
+- [ ] Transition animations between states
+- [ ] Button/input states (default, hover, active, disabled, loading)
+- [ ] What happens between user action and system response (micro-interactions)
+
+**Display the inventory to user and ask:**
+
+```
+Does this cover all the states? Anything missing for how this should feel?
+```
+
+**WAIT for user confirmation or additions.**
+
+Store the confirmed UX States Inventory — it feeds into BDD scenarios (Step 8) and chore UX acceptance criteria (Step 10).
+
 **Proceed to Step 6.**
 
 ### Step 6: Define Integration Contract
@@ -274,7 +333,7 @@ jettypod workflow checkpoint <feature-id> --step=5
 **Display to user:**
 
 ```
-📍 Integration Contract
+Integration Contract
 
 **Entry Point:** [How users reach this feature]
 **Caller Code:** [What existing code invokes this]
@@ -297,11 +356,11 @@ Example:
 2. Claude has `WORKTREE_PATH` before being tempted to write files
 3. Writing to main is impossible because we're in worktree context
 
-**🚫 FORBIDDEN: Manual Git Worktree Commands**
+**FORBIDDEN: Manual Git Worktree Commands**
 ```
-❌ git worktree add ...
-❌ git checkout -b tests/...
-❌ git branch tests/...
+git worktree add ...
+git checkout -b tests/...
+git branch tests/...
 ```
 **ALWAYS use jettypod commands** - they handle branch naming, path conventions, database tracking, and cleanup. Manual git commands will create orphaned worktrees that break the merge workflow.
 
@@ -315,14 +374,14 @@ This creates:
 - Worktree at `.jettypod-work/tests-<id>-<slug>/`
 - Branch `tests/feature-<id>-<slug>`
 
-**🛑 STOP AND CHECK:** Verify worktree was created successfully. If you see an error, investigate before continuing.
+**STOP AND CHECK:** Verify worktree was created successfully. If you see an error, investigate before continuing.
 
 **Capture from output:**
 - `WORKTREE_PATH` - the absolute path to the worktree (e.g., `/path/to/.jettypod-work/tests-42-email-login`)
 
 Example output:
 ```
-✅ Created test worktree: /path/to/.jettypod-work/tests-42-email-login
+Created test worktree: /path/to/.jettypod-work/tests-42-email-login
 Branch: tests/feature-42-email-login
 
 Write your BDD files to:
@@ -333,13 +392,13 @@ Write your BDD files to:
 **Display:**
 
 ```
-📁 Test worktree created: ${WORKTREE_PATH}
+Test worktree created: ${WORKTREE_PATH}
 Branch: tests/feature-${FEATURE_ID}-${FEATURE_SLUG}
 
-🔒 WORKTREE LOCK ACTIVE: All BDD file writes will use this path.
+WORKTREE LOCK ACTIVE: All BDD file writes will use this path.
 ```
 
-**🔒 WORKTREE PATH LOCK**
+**WORKTREE PATH LOCK**
 
 From this point forward, ALL file operations for BDD tests MUST use paths starting with:
 ```
@@ -350,13 +409,17 @@ ${WORKTREE_PATH}/features/
 
 **Proceed to Step 8.**
 
+### BDD Scenario Formulation Rules (ENFORCED)
+
+Before proposing scenarios, read `templates/bdd-guidance.md`. Scenarios MUST be: declarative (describe intent, not UI clicks), one behavior per scenario, deterministic (factory data, not ambient), no implementation leakage ("Given a user with an unpaid invoice" not "Given the database has a row in invoices"). No UI specifics unless the feature IS a UI interaction.
+
 ### Step 8: Propose BDD Scenarios
 
-**🚫 FORBIDDEN: Writing Files at This Step**
+**FORBIDDEN: Writing Files at This Step**
 ```
-❌ Write tool to ${WORKTREE_PATH}/features/*.feature
-❌ Write tool to ${WORKTREE_PATH}/features/step_definitions/*.js
-❌ Any file creation (even in worktree)
+Write tool to ${WORKTREE_PATH}/features/*.feature
+Write tool to ${WORKTREE_PATH}/features/step_definitions/*.js
+Any file creation (even in worktree)
 ```
 **Files are written in Step 9** after user confirms the scenarios. At this step, you are ONLY displaying proposed scenarios to the user for confirmation.
 
@@ -369,7 +432,7 @@ ${WORKTREE_PATH}/features/
 Based on chosen approach, **display** the proposed scenarios to the user:
 
 ```
-📋 Proposed BDD Scenarios
+Proposed BDD Scenarios
 
 **Feature file:** ${WORKTREE_PATH}/features/[feature-slug].feature
 **Step definitions:** ${WORKTREE_PATH}/features/step_definitions/[feature-slug].steps.js
@@ -431,6 +494,11 @@ Does this capture the feature correctly? Any scenarios to add/change?
   - NO error handling scenarios (added in stable mode)
   - NO validation failures (added in stable mode)
   - NO security/compliance scenarios (added in production mode)
+- **Incorporate UX states from Step 5B** into scenario Then/And steps:
+  - Loading indicators: "And I see a loading indicator while [action] completes"
+  - Success feedback: "And I see a success confirmation"
+  - Empty states: "Then I see an empty state with [description]"
+  - Transitions: "And the [content] appears with [transition description]"
 
 **WAIT for user confirmation.**
 
@@ -438,7 +506,7 @@ Does this capture the feature correctly? Any scenarios to add/change?
 - If user requests changes → Revise scenarios and display again
 - **Store the confirmed scenarios in memory** - you'll write them in Step 9
 
-**🔄 WORKFLOW CHECKPOINT: BDD scenarios confirmed**
+**WORKFLOW CHECKPOINT: BDD scenarios confirmed**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=8
@@ -520,7 +588,7 @@ Scenario: User logs in with "Remember me" option (optional feature)
 ```
 
 <details>
-<summary><strong>📋 BDD Scenario Guidelines (click to expand)</strong></summary>
+<summary><strong>BDD Scenario Guidelines (click to expand)</strong></summary>
 
 **Scenario naming:**
 - Use present tense
@@ -573,7 +641,7 @@ Scenario: Prevent unauthorized access
 
 **NOW you may write files** - the worktree exists (from Step 7) and scenarios are confirmed (from Step 8).
 
-**🔒 WORKTREE PATH REQUIRED:** All file writes MUST use the `WORKTREE_PATH` captured in Step 7.
+**WORKTREE PATH REQUIRED:** All file writes MUST use the `WORKTREE_PATH` captured in Step 7.
 
 Using the scenarios confirmed in Step 8, write the files using **absolute paths to the worktree**:
 
@@ -605,14 +673,14 @@ cd ${WORKTREE_PATH} && npx cucumber-js --dry-run features/${FEATURE_SLUG}.featur
 
 **What the output means:**
 
-✅ **Success** - No errors, all steps have definitions:
+**Success** - No errors, all steps have definitions:
 ```
 0 scenarios
 0 steps
 ```
 (Dry-run doesn't execute, so 0 is correct)
 
-❌ **Undefined steps** - Missing step definitions:
+**Undefined steps** - Missing step definitions:
 ```
 Undefined. Implement with the following snippet:
   Given('I am on the login page', function () {
@@ -621,13 +689,13 @@ Undefined. Implement with the following snippet:
 ```
 → Add the missing step definition to your `.steps.js` file
 
-❌ **Syntax error** - Invalid Gherkin:
+**Syntax error** - Invalid Gherkin:
 ```
 Parse error in features/foo.feature
 ```
 → Fix the feature file syntax
 
-❌ **Duplicate steps** - Multiple definitions match:
+**Duplicate steps** - Multiple definitions match:
 ```
 Multiple step definitions match
 ```
@@ -640,7 +708,7 @@ Multiple step definitions match
 4. **Loop until validation passes** - do NOT proceed until green
 
 **If validation succeeds:**
-Display: "✅ BDD infrastructure validated - all steps have definitions"
+Display: "BDD infrastructure validated - all steps have definitions"
 
 **Update database with scenario file path:**
 
@@ -677,7 +745,7 @@ Now let me analyze the codebase and propose implementation chores for speed mode
 
 Based on the scenario and my understanding of the codebase, here are the chores I recommend for speed mode:
 
-**Chore 1: [Integration chore - wire feature into app]** ⚡ INTEGRATION
+**Chore 1: [Integration chore - wire feature into app]** INTEGRATION
 - Why: Makes the feature reachable from [entry point]
 - Integration Contract:
   • Entry point: [from Step 6]
@@ -698,6 +766,11 @@ Based on the scenario and my understanding of the codebase, here are the chores
   • Files to create/modify: [specific paths]
   • Patterns to follow: [reference existing similar code]
   • Key functions/components needed: [list]
+- UX acceptance criteria (from Step 5B):
+  • [Loading state: what shows during async operations in this chore's scope]
+  • [Success feedback: what the user sees after the action completes]
+  • [Empty state: what shows when there's no data, if applicable]
+  • [Micro-interactions: button states, transitions, visual feedback]
 - Verification:
   • [Which step definitions should pass]
 
@@ -739,18 +812,24 @@ Does this rationale capture why you chose this approach? (You can edit it if nee
 
 **CRITICAL: Create chores BEFORE running `work implement`.** The system validates that chores exist before allowing the transition.
 
-For each chore that the user confirmed in Step 10, use the Bash tool to create it:
-
-```bash
-jettypod work create chore "[Chore title]" "[Chore description]" --parent=${FEATURE_ID}
+For each chore that the user confirmed in Step 10, use the **Write** tool to create `/tmp/jettypod-create.json`:
+```json
+{
+  "type": "chore",
+  "title": "[Chore title]",
+  "description": "[Chore description]",
+  "parent": ${FEATURE_ID}
+}
 ```
 
-Replace `${FEATURE_ID}` with actual ID. Example:
+Then run via **Bash**:
 ```bash
-jettypod work create chore "Set up auth routes" "Create login/logout endpoints..." --parent=42
+jettypod work create --from=/tmp/jettypod-create.json
 ```
 
-**CRITICAL: Copy the EXACT proposal from Step 10 into each chore description.** Do not paraphrase or summarize - the implementation guidance must be preserved verbatim:
+Replace `${FEATURE_ID}` with actual ID. Example: Write `{"type":"chore","title":"Set up auth routes","description":"Create login/logout endpoints...","parent":42}` to `/tmp/jettypod-create.json`, then run `jettypod work create --from=/tmp/jettypod-create.json`.
+
+**CRITICAL: Copy the EXACT proposal from Step 10 into each chore description.** Do not paraphrase or summarize - the implementation guidance AND UX acceptance criteria must be preserved verbatim:
 
 ```
 [Technical description from Step 10]
@@ -763,6 +842,9 @@ Implementation guidance:
 • Patterns to follow: [EXACT references from Step 10]
 • Key functions/components needed: [EXACT list from Step 10]
 
+UX acceptance criteria:
+• [EXACT UX criteria from Step 10 — loading states, success feedback, empty states, micro-interactions]
+
 Verification:
 • [EXACT step definitions from Step 10]
 ```
@@ -792,13 +874,13 @@ jettypod work implement 42 --winner="Simple inline form" --rationale="Fastest UX
 After successful transition, display:
 
 ```
-✅ Feature transitioned to implementation phase
-✅ Created X chores for speed mode
+Feature transitioned to implementation phase
+Created X chores for speed mode
 
 Now I'll merge the BDD tests to main...
 ```
 
-**🔄 WORKFLOW CHECKPOINT: Implementation transition complete**
+**WORKFLOW CHECKPOINT: Implementation transition complete**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=11
@@ -817,6 +899,8 @@ The BDD files were written in Step 9. Now merge them to main.
 jettypod work tests merge ${FEATURE_ID}
 ```
 
+**If merge fails with `Uncommitted changes detected`:** `git stash` from main repo CWD → create a work item for the stashed changes → `jettypod work start <id>` → `git stash pop` in that worktree → commit → merge → cleanup → then retry your original merge.
+
 ```bash
 # Step 2: cd to main repo
 cd <main-repo-path>
@@ -834,33 +918,33 @@ This will:
 - Push to remote
 - Mark worktree as merged (cleanup is separate)
 
-**🛑 STOP AND CHECK:** Verify merge succeeded:
-- ✅ "Tests merged to main" → Proceed to Step 13
-- ❌ Error → Investigate, worktree still exists for debugging
+**STOP AND CHECK:** Verify merge succeeded:
+- "Tests merged to main" → Proceed to Step 13
+- Error → Investigate, worktree still exists for debugging
 
 **After successful merge, display:**
 
 ```
-✅ Feature transitioned to implementation phase
-✅ Created X chores for speed mode
-✅ BDD tests merged to main
+Feature transitioned to implementation phase
+Created X chores for speed mode
+BDD tests merged to main
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Feature Planning Complete!
+Feature Planning Complete!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-📋 BDD scenarios: features/[feature-slug].feature
-🧪 Step definitions: features/step_definitions/[feature-slug].steps.js
-✅ Feature phase: Implementation
-🚀 Feature mode: Speed
+BDD scenarios: features/[feature-slug].feature
+Step definitions: features/step_definitions/[feature-slug].steps.js
+Feature phase: Implementation
+Feature mode: Speed
 
-💡 Recommendation: Start with Chore #[first-chore-id] ([chore-title])
+Recommendation: Start with Chore #[first-chore-id] ([chore-title])
    [Brief reasoning - e.g., "It sets up the foundation the other chores depend on."]
 
 Start this one? [yes / pick different / done for now]
 ```
 
-**🔄 WORKFLOW INTEGRATION: Complete workflow**
+**WORKFLOW INTEGRATION: Complete workflow**
 
 ```bash
 jettypod workflow complete feature-planning <feature-id>
@@ -897,11 +981,11 @@ End feature-planning skill without starting a chore. Do NOT invoke speed-mode.
 
 **After user picks a chore, execute these steps IN ORDER:**
 
-**🚫 FORBIDDEN: Manual Git Worktree Commands**
+**FORBIDDEN: Manual Git Worktree Commands**
 ```
-❌ git worktree add ...
-❌ git checkout -b feature/...
-❌ git branch feature/...
+git worktree add ...
+git checkout -b feature/...
+git branch feature/...
 ```
 **ALWAYS use `jettypod work start`** - it handles branch naming, path conventions, database tracking, and cleanup. Manual git commands will create orphaned worktrees that break the merge workflow.
 
@@ -910,17 +994,17 @@ End feature-planning skill without starting a chore. Do NOT invoke speed-mode.
 jettypod work start [chore-id]
 ```
 
-**🛑 STOP AND CHECK:** Look at the output of `work start`. You should see:
+**STOP AND CHECK:** Look at the output of `work start`. You should see:
 ```
-✅ Created worktree: /path/to/.jettypod-work/[id]-[title-slug]
+Created worktree: /path/to/.jettypod-work/[id]-[title-slug]
 Branch: feature/work-[id]-[title-slug]
 ```
 
-**If you see `⚠️ Working in main repository (worktree creation failed)`:**
+**If you see `Working in main repository (worktree creation failed)`:**
 - **DO NOT proceed to speed-mode**
 - Investigate why worktree failed (uncommitted changes? branch conflict?)
 - Fix the issue and re-run `work start`
-- Only continue after seeing `✅ Created worktree`
+- Only continue after seeing `Created worktree`
 
 **Step 2: Verify worktree exists before invoking speed-mode:**
 ```bash
@@ -937,7 +1021,7 @@ If this returns empty/no rows, **STOP** - the worktree wasn't created properly.
 Use the Skill tool with skill: "speed-mode"
 ```
 
-**🛑 CRITICAL:** You MUST:
+**CRITICAL:** You MUST:
 1. Run `work start` first
 2. Verify the worktree was created (not fallback to main)
 3. THEN invoke speed-mode using the Skill tool
@@ -958,6 +1042,20 @@ If you skip `work start` or proceed when worktree creation failed, the merge wor
 
 **User picks:** Option 1 (Simple inline form)
 
+**UX States Inventory:**
+
+| State | Login Form | Dashboard (after login) |
+|-------|-----------|----------------------|
+| Default | Email + password fields, "Sign In" button | N/A (redirected here) |
+| Loading | Button shows spinner, fields disabled | Skeleton cards for activity |
+| Success | Brief checkmark animation, then redirect | Full dashboard with welcome toast |
+| Empty | N/A | "No recent activity" with illustration |
+
+**Micro-interactions:**
+- Sign In click → button disabled + spinner → redirect on success
+- "Remember me" checkbox → toggle animation
+- Page transition → fade/slide to dashboard
+
 **Scenarios generated (speed mode - all success paths):**
 ```gherkin
 Feature: Email/Password Login
@@ -992,6 +1090,7 @@ Before completing feature planning, ensure:
 - [ ] Epic's architectural decision is shown (if exists)
 - [ ] Exactly 3 approaches suggested
 - [ ] Winner chosen (with prototypes or without)
+- [ ] **UX States Inventory completed** (all screens/states/micro-interactions enumerated, confirmed by user)
 - [ ] **Integration Contract defined** (entry point, caller code, integration scenario)
 - [ ] **Test worktree created** with `work tests start` (Step 7)
 - [ ] **Integration Scenario is FIRST scenario** in proposed scenarios