@kennethsolomon/shipkit 1.0.0

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

@@ -0,0 +1,76 @@
+"""Safe writer for tasks/findings.md - appends findings without overwriting."""
+
+from pathlib import Path
+from datetime import datetime
+from typing import Dict
+
+
+class FindingsWriter:
+    """Append findings to tasks/findings.md without overwriting."""
+
+    def __init__(self, root: Path = None):
+        self.root = root or Path.cwd()
+        self.findings_path = self.root / 'tasks' / 'findings.md'
+
+    def write_findings(self, state: Dict) -> bool:
+        """Write findings entry from debug state."""
+        bug_info = state.get('bug_info', {})
+        hypotheses = state.get('hypotheses', [])
+        root_cause = state.get('root_cause_confirmed', '')
+
+        now = datetime.now().strftime("%Y-%m-%d %H:%M")
+        bug_summary = bug_info.get('description', 'Unknown')
+
+        # Build the entry
+        entry = f"\n## {now} — Bug: {bug_summary}\n\n"
+        entry += f"**Symptom:** {bug_info.get('actual_behavior', 'Unknown')}\n\n"
+        entry += f"**Root cause:** {root_cause}\n\n"
+
+        # Add hypotheses tested
+        if hypotheses:
+            entry += "**Hypotheses tested:**\n"
+            for h in hypotheses:
+                status = h.get('status', 'UNKNOWN')
+                entry += f"- H{h['rank']}: {h['description']} → **{status}**\n"
+                if h.get('test_results'):
+                    entry += f"  Result: {h['test_results']}\n"
+            entry += "\n"
+
+        entry += f"**Status:** Investigation complete\n"
+
+        # Write to file
+        try:
+            self._ensure_file_exists()
+            self._append_entry(entry)
+            print(f"\n✅ Findings written to {self.findings_path}")
+            return True
+        except Exception as e:
+            print(f"\n❌ Error writing findings: {e}")
+            return False
+
+    def _ensure_file_exists(self):
+        """Create tasks/findings.md if missing with template."""
+        if not self.findings_path.exists():
+            self.findings_path.parent.mkdir(parents=True, exist_ok=True)
+            template = """# Bug Findings
+
+Investigations of bugs found during development.
+
+## Entry Format
+
+Each entry includes:
+- **Date and summary** — When and what
+- **Symptom** — What the user reported
+- **Root cause** — What was actually wrong
+- **Hypotheses tested** — What we checked
+- **Status** — Investigation stage
+
+---
+
+"""
+            self.findings_path.write_text(template)
+
+    def _append_entry(self, entry: str):
+        """Append entry to findings.md without overwriting."""
+        current = self.findings_path.read_text()
+        self.findings_path.write_text(current + entry + "\n")

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

@@ -0,0 +1,165 @@
+"""Safe writer for tasks/lessons.md - appends lessons only when pattern detected."""
+
+from pathlib import Path
+from datetime import datetime
+from typing import Dict
+
+
+class LessonsWriter:
+    """Append lessons to tasks/lessons.md only when recurrence risk detected."""
+
+    def __init__(self, root: Path = None):
+        self.root = root or Path.cwd()
+        self.lessons_path = self.root / 'tasks' / 'lessons.md'
+
+    def should_create_lesson(self, state: Dict) -> bool:
+        """Determine if this bug warrants a lesson (recurrence risk)."""
+        root_cause = state.get('root_cause_confirmed', '')
+
+        if not root_cause:
+            return False
+
+        # Skip lessons for one-off issues:
+        skip_patterns = [
+            'typo', 'spelling', 'copy-paste',
+            'environment variable not set',
+            'hardware failure', 'network timeout',
+            'race condition (timing)',
+            'one-off',
+        ]
+
+        for pattern in skip_patterns:
+            if pattern.lower() in root_cause.lower():
+                return False
+
+        # Create lesson for systematic issues that could recur:
+        # - Logic errors
+        # - Missing validation
+        # - Architectural oversights
+        # - Performance issues
+        # - Missing error handling
+
+        return True
+
+    def write_lesson(self, state: Dict) -> bool:
+        """Write lesson entry from debug state."""
+        if not self.should_create_lesson(state):
+            print("\n⏭️  Skipping lesson (one-off issue, pattern unlikely to recur)")
+            return False
+
+        bug_info = state.get('bug_info', {})
+        root_cause = state.get('root_cause_confirmed', '')
+
+        date = datetime.now().strftime("%Y-%m-%d")
+        bug_symptom = bug_info.get('description', 'Unknown')
+        prevention = self._derive_prevention(state)
+
+        # Build the lesson entry
+        entry = f"\n### [{date}] {self._generate_title(root_cause)}\n\n"
+        entry += f"**Bug:** {bug_symptom}\n\n"
+        entry += f"**Root cause:** {root_cause}\n\n"
+        entry += f"**Prevention:** {prevention}\n"
+
+        # Write to file
+        try:
+            self._ensure_file_exists()
+            self._append_lesson(entry)
+            print(f"\n✅ New lesson added to {self.lessons_path}")
+            return True
+        except Exception as e:
+            print(f"\n❌ Error writing lesson: {e}")
+            return False
+
+    def _ensure_file_exists(self):
+        """Create tasks/lessons.md if missing with template."""
+        if not self.lessons_path.exists():
+            self.lessons_path.parent.mkdir(parents=True, exist_ok=True)
+            template = """# Lessons Learned
+
+Patterns that caused bugs and prevention rules to avoid them in the future.
+
+## Entry Format
+
+Each lesson includes:
+- **[Date] Title** — When and what we learned
+- **Bug** — What went wrong
+- **Root cause** — Why it happened
+- **Prevention** — How to avoid it next time
+
+Lessons are applied as standing constraints by:
+- `/brainstorm` — Applies to requirement exploration
+- `/write-plan` — Applies to plan creation
+- `/execute-plan` — Applies as implementation constraints
+- `/write-tests` — Applies to test patterns
+- `/review` — Applies to code review checks
+- `/finish-feature` — Applies as merge gate checks
+
+---
+
+## Active Lessons
+
+"""
+            self.lessons_path.write_text(template)
+
+    def _append_lesson(self, entry: str):
+        """Append lesson to lessons.md in the Active Lessons section."""
+        content = self.lessons_path.read_text()
+
+        # Find "## Active Lessons" marker
+        marker = "## Active Lessons\n"
+        if marker in content:
+            # Insert after the marker
+            parts = content.split(marker)
+            self.lessons_path.write_text(
+                parts[0] + marker + "\n" + entry + "\n" + parts[1]
+            )
+        else:
+            # Fallback: append at end
+            self.lessons_path.write_text(content + entry + "\n")
+
+    def _derive_prevention(self, state: Dict) -> str:
+        """Suggest prevention rule from root cause."""
+        root_cause = state.get('root_cause_confirmed', '').lower()
+
+        # Simple heuristics to suggest prevention
+        if 'validation' in root_cause:
+            return "Always validate input at system boundaries (user input, API calls, file uploads) before processing. Check type, range, format, and size."
+
+        elif 'race condition' in root_cause:
+            return "Use locks or atomic operations for concurrent access to shared state. Add tests for concurrent scenarios."
+
+        elif 'type' in root_cause or 'coercion' in root_cause:
+            return "Enable and enforce strict type checking. Avoid implicit type coercion. Use type hints/annotations."
+
+        elif 'error handling' in root_cause or 'exception' in root_cause:
+            return "Always handle exceptions explicitly. Don't silently catch and ignore errors. Log unexpected conditions."
+
+        elif 'null' in root_cause or 'undefined' in root_cause:
+            return "Check for null/undefined values before accessing properties. Use optional chaining or default values."
+
+        elif 'memory' in root_cause or 'resource' in root_cause:
+            return "Always clean up resources (close files, connections, listeners). Use try-finally or context managers."
+
+        elif 'performance' in root_cause or 'slow' in root_cause:
+            return "Profile before optimizing. Add monitoring and alerts for performance regressions. Include performance tests."
+
+        elif 'security' in root_cause or 'injection' in root_cause:
+            return "Apply input validation and output encoding. Use parameterized queries. Never trust user input. Review OWASP top 10."
+
+        else:
+            # Generic prevention
+            return f"Pattern identified: {root_cause[:60]}... Review root cause and implement safeguard in code review checklist."
+
+    def _generate_title(self, root_cause: str) -> str:
+        """Generate lesson title from root cause."""
+        # Try to create a concise title
+        title = root_cause
+
+        # Limit length
+        if len(title) > 60:
+            title = title[:57] + "..."
+
+        # Capitalize first letter
+        title = title[0].upper() + title[1:] if title else "Bug Lesson"
+
+        return title

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

@@ -0,0 +1,326 @@
+"""Execute individual debug steps (3-11)."""
+
+import subprocess
+from typing import Dict
+from pathlib import Path
+import sys
+
+
+class StepRunner:
+    """Execute each debugging step."""
+
+    def execute(self, step, state: Dict) -> Dict:
+        """Execute a specific step and return results."""
+        step_num = step.value
+
+        if step_num == 3:
+            return self._step_3_check_changes()
+        elif step_num == 4:
+            return self._step_4_reproduce(state)
+        elif step_num == 5:
+            return self._step_5_isolate(state)
+        elif step_num == 6:
+            return self._step_6_form_hypotheses(state)
+        elif step_num == 7:
+            return self._step_7_test_hypotheses(state)
+        elif step_num == 8:
+            return self._step_8_update_findings(state)
+        elif step_num == 9:
+            return self._step_9_propose_fix(state)
+        elif step_num == 10:
+            return self._step_10_verify_fix(state)
+        elif step_num == 11:
+            return self._step_11_document(state)
+
+        return {}
+
+    def _step_3_check_changes(self) -> Dict:
+        """Check recent git changes."""
+        print("Checking recent git commits and diffs...\n")
+
+        try:
+            # Recent commits
+            print("📋 Recent commits:")
+            result = subprocess.run(
+                "git log --oneline -10",
+                shell=True,
+                capture_output=True,
+                text=True
+            )
+            print(result.stdout)
+
+            # Recent diffs
+            print("\n📋 Recent file changes:")
+            result = subprocess.run(
+                "git diff HEAD~3 --stat",
+                shell=True,
+                capture_output=True,
+                text=True
+            )
+            print(result.stdout)
+
+            return {'changes_reviewed': True}
+
+        except Exception as e:
+            print(f"⚠️  Could not check git history: {e}")
+            return {'changes_reviewed': False}
+
+    def _step_4_reproduce(self, state: Dict) -> Dict:
+        """Reproduce the bug (CLI or browser)."""
+        bug_info = state['bug_info']
+
+        print("Now let's reproduce the bug to confirm it exists.\n")
+
+        # Detect if likely browser bug
+        is_browser_bug = self._detect_browser_bug(bug_info)
+
+        if is_browser_bug:
+            return self._reproduce_browser_bug(state)
+        else:
+            return self._reproduce_cli_bug(state)
+
+    def _detect_browser_bug(self, bug_info: Dict) -> bool:
+        """Heuristic: is this a browser/UI bug?"""
+        keywords = [
+            'visual', 'browser', 'javascript', 'console', 'render',
+            'DOM', 'click', 'button', 'form', 'UI', 'page', 'screen'
+        ]
+        text = (
+            bug_info.get('description', '') + ' ' +
+            bug_info.get('error_message', '')
+        ).lower()
+        return any(kw in text for kw in keywords)
+
+    def _reproduce_cli_bug(self, state: Dict) -> Dict:
+        """Reproduce CLI/server bug via bash command."""
+        print("📝 Provide the bash command that triggers the bug:")
+        print("   (Leave blank if you'd rather describe manually)\n")
+
+        command = input("> ").strip()
+
+        if not command:
+            print("\n⚠️  Cannot reproduce without a command.")
+            print("   Please provide the exact command/steps to trigger the bug.")
+            return {'reproduced': False}
+
+        print(f"\n🔧 Running: {command}\n")
+
+        try:
+            result = subprocess.run(
+                command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=30
+            )
+
+            output = result.stdout + result.stderr
+            print(output)
+
+            print("\n✅ Bug reproduced successfully!")
+
+            return {
+                'reproduced': True,
+                'bug_type': 'cli',
+                'reproduction_command': command,
+                'reproduction_output': output[:500],  # First 500 chars
+                'evidence_collected': [f"Reproduced with: {command}"]
+            }
+
+        except subprocess.TimeoutExpired:
+            print("\n⚠️  Command timed out (30s)")
+            return {'reproduced': False}
+        except Exception as e:
+            print(f"\n❌ Error: {e}")
+            return {'reproduced': False}
+
+    def _reproduce_browser_bug(self, state: Dict) -> Dict:
+        """Reproduce browser/UI bug using Playwright (if available)."""
+        print("🌐 Browser bug detected. Provide URL where bug occurs:")
+        print("   (e.g., http://localhost:3000/page)\n")
+
+        url = input("> ").strip()
+
+        if not url:
+            print("\n⚠️  Cannot reproduce without URL.")
+            return {'reproduced': False}
+
+        print(f"\n🔧 Navigating to {url}...\n")
+
+        # TODO: Integrate Playwright MCP if available
+        # For now, mark as reproduced with manual confirmation
+
+        confirmed = input("Is the bug visible? (y/n): ").strip().lower()
+
+        if confirmed in ['y', 'yes']:
+            return {
+                'reproduced': True,
+                'bug_type': 'browser',
+                'url': url,
+                'evidence_collected': [f"Reproduced at {url}"]
+            }
+
+        return {'reproduced': False}
+
+    def _step_5_isolate(self, state: Dict) -> Dict:
+        """Isolate the problem by analyzing code."""
+        print("Now let's isolate the problem.\n")
+
+        error = state['bug_info'].get('error_message', '')
+        stack_trace = state['bug_info'].get('stack_trace', '')
+
+        print("📊 Code path to investigate:")
+        if error:
+            print(f"   Error: {error}")
+        if stack_trace:
+            print(f"   Stack trace: {stack_trace}")
+
+        isolation_notes = input("\n> Describe what code you think is involved: ").strip()
+
+        return {
+            'isolated_problem': isolation_notes,
+            'evidence_collected': [f"Isolated problem: {isolation_notes}"]
+        }
+
+    def _step_6_form_hypotheses(self, state: Dict) -> Dict:
+        """Form 2-3 hypotheses about root cause."""
+        print("\nForm hypotheses about what's causing the bug.\n")
+        print("For each hypothesis, provide:")
+        print("  1. Your theory")
+        print("  2. Evidence that supports it")
+        print("  3. How you'd test it\n")
+
+        hypotheses = []
+        for rank in range(1, 4):
+            print(f"Hypothesis {rank}:")
+            description = input("  > Theory: ").strip()
+            if not description:
+                continue
+
+            evidence = input("  > Evidence supporting this: ").strip()
+            test_plan = input("  > How to test it: ").strip()
+
+            hypotheses.append({
+                'rank': rank,
+                'description': description,
+                'evidence': evidence,
+                'test_plan': test_plan,
+                'status': 'UNKNOWN',
+                'test_results': '',
+            })
+
+        return {'hypotheses': hypotheses}
+
+    def _step_7_test_hypotheses(self, state: Dict) -> Dict:
+        """Test each hypothesis systematically."""
+        hypotheses = state.get('hypotheses', [])
+
+        print(f"\nTesting {len(hypotheses)} hypothesis/hypotheses...\n")
+
+        for h in hypotheses:
+            print(f"Testing H{h['rank']}: {h['description']}")
+            print(f"  Plan: {h['test_plan']}\n")
+
+            result = input("  > Test result (CONFIRMED/REJECTED/PARTIAL): ").strip().upper()
+            details = input("  > Details: ").strip()
+
+            h['status'] = result if result in ['CONFIRMED', 'REJECTED', 'PARTIAL'] else 'UNKNOWN'
+            h['test_results'] = details
+
+            if h['status'] == 'CONFIRMED':
+                print(f"  ✅ H{h['rank']} CONFIRMED!\n")
+            elif h['status'] == 'REJECTED':
+                print(f"  ❌ H{h['rank']} rejected.\n")
+            else:
+                print(f"  ⚠️  H{h['rank']} inconclusive.\n")
+
+        return {'hypotheses': hypotheses}
+
+    def _step_8_update_findings(self, state: Dict) -> Dict:
+        """Update findings.md with investigation results."""
+        print("\n📝 Findings will be written to tasks/findings.md")
+        print("   (This happens automatically in the next step)")
+        return {}
+
+    def _step_9_propose_fix(self, state: Dict) -> Dict:
+        """Propose minimal fix."""
+        hypotheses = state.get('hypotheses', [])
+        confirmed = next((h for h in hypotheses if h['status'] == 'CONFIRMED'), None)
+
+        if not confirmed:
+            print("\n❌ No confirmed hypothesis—cannot propose fix.")
+            return {}
+
+        print(f"\nConfirmed root cause: {confirmed['description']}\n")
+        print("Describe the minimal fix:")
+        print("  - What file(s) to change")
+        print("  - What to change")
+        print("  - Why it fixes the problem\n")
+
+        fix_description = input("> Fix proposal: ").strip()
+
+        return {
+            'confirmed_hypothesis': confirmed['description'],
+            'proposed_fix': fix_description,
+            'root_cause_confirmed': confirmed['description']
+        }
+
+    def _step_10_verify_fix(self, state: Dict) -> Dict:
+        """Verify the fix works."""
+        print("\n✅ Apply the fix to your code, then return here.\n")
+        input("Press Enter when fix is applied: ")
+
+        print("\nVerifying fix works...\n")
+
+        command = input("Run your reproduction command again: ").strip()
+
+        if command:
+            try:
+                result = subprocess.run(
+                    command,
+                    shell=True,
+                    capture_output=True,
+                    text=True,
+                    timeout=30
+                )
+                output = result.stdout + result.stderr
+                print(output)
+
+                fixed = input("\nIs the bug fixed? (y/n): ").strip().lower()
+                if fixed in ['y', 'yes']:
+                    print("✅ Fix verified!")
+                    return {'fix_verified': True}
+
+            except Exception as e:
+                print(f"Error: {e}")
+
+        return {'fix_verified': False}
+
+    def _step_11_document(self, state: Dict) -> Dict:
+        """Document the findings and create lesson if needed."""
+        print("\n📚 Documentation will be written:")
+        print("   ✅ tasks/findings.md (bug details)")
+
+        # Determine if a lesson should be created
+        root_cause = state.get('root_cause_confirmed', '')
+
+        skip_patterns = [
+            'typo', 'spelling', 'copy-paste',
+            'environment variable',
+            'one-off', 'race condition'
+        ]
+
+        skip_lesson = any(p.lower() in root_cause.lower() for p in skip_patterns)
+
+        if not skip_lesson and root_cause:
+            print("   ✅ tasks/lessons.md (prevention rule)")
+            return {
+                'lesson_created': True,
+                'root_cause_confirmed': root_cause
+            }
+        else:
+            print("   ⏭️  Skipping lesson (one-off issue)")
+            return {
+                'lesson_created': False,
+                'root_cause_confirmed': root_cause
+            }