jettypod 4.4.70 → 4.4.72

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

@@ -0,0 +1,387 @@
+---
+name: bug-planning
+description: Guide structured bug investigation with symptom capture, hypothesis testing, and root cause identification. Creates bug work item with fix chore and regression tests. Use when user reports a bug, mentions unexpected behavior, or says "investigate bug".
+---
+
+# Bug Planning Skill
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Bug Planning Flow                                                  │
+│                                                                     │
+│  Symptom → Hypothesis → Evidence → Root Cause → Chore → Tests       │
+│                                                                     │
+│  Output: Bug work item, fix chore with breadcrumbs, regression test │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+Guides Claude through systematic bug investigation. Produces actionable fix chores with clear breadcrumbs.
+
+## Instructions
+
+When this skill is activated, you are investigating a bug to identify root cause and plan the fix.
+
+---
+
+## Phase 1: Symptom Capture
+
+**Goal:** Understand exactly what's happening before investigating.
+
+**Gather from user:**
+
+```
+🐛 Bug Investigation
+
+I need to understand the bug before we investigate.
+
+**What's happening?**
+> [User describes the problem]
+
+**What should happen instead?**
+> [Expected behavior]
+
+**Reproduction steps?**
+> [How to trigger the bug]
+
+**Any error messages?**
+> [Exact error text, stack traces]
+
+**When did it start?**
+> [ ] Always been broken
+> [ ] After a specific change (which?)
+> [ ] Not sure
+```
+
+**If user provides partial info**, ask follow-up questions. Don't proceed until you have:
+- Clear actual vs expected behavior
+- Reproduction steps (or acknowledgment it's intermittent)
+- Error messages if any
+
+**Document symptoms:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 Bug Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Symptom:** [What's happening]
+**Expected:** [What should happen]
+**Reproduction:** [Steps]
+**Error:** [Error message if any]
+**Context:** [When it started, related changes]
+
+Proceeding to hypothesis formation...
+```
+
+**Proceed to Phase 2.**
+
+---
+
+## Phase 2: Hypothesis Formation
+
+**Goal:** Form testable theories about what might cause the bug.
+
+**CRITICAL:** Execute autonomously - no user input needed.
+
+**Your task:**
+1. Analyze symptoms for clues
+2. Search codebase for relevant code
+3. Check recent changes (git log)
+4. Form 2-4 testable hypotheses
+5. Rank by likelihood
+
+**Codebase analysis:**
+
+```bash
+# Search for code related to the failing functionality
+# Use Glob/Grep based on keywords from symptoms
+```
+
+```bash
+# Check recent changes to relevant files
+git log --oneline -10 -- <relevant-files>
+```
+
+**Display hypotheses:**
+
+```
+🔍 Hypotheses
+
+Based on symptoms and codebase analysis:
+
+**H1 (Most Likely): [Title]**
+- Theory: [What might be wrong]
+- Test: [How to confirm/eliminate]
+- Files: [Specific files to check]
+
+**H2: [Title]**
+- Theory: [What might be wrong]
+- Test: [How to confirm/eliminate]
+- Files: [Specific files to check]
+
+**H3: [Title]**
+- Theory: [What might be wrong]
+- Test: [How to confirm/eliminate]
+- Files: [Specific files to check]
+
+Starting evidence gathering with H1...
+```
+
+**Proceed to Phase 3.**
+
+---
+
+## Phase 3: Evidence Gathering
+
+**Goal:** Test hypotheses systematically until root cause is found.
+
+**CRITICAL:** Test one hypothesis at a time. Document findings.
+
+**For each hypothesis:**
+
+1. **Read relevant code** (Read tool)
+2. **Add diagnostics if needed** (temporary logging)
+3. **Evaluate evidence** - supports, refutes, or partial?
+
+**Display progress:**
+
+```
+━━━ Testing H1: [Title] ━━━
+
+📂 Reading: [file:lines]
+🔎 Looking for: [specific issue]
+
+**Finding:** [What you discovered]
+
+**Verdict:** ✅ CONFIRMED / ❌ ELIMINATED / ⚠️ PARTIAL
+```
+
+**If ELIMINATED:** Move to next hypothesis.
+**If PARTIAL:** Gather more evidence.
+**If CONFIRMED:** Proceed to Phase 4.
+
+**If all hypotheses eliminated:**
+
+```
+⚠️ Initial hypotheses eliminated
+
+What we learned:
+- H1: Eliminated because [reason]
+- H2: Eliminated because [reason]
+
+Forming new hypotheses...
+```
+
+Loop back to Phase 2 with new information.
+
+**Proceed to Phase 4 when root cause confirmed.**
+
+---
+
+## Phase 4: Root Cause Confirmation
+
+**Goal:** Confirm root cause with user before creating work items.
+
+**⚡ ASYNC BOUNDARY - Wait for user confirmation**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 Root Cause Identified
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**What's broken:** [Specific code/logic]
+**Why:** [The actual cause]
+**Location:** [file:line]
+**Evidence:** [What confirmed this]
+
+**Proposed fix:**
+[Brief description of how to fix it]
+
+Does this match your understanding? Ready to create the fix chore?
+```
+
+**WAIT for user confirmation.**
+
+If user disagrees or adds context, revise understanding and confirm again.
+
+**Proceed to Phase 5.**
+
+---
+
+## Phase 5: Create Bug Work Item and Chore
+
+**Goal:** Create tracked work items for the fix.
+
+**Check for parent context:**
+
+```bash
+# If bug is related to a feature/epic, user may specify parent
+# Otherwise create standalone bug
+```
+
+**Create bug work item:**
+
+```bash
+# Standalone bug
+jettypod work create bug "[Bug title - brief description]"
+
+# OR with parent
+jettypod work create bug "[Bug title]" --parent=<feature-or-epic-id>
+```
+
+**Capture the bug ID from output.**
+
+**Create fix chore with breadcrumbs:**
+
+```bash
+jettypod work create chore "Fix: [brief description]" "[Full description with breadcrumbs]" --parent=<bug-id>
+```
+
+**Chore description must include:**
+
+```
+Root cause: [What's broken and why]
+Location: [file:line]
+
+Fix approach:
+- [Step 1]
+- [Step 2]
+
+Files to modify:
+- [file1]: [what to change]
+- [file2]: [what to change]
+
+Verification:
+- Regression test passes
+- Original bug no longer reproduces
+- [Any other checks]
+```
+
+**Proceed to Phase 6.**
+
+---
+
+## Phase 6: Write Regression Test
+
+**Goal:** Create BDD scenario that fails now, passes after fix.
+
+**🚫 FORBIDDEN: Writing directly to main**
+```
+❌ Write to features/*.feature on main
+❌ Manual git commands for worktrees
+```
+
+**Create test worktree:**
+
+```bash
+jettypod work tests start <bug-id>
+```
+
+**Capture worktree path from output.**
+
+**Derive feature slug** from bug title (lowercase, hyphens, no special chars).
+
+**Write regression test in worktree:**
+
+Feature file at `<worktree>/features/<bug-slug>.feature`:
+
+```gherkin
+Feature: [Bug title] - Regression Test
+  Prevents regression of bug #<bug-id>
+
+  Root cause: [Brief description]
+
+  Scenario: [Description of correct behavior]
+    Given [setup that triggers the bug condition]
+    When [action that previously caused the bug]
+    Then [expected correct behavior]
+    And [additional verifications]
+```
+
+Step definitions at `<worktree>/features/step_definitions/<bug-slug>.steps.js`
+
+**Validate with dry-run:**
+
+```bash
+cd <worktree> && npx cucumber-js --dry-run features/<bug-slug>.feature
+```
+
+Fix any undefined steps or syntax errors.
+
+**Merge tests:**
+
+```bash
+# Commit
+cd <worktree> && git add features/ && git commit -m "test: Add regression test for bug #<bug-id>"
+```
+
+```bash
+# Merge (from worktree is OK)
+jettypod work tests merge <bug-id>
+```
+
+```bash
+# cd to main repo
+cd <main-repo-path>
+```
+
+```bash
+# Cleanup worktree
+jettypod work cleanup <bug-id>
+```
+
+**Proceed to Phase 7.**
+
+---
+
+## Phase 7: Hand Off to Bug Mode
+
+**Display completion:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Bug Planning Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Bug: #<bug-id> [title]
+🔧 Fix chore: #<chore-id> [title]
+🧪 Regression test: features/<bug-slug>.feature
+
+Ready to implement the fix?
+```
+
+**WAIT for user response.**
+
+**If user confirms:**
+
+```bash
+jettypod work start <chore-id>
+```
+
+**Verify worktree created:**
+
+```bash
+sqlite3 .jettypod/work.db "SELECT worktree_path FROM worktrees WHERE work_item_id = <chore-id> AND status = 'active'"
+```
+
+**Then invoke bug-mode:**
+
+```
+Use the Skill tool with skill: "bug-mode"
+```
+
+**Bug-planning skill complete.**
+
+---
+
+## Validation Checklist
+
+Before completing bug-planning:
+- [ ] Symptoms clearly documented
+- [ ] Root cause confirmed with evidence
+- [ ] User confirmed root cause
+- [ ] Bug work item created
+- [ ] Fix chore created with breadcrumbs
+- [ ] Regression test written and merged
+- [ ] Fix chore started with `work start`
+- [ ] bug-mode skill invoked

package/skills-templates/speed-mode/SKILL.md

@@ -651,9 +651,36 @@ If the query returns no remaining chores, proceed to Step 7.
 
 This is the transition from speed mode to stable mode. Follow these phases in order.
 
-#### Step 7A: Verify Integration Scenario Passes
+#### Step 7A: Validate BDD Infrastructure and Verify Integration
 
-**CRITICAL: Before transitioning, verify the feature is actually integrated into the app.**
+**CRITICAL: Before transitioning, validate BDD infrastructure and verify integration.**
+
+**1. Run dry-run validation to catch step definition conflicts:**
+
+```bash
+node -e "
+const { validateBddInfrastructure } = require('./lib/skills/feature-planning/dry-run-validator');
+validateBddInfrastructure('<scenario-file-path>').then(result => {
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.success ? 0 : 1);
+});
+"
+```
+
+**If validation FAILS with `duplicate_step` error:**
+- Two step definition files define the same step pattern
+- The error shows which files conflict
+- **STOP** - create a chore to fix the step definition conflict before proceeding
+- This is a test infrastructure bug, not a feature implementation issue
+
+**If validation FAILS with other errors:**
+- Check for `undefined_step` (missing step definitions)
+- Check for `syntax_error` (malformed Gherkin)
+- Fix the specific issue before proceeding
+
+**If validation PASSES:** Continue to run integration scenario.
+
+**2. Run the integration scenario:**
 
 ```bash
 # Run ONLY the integration scenario (first scenario in the feature file)

package/skills-templates/stable-mode/SKILL.md

@@ -428,13 +428,36 @@ If user adjusts: revise proposal and confirm again before proceeding.
 
 **CRITICAL:** After user confirms (or skips confirmation), execute autonomously - no permission needed for code changes.
 
-Before writing any implementation code, run tests to establish the RED state:
+Before writing any implementation code, validate BDD infrastructure and run tests to establish the RED state:
 
 ```bash
 # Get current work and parent feature's scenario file
 sqlite3 .jettypod/work.db "SELECT wi.id, wi.parent_id, parent.scenario_file FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id WHERE wi.status = 'in_progress'"
+```
+
+**1. Run dry-run validation to catch step definition conflicts:**
+
+```bash
+node -e "
+const { validateBddInfrastructure } = require('./lib/skills/feature-planning/dry-run-validator');
+validateBddInfrastructure('<scenario-file-path>').then(result => {
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.success ? 0 : 1);
+});
+"
+```
+
+**If validation FAILS with `duplicate_step` error:**
+- Two step definition files define the same step pattern
+- The error shows which files conflict
+- **STOP** - fix the step definition conflict before proceeding
+- Common cause: stable mode step definitions duplicating existing steps
+
+**If validation PASSES:** Continue to establish RED baseline.
 
-# Run BDD tests to establish RED baseline
+**2. Run BDD tests to establish RED baseline:**
+
+```bash
 npx cucumber-js <scenario-file-path> --format progress
 ```