@kennethsolomon/shipkit 1.0.0

package/skills/sk:debug/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: sk:debug
+description: "Structured bug investigation: reproduce, isolate, hypothesize, verify, fix. Logs findings systematically."
+---
+
+# Structured Debugging Workflow
+
+## Overview
+
+Systematic bug investigation that follows a disciplined process: reproduce, isolate, hypothesize, verify, fix. Every finding is logged to prevent repeated work and build project knowledge.
+
+<HARD-GATE>
+Do NOT jump to fixing code before you understand the bug. No code changes until a hypothesis is CONFIRMED through systematic investigation. Random fixes waste time and mask root causes.
+</HARD-GATE>
+
+## Anti-Patterns — Do NOT Do These
+
+- **Changing code before understanding** — Read and analyze first
+- **Trying random fixes** — "Maybe if I change this..." is not debugging
+- **Ignoring stack traces** — They tell you exactly where to look
+- **Fixing symptoms, not causes** — A try/catch around a crash is not a fix
+- **Skipping reproduction** — If you can't reproduce it, you can't verify the fix
+- **Debugging in production** — Reproduce locally first
+
+## Allowed Tools
+
+Bash, Read, Write, Edit, Glob, Grep, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_network_requests, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_snapshot
+
+## Steps
+
+You MUST complete these steps in order:
+
+### 1. Gather Information
+
+Parse what the user tells you:
+
+- **Error message**: Extract the exact error text
+- **Stack trace**: Identify the file, line, and call chain
+- **Expected vs actual behavior**: What should happen vs what does happen
+- **Trigger conditions**: When does it happen? Always, sometimes, under specific conditions?
+- **Recent changes**: Did it work before? What changed?
+
+If the user provides insufficient information, ask specific questions — don't guess.
+
+### 2. Read Project Context
+
+Check for existing knowledge:
+
+```
+CLAUDE.md                  — Project conventions, known issues
+tasks/findings.md          — Previous debugging sessions, known bugs
+tasks/lessons.md           — Patterns that caused issues before
+tasks/progress.md          — Recent work log and error log
+```
+
+**If `tasks/lessons.md` exists, read it in full.** For each active lesson, apply its prevention rule to your investigation — treat lessons as standing constraints, not just history. For example: if a lesson says "always check env vars before checking application code", do that first.
+
+**If `tasks/progress.md` exists**, scan the Error Log for failures near the bug's reported time — they often share a root cause with the current bug.
+
+Check if this bug (or something similar) has been investigated before.
+
+### 3. Check Recent Changes
+
+```bash
+git log --oneline -10
+git diff HEAD~3 --stat
+```
+
+Correlate the bug timeline with recent changes. Did the bug start after a specific commit?
+
+### 4. Reproduce the Bug
+
+**Determine the bug surface first:**
+
+#### A. Server / CLI / Non-Browser Bug
+
+Run the specific command, test, or action that triggers the bug. Capture the full output.
+
+```bash
+# Run the failing test/command
+[specific command that triggers the bug]
+```
+
+#### B. Browser / UI Bug
+
+If the bug is visual, involves JavaScript errors, or requires a browser to reproduce, use the Playwright MCP plugin instead of Bash:
+
+1. **Navigate to the page**:
+   ```
+   mcp__plugin_playwright_playwright__browser_navigate({ url: "http://localhost:[PORT]/[path]" })
+   ```
+
+2. **Capture JS errors** (most useful for runtime exceptions):
+   ```
+   mcp__plugin_playwright_playwright__browser_console_messages({ level: "error" })
+   ```
+
+3. **Inspect failed network requests** (useful for API/fetch failures):
+   ```
+   mcp__plugin_playwright_playwright__browser_network_requests({ includeStatic: false })
+   ```
+
+4. **Screenshot the visual state** to document what the bug looks like:
+   ```
+   mcp__plugin_playwright_playwright__browser_take_screenshot({ type: "png" })
+   ```
+
+5. **Capture accessibility snapshot** for structural/DOM-level inspection:
+   ```
+   mcp__plugin_playwright_playwright__browser_snapshot()
+   ```
+
+Use the console errors and network failures as primary evidence in Step 6 (Hypotheses).
+
+---
+
+If you cannot reproduce (either path):
+- Check environment differences
+- Check for race conditions or timing issues
+- Ask the user for exact reproduction steps
+- Do NOT proceed to fixing without reproduction
+
+### 5. Isolate the Problem
+
+Read the relevant code, tracing the execution path:
+
+1. Start at the error location (from stack trace)
+2. Trace backward through the call chain
+3. Identify the inputs and state at each step
+4. Find where actual behavior diverges from expected
+
+Use targeted searches:
+
+```bash
+# Find related code
+grep -r "functionName" src/
+grep -r "ERROR_CODE" .
+```
+
+### 6. Form Hypotheses
+
+Generate 2-3 ranked hypotheses based on your investigation:
+
+```markdown
+## Hypotheses
+
+### H1: [Most likely] Description
+- Evidence: what supports this
+- Test: how to confirm or reject
+
+### H2: [Alternative] Description
+- Evidence: what supports this
+- Test: how to confirm or reject
+
+### H3: [Less likely] Description
+- Evidence: what supports this
+- Test: how to confirm or reject
+```
+
+Log these to `tasks/findings.md` under a dated heading.
+
+### 7. Test Hypotheses Systematically
+
+For each hypothesis, starting with the most likely:
+
+1. Design a specific diagnostic step (not a fix)
+2. Execute it and observe the result
+3. Update the hypothesis status: **CONFIRMED** / **REJECTED** / **PARTIAL**
+
+Diagnostic steps might include:
+- Adding a temporary log statement to check a value
+- Running with different inputs
+- Checking database state
+- Inspecting environment variables
+- Running a minimal reproduction
+
+**Do NOT change production code during this phase.** Diagnostic changes only.
+
+### 8. Update Findings
+
+Update `tasks/findings.md` with results:
+
+```markdown
+### [Date] Bug: [brief description]
+
+**Symptom:** [what the user reported]
+**Root cause:** [H1/H2/H3 — which was confirmed]
+**Evidence:** [what confirmed it]
+**Status:** CONFIRMED → fix proposed
+```
+
+### 9. Propose Minimal Fix
+
+Once a hypothesis is confirmed, propose the smallest possible fix:
+
+- Change as few lines as possible
+- Don't refactor surrounding code
+- Don't add "while I'm here" improvements
+- Explain why this fix addresses the root cause
+
+Present the fix and **wait for user approval** before applying.
+
+### 10. Verify Fix + Regression Check
+
+After the fix is applied:
+
+1. Re-run the original reproduction steps — bug should be gone
+2. Run the full test suite — no new failures
+3. If there was a related test, confirm it passes
+4. If there was no test, suggest writing one (reference `/sk:write-tests`)
+
+```bash
+# Verify the specific fix
+[reproduction command]
+
+# Regression check
+[test suite command]
+```
+
+### 11. Document
+
+**Root cause in `tasks/findings.md`:**
+Update the entry from step 8 with the final resolution.
+
+**Lesson in `tasks/lessons.md`** (only if the pattern could recur):
+
+```markdown
+### [Date] Lesson: [brief title]
+**Bug:** [what happened]
+**Root cause:** [why it happened]
+**Prevention:** [how to avoid it in the future]
+```
+
+Skip the lesson entry if it was a simple typo or one-off mistake.
+
+---
+
+## Model Routing
+
+Read `.shipkit/sk:config.json` from the project root if it exists.
+
+- If `model_overrides["sk:debug"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | opus (inherit) |
+| `balanced` | sonnet |
+| `budget` | sonnet |
+
+> `opus` = inherit (uses the current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

package/skills/sk:debug/debug_conductor.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""Main conductor for /debug skill: 11-step structured debugging."""
+
+import sys
+from pathlib import Path
+from enum import Enum
+from datetime import datetime
+
+# Add lib to path
+sys.path.insert(0, str(Path(__file__).parent / "lib"))
+
+from context_reader import ContextReader
+from bug_gatherer import BugGatherer
+from step_runner import StepRunner
+from findings_writer import FindingsWriter
+from lessons_writer import LessonsWriter
+
+
+class DebugStep(Enum):
+    GATHER_INFO = 1
+    READ_CONTEXT = 2
+    CHECK_CHANGES = 3
+    REPRODUCE = 4
+    ISOLATE = 5
+    FORM_HYPOTHESES = 6
+    TEST_HYPOTHESES = 7
+    UPDATE_FINDINGS = 8
+    PROPOSE_FIX = 9
+    VERIFY_FIX = 10
+    DOCUMENT = 11
+
+
+class DebugConductor:
+    """Manages the 11-step debugging workflow with gating."""
+
+    def __init__(self):
+        self.context_reader = ContextReader()
+        self.bug_gatherer = BugGatherer()
+        self.step_runner = StepRunner()
+        self.findings_writer = FindingsWriter()
+        self.lessons_writer = LessonsWriter()
+        self.current_step = DebugStep.GATHER_INFO
+        self.state = {}  # Accumulate findings across steps
+
+    def run(self):
+        """Execute debugging workflow from step 1 to 11."""
+        print("\n" + "="*70)
+        print("🐛 DEBUG: Structured Bug Investigation")
+        print("="*70)
+
+        # Step 1: Gather user input
+        print("\n[STEP 1] Gathering Information")
+        bug_info = self.bug_gatherer.gather_from_user()
+        self.state['bug_info'] = bug_info
+
+        # Step 2: Read context files
+        print("\n[STEP 2] Reading Project Context")
+        context = self.context_reader.read_all()
+        self.state['context'] = context
+        self.state['active_lessons'] = context['lessons']
+
+        # Apply lessons as constraints
+        self._apply_lessons_as_constraints(context['lessons'])
+
+        # Steps 3-11: Run sequentially with gating
+        for step_num in range(3, 12):
+            step = DebugStep(step_num)
+            self.current_step = step
+
+            print(f"\n{'='*70}")
+            print(f"[STEP {step_num}] {step.name.replace('_', ' ').title()}")
+            print(f"{'='*70}\n")
+
+            # Check if we can proceed
+            if not self._can_proceed(step):
+                print(f"\n⛔ BLOCKED: {self._gate_reason(step)}")
+                print("\nRun /debug again to continue from this step.")
+                self._save_progress()
+                return
+
+            # Run step and update state
+            result = self.step_runner.execute(step, self.state)
+            self.state.update(result)
+
+            # Step 8: Write findings
+            if step_num == 8:
+                self.findings_writer.write_findings(self.state)
+
+            # Step 11: Write lesson (conditional)
+            if step_num == 11:
+                self.lessons_writer.write_lesson(self.state)
+
+            if step_num < 11:
+                proceed = input(f"\n✅ Step {step_num} complete. Continue to step {step_num + 1}? (y/n): ").strip().lower()
+                if proceed not in ['y', 'yes', '']:
+                    print(f"Pausing after step {step_num}. Run /debug again to continue.")
+                    self._save_progress()
+                    return
+
+        print("\n" + "="*70)
+        print("🎉 DEBUGGING WORKFLOW COMPLETE")
+        print("="*70)
+        print(f"\n✅ Findings written to: tasks/findings.md")
+        if self.state.get('lesson_created'):
+            print(f"✅ New lesson written to: tasks/lessons.md")
+        print("\n📝 Next: Run /commit to create a fix commit")
+        print("   Or:  Run /write-tests to add test coverage")
+
+    def _apply_lessons_as_constraints(self, lessons: list):
+        """Apply all active lessons as standing constraints during investigation."""
+        if not lessons:
+            return
+
+        print("\n📚 APPLYING STANDING LESSONS:")
+        for lesson in lessons:
+            print(f"   - [{lesson.get('date', '?')}] {lesson.get('title', 'Unknown')}")
+            print(f"     Prevention: {lesson.get('prevention', 'N/A')}")
+        print()
+
+    def _can_proceed(self, step: DebugStep) -> bool:
+        """Check if we can proceed to/through this step."""
+        # Step 4: Must eventually reproduce to proceed
+        if step == DebugStep.REPRODUCE:
+            return True  # Can always try to reproduce
+
+        # Step 5+: Must have reproduced
+        if step.value > 4:
+            return self.state.get('reproduced', False)
+
+        # Step 6: Can form hypotheses
+        if step == DebugStep.FORM_HYPOTHESES:
+            return True
+
+        # Step 7+: Must have hypotheses
+        if step.value > 6:
+            return len(self.state.get('hypotheses', [])) > 0
+
+        # Step 8+: Must have tested at least one
+        if step.value > 7:
+            hypotheses = self.state.get('hypotheses', [])
+            return any(h.get('status') in ['CONFIRMED', 'REJECTED', 'PARTIAL']
+                      for h in hypotheses)
+
+        # Step 9+: Must have confirmed hypothesis
+        if step.value > 8:
+            hypotheses = self.state.get('hypotheses', [])
+            return any(h.get('status') == 'CONFIRMED' for h in hypotheses)
+
+        return True
+
+    def _gate_reason(self, step: DebugStep) -> str:
+        """Explain why we can't proceed."""
+        if step.value > 4 and not self.state.get('reproduced'):
+            return "Cannot proceed without reproducing the bug first."
+        if step.value > 7 and not self.state.get('hypotheses'):
+            return "No hypotheses formed yet."
+        if step.value > 8 and not any(
+            h.get('status') == 'CONFIRMED'
+            for h in self.state.get('hypotheses', [])
+        ):
+            return "No confirmed hypothesis yet—cannot propose fix."
+        return "Precondition not met for this step."
+
+    def _save_progress(self):
+        """Save current state for resumption (optional)."""
+        # Could implement checkpoint system here
+        pass
+
+
+def main():
+    """Entry point for /debug skill."""
+    conductor = DebugConductor()
+    conductor.run()
+
+
+if __name__ == '__main__':
+    main()

package/skills/sk:debug/lib/__init__.py

@@ -0,0 +1 @@
+"""Debug skill library modules."""

package/skills/sk:debug/lib/bug_gatherer.py

@@ -0,0 +1,55 @@
+"""Gather bug information from user input."""
+
+from typing import Dict
+
+
+class BugGatherer:
+    """Interactive bug information gathering."""
+
+    def gather_from_user(self) -> Dict:
+        """Prompt user for bug details."""
+        print("\nLet's gather information about the bug.\n")
+
+        bug_info = {
+            'description': self._prompt("Brief description of what's wrong"),
+            'error_message': self._prompt("Exact error message (if any)", optional=True),
+            'stack_trace': self._prompt_multiline("Stack trace or logs (if any)", optional=True),
+            'expected_behavior': self._prompt("What SHOULD happen"),
+            'actual_behavior': self._prompt("What ACTUALLY happens"),
+            'trigger_conditions': self._prompt("When/how does it happen? (Always, sometimes, specific conditions?)"),
+            'recent_changes': self._prompt("Did this work before? What changed?", optional=True),
+            'environment': self._prompt("Environment (local, staging, prod)?"),
+        }
+
+        return bug_info
+
+    def _prompt(self, question: str, optional: bool = False) -> str:
+        """Prompt user for input."""
+        marker = " (optional)" if optional else " (required)"
+        print(f"❓ {question}{marker}:")
+        answer = input("> ").strip()
+
+        if not answer and not optional:
+            print("   ⚠️  This is required. Please try again.")
+            return self._prompt(question, optional)
+
+        return answer
+
+    def _prompt_multiline(self, question: str, optional: bool = False) -> str:
+        """Prompt for multiline input (ends with empty line)."""
+        marker = " (optional, blank line to end)" if optional else " (blank line to end)"
+        print(f"❓ {question}{marker}:")
+
+        lines = []
+        while True:
+            line = input("> ")
+            if not line:
+                break
+            lines.append(line)
+
+        result = '\n'.join(lines)
+        if not result and not optional:
+            print("   ⚠️  This is required. Please try again.")
+            return self._prompt_multiline(question, optional)
+
+        return result

package/skills/sk:debug/lib/context_reader.py

@@ -0,0 +1,139 @@
+"""Read and parse project context files (CLAUDE.md, lessons, findings, progress)."""
+
+from pathlib import Path
+from typing import Dict, List
+import re
+
+
+class ContextReader:
+    """Safe reader for CLAUDE.md, lessons.md, findings.md, progress.md."""
+
+    def __init__(self, project_root: Path = None):
+        self.root = project_root or Path.cwd()
+
+    def read_all(self) -> Dict:
+        """Read all context files and return structured data."""
+        return {
+            'claude_md': self._read_claude_md(),
+            'lessons': self._read_lessons(),
+            'findings': self._read_findings(),
+            'progress': self._read_progress(),
+        }
+
+    def _read_claude_md(self) -> Dict:
+        """Parse CLAUDE.md for tech stack and conventions."""
+        claude_path = self.root / 'CLAUDE.md'
+        if not claude_path.exists():
+            return {'exists': False}
+
+        content = claude_path.read_text()
+        return {
+            'exists': True,
+            'has_content': len(content) > 100,
+        }
+
+    def _read_lessons(self) -> List[Dict]:
+        """Parse tasks/lessons.md and extract active lessons."""
+        lessons_path = self.root / 'tasks' / 'lessons.md'
+        if not lessons_path.exists():
+            return []
+
+        content = lessons_path.read_text()
+        lessons = []
+
+        # Parse markdown format:
+        # ### [YYYY-MM-DD] Brief title
+        # **Bug:** ...
+        # **Root cause:** ...
+        # **Prevention:** ...
+
+        # Split by ### headers
+        sections = re.split(r'### ', content)
+
+        for section in sections[1:]:  # Skip header
+            lines = section.strip().split('\n')
+            if not lines:
+                continue
+
+            # First line: [YYYY-MM-DD] Title
+            first = lines[0]
+            match = re.match(r'\[(\d{4}-\d{2}-\d{2})\]\s*(.*)', first)
+            if not match:
+                continue
+
+            date, title = match.groups()
+
+            # Extract fields
+            full_text = '\n'.join(lines)
+            bug = self._extract_field(full_text, 'Bug')
+            root_cause = self._extract_field(full_text, 'Root cause')
+            prevention = self._extract_field(full_text, 'Prevention')
+
+            lesson = {
+                'date': date,
+                'title': title,
+                'bug': bug,
+                'root_cause': root_cause,
+                'prevention': prevention,
+            }
+            lessons.append(lesson)
+
+        return lessons
+
+    def _read_findings(self) -> List[Dict]:
+        """Parse tasks/findings.md and extract past investigations."""
+        findings_path = self.root / 'tasks' / 'findings.md'
+        if not findings_path.exists():
+            return []
+
+        content = findings_path.read_text()
+        findings = []
+
+        # Parse markdown format:
+        # ## YYYY-MM-DD HH:MM — Bug: Description
+        # **Symptom:** ...
+        # **Root cause:** ...
+
+        sections = re.split(r'## (\d{4}-\d{2}-\d{2})', content)
+
+        for i in range(1, len(sections), 2):
+            date = sections[i]
+            text = sections[i + 1] if i + 1 < len(sections) else ''
+
+            # Extract description from "— Bug: ..."
+            desc_match = re.search(r'—\s*Bug:\s*(.+)', text)
+            description = desc_match.group(1).strip() if desc_match else ''
+
+            symptom = self._extract_field(text, 'Symptom')
+            root_cause = self._extract_field(text, 'Root cause')
+            status = self._extract_field(text, 'Status')
+
+            findings.append({
+                'date': date,
+                'description': description,
+                'symptom': symptom,
+                'root_cause': root_cause,
+                'status': status,
+            })
+
+        return findings
+
+    def _read_progress(self) -> Dict:
+        """Parse tasks/progress.md for recent errors."""
+        progress_path = self.root / 'tasks' / 'progress.md'
+        if not progress_path.exists():
+            return {'exists': False}
+
+        content = progress_path.read_text()
+        return {
+            'exists': True,
+            'has_error_log': '## Error Log' in content or '### Error' in content,
+        }
+
+    def _extract_field(self, text: str, field_name: str) -> str:
+        """Extract field from markdown (e.g., **Bug:** content)."""
+        pattern = rf'\*\*{field_name}:\*\*\s*(.+?)(?=\n\*\*|\n###|$)'
+        match = re.search(pattern, text, re.DOTALL)
+        if match:
+            return match.group(1).strip()
+        return ''