bobs-workshop 0.3.3 → 3.1.0

package/src/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: systematic-debugging
+description: 4-phase systematic debugging methodology with root cause analysis and evidence-based verification.
+metadata:
+  recommended_for: trace
+  category: debugging
+---
+
+# Systematic Debugging
+
+> Source: obra/superpowers
+
+## Overview
+This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.
+
+## 4-Phase Debugging Process
+
+### Phase 1: Reproduce
+Before fixing, reliably reproduce the issue.
+
+```markdown
+## Reproduction Steps
+1. [Exact step to reproduce]
+2. [Next step]
+3. [Expected vs actual result]
+
+## Reproduction Rate
+- [ ] Always (100%)
+- [ ] Often (50-90%)
+- [ ] Sometimes (10-50%)
+- [ ] Rare (<10%)
+```
+
+### Phase 2: Isolate
+Narrow down the source.
+
+```markdown
+## Isolation Questions
+- When did this start happening?
+- What changed recently?
+- Does it happen in all environments?
+- Can we reproduce with minimal code?
+- What's the smallest change that triggers it?
+```
+
+### Phase 3: Understand
+Find the root cause, not just symptoms.
+
+```markdown
+## Root Cause Analysis
+### The 5 Whys
+1. Why: [First observation]
+2. Why: [Deeper reason]
+3. Why: [Still deeper]
+4. Why: [Getting closer]
+5. Why: [Root cause]
+```
+
+### Phase 4: Fix & Verify
+Fix and verify it's truly fixed.
+
+```markdown
+## Fix Verification
+- [ ] Bug no longer reproduces
+- [ ] Related functionality still works
+- [ ] No new issues introduced
+- [ ] Test added to prevent regression
+```
+
+## Debugging Checklist
+
+```markdown
+## Before Starting
+- [ ] Can reproduce consistently
+- [ ] Have minimal reproduction case
+- [ ] Understand expected behavior
+
+## During Investigation
+- [ ] Check recent changes (git log)
+- [ ] Check logs for errors
+- [ ] Add logging if needed
+- [ ] Use debugger/breakpoints
+
+## After Fix
+- [ ] Root cause documented
+- [ ] Fix verified
+- [ ] Regression test added
+- [ ] Similar code checked
+```
+
+## Common Debugging Commands
+
+```bash
+# Recent changes
+git log --oneline -20
+git diff HEAD~5
+
+# Search for pattern
+grep -r "errorPattern" --include="*.ts"
+
+# Check logs
+pm2 logs app-name --err --lines 100
+```
+
+## Anti-Patterns
+
+❌ **Random changes** - "Maybe if I change this..."
+❌ **Ignoring evidence** - "That can't be the cause"
+❌ **Assuming** - "It must be X" without proof
+❌ **Not reproducing first** - Fixing blindly
+❌ **Stopping at symptoms** - Not finding root cause
+
+---
+
+## Bob's Workshop Integration
+
+This skill is used by **trace (debugger)** agent during the FIX phase.
+
+### MANUAL Integration
+
+Add debugging section to MANUAL:
+```markdown
+## 🔍 Debug Logs
+
+### Issue Summary
+- **Bug ID:** [BUG-001]
+- **Reported by:** [User/Agent]
+- **Severity:** [Critical/High/Medium/Low]
+
+### Phase 1: Reproduce
+- [ ] Reproduction steps documented
+- [ ] Reproduction rate identified
+- [ ] Expected vs actual behavior clear
+
+### Phase 2: Isolate
+- [ ] Timeline: When did this start?
+- [ ] Changes: What changed recently?
+- [ ] Environment: Does it happen everywhere?
+- [ ] Scope: Can we isolate to specific code?
+
+### Phase 3: Understand
+- [ ] Root cause analysis complete (5 Whys)
+- [ ] Root cause identified: [Description]
+- [ ] Related areas affected: [List]
+
+### Phase 4: Fix & Verify
+- [ ] Fix implemented
+- [ ] Bug no longer reproduces
+- [ ] Related functionality verified
+- [ ] No new issues introduced
+- [ ] Regression test added: [Test name]
+
+### Related Code
+- Files changed: [List]
+- Lines affected: [List]
+- Similar patterns to check: [List]
+```
+
+### Handoff Format
+
+After fixing, document the solution:
+```markdown
+## 🤝 Agent Handoffs
+
+🤝 trace: Root cause identified - [Brief description]
+🤝 trace → bob-rev: Fix verified, ready for re-review
+```
+
+### Evidence Requirements
+
+**Before marking fix complete, gather:**
+1. **Reproduction steps** - Can we reliably reproduce?
+2. **Isolation evidence** - What narrows down the cause?
+3. **Root cause proof** - Why is this the root cause?
+4. **Fix verification** - Bug gone, tests pass, nothing broken

package/src/skills/testing-patterns/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: testing-patterns
+description: Testing patterns and principles. Unit, integration, mocking strategies.
+metadata:
+  recommended_for: bob-eng
+  category: testing
+---
+
+# Testing Patterns
+
+> Principles for reliable test suites.
+
+---
+
+## 1. Testing Pyramid
+
+```
+        /\          E2E (Few)
+       /  \         Critical flows
+      /----\
+     /      \       Integration (Some)
+    /--------\      API, DB queries
+   /          \
+  /------------\    Unit (Many)
+                  Functions, classes
+```
+
+---
+
+## 2. AAA Pattern
+
+| Step | Purpose |
+|------|---------|
+| **Arrange** | Set up test data |
+| **Act** | Execute code under test |
+| **Assert** | Verify outcome |
+
+---
+
+## 3. Test Type Selection
+
+### When to Use Each
+
+| Type | Best For | Speed |
+|------|----------|-------|
+| **Unit** | Pure functions, logic | Fast (<50ms) |
+| **Integration** | API, DB, services | Medium |
+| **E2E** | Critical user flows | Slow |
+
+---
+
+## 4. Unit Test Principles
+
+### Good Unit Tests
+
+| Principle | Meaning |
+|-----------|---------|
+| Fast | < 100ms each |
+| Isolated | No external deps |
+| Repeatable | Same result always |
+| Self-checking | No manual verification |
+| Timely | Written with code |
+
+### What to Unit Test
+
+| Test | Don't Test |
+|------|------------|
+| Business logic | Framework code |
+| Edge cases | Third-party libs |
+| Error handling | Simple getters |
+
+---
+
+## 5. Integration Test Principles
+
+### What to Test
+
+| Area | Focus |
+|------|-------|
+| API endpoints | Request/response |
+| Database | Queries, transactions |
+| External services | Contracts |
+
+### Setup/Teardown
+
+| Phase | Action |
+|-------|------|
+| Before All | Connect resources |
+| Before Each | Reset state |
+| After Each | Clean up |
+| After All | Disconnect |
+
+---
+
+## 6. Mocking Principles
+
+### When to Mock
+
+| Mock | Don't Mock |
+|------|------------|
+| External APIs | The code under test |
+| Database (unit) | Simple dependencies |
+| Time/random | Pure functions |
+| Network | In-memory stores |
+
+### Mock Types
+
+| Type | Use |
+|------|-----|
+| Stub | Return fixed values |
+| Spy | Track calls |
+| Mock | Set expectations |
+| Fake | Simplified implementation |
+
+---
+
+## 7. Test Organization
+
+### Naming
+
+| Pattern | Example |
+|---------|---------|
+| Should behavior | "should return error when..." |
+| When condition | "when user not found..." |
+| Given-when-then | "given X, when Y, then Z" |
+
+### Grouping
+
+| Level | Use |
+|-------|-----|
+| describe | Group related tests |
+| it/test | Individual case |
+| beforeEach | Common setup |
+
+---
+
+## 8. Test Data
+
+### Strategies
+
+| Approach | Use |
+|----------|-----|
+| Factories | Generate test data |
+| Fixtures | Predefined datasets |
+| Builders | Fluent object creation |
+
+### Principles
+
+- Use realistic data
+- Randomize non-essential values (faker)
+- Share common fixtures
+- Keep data minimal
+
+---
+
+## 9. Best Practices
+
+| Practice | Why |
+|----------|------|
+| One assert per test | Clear failure reason |
+| Independent tests | No order dependency |
+| Fast tests | Run frequently |
+| Descriptive names | Self-documenting |
+| Clean up | Avoid side effects |
+
+---
+
+## 10. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Test implementation | Test behavior |
+| Duplicate test code | Use factories |
+| Complex test setup | Simplify or split |
+| Ignore flaky tests | Fix root cause |
+| Skip cleanup | Reset state |
+
+---
+
+> **Remember:** Tests are documentation. If someone can't understand what code does from the tests, rewrite them.
+
+---
+
+## Bob's Workshop Integration
+
+This skill is used by **bob-eng (engineer)** agent during BUILD phase.
+
+### MANUAL Integration
+
+Add testing section to MANUAL:
+```markdown
+## 🧪 Testing Strategy
+
+### Test Pyramid
+
+```
+        /\          E2E (2-3 tests)
+       /  \         Critical user flows
+      /----\
+     /      \       Integration (10-20 tests)
+    /--------\      API endpoints, DB queries
+   /          \
+  /------------\    Unit (50-100 tests)
+                  Functions, classes, utilities
+```
+
+### Test Coverage
+
+| Layer | Test Type | Count | Coverage Target |
+|-------|-----------|--------|----------------|
+| Unit | Pure functions, logic | 50-100 | 80%+ |
+| Integration | API, DB queries | 10-20 | Critical paths |
+| E2E | User flows | 2-3 | Happy path + key edge cases |
+
+### Test Requirements
+
+#### Unit Tests
+- [ ] All business logic functions tested
+- [ ] Edge cases covered (empty, null, invalid)
+- [ ] Error handling tested
+- [ ] Pure functions isolated (no mocks if possible)
+- [ ] Tests < 100ms each
+
+#### Integration Tests
+- [ ] API endpoints tested
+- [ ] Database queries verified
+- [ ] External services mocked
+- [ ] Transaction rollback tested
+- [ ] Error paths tested
+
+#### E2E Tests
+- [ ] Critical user flows covered
+- [ ] Happy path works
+- [ ] Key edge cases tested
+- [ ] Cross-browser verified (if applicable)
+
+### Mocking Strategy
+
+| Component | Mock/Fake | Rationale |
+|-----------|-----------|-----------|
+| External API | Mock | Unreliable, slow |
+| Database | Fake (in-memory) | Fast, isolated |
+| Time | Mock | Deterministic |
+| Network | Mock | No network dependency |
+
+### Test Framework
+
+- **Unit:** [Jest / Vitest / Pytest / etc.]
+- **Integration:** [Supertest / etc.]
+- **E2E:** [Playwright / Cypress / etc.]
+```
+
+### Test Tasks
+
+Add to implementation plan:
+```markdown
+#### TEST-001: Unit Tests
+- [ ] Test business logic functions → Verify: All tests pass
+- [ ] Test error handling → Verify: Edge cases covered
+- [ ] Test edge cases → Verify: Empty, null, invalid inputs
+
+#### TEST-002: Integration Tests
+- [ ] Test API endpoints → Verify: Returns correct data
+- [ ] Test database queries → Verify: Queries match schema
+- [ ] Test error paths → Verify: Errors handled correctly
+
+#### TEST-003: E2E Tests
+- [ ] Test happy path flow → Verify: User completes main task
+- [ ] Test error recovery → Verify: User can recover from errors
+```
+
+### Verification Criteria
+
+Before handing off to bob-rev:
+- [ ] All tests pass (unit, integration, E2E)
+- [ ] Test coverage meets target (80%+)
+- [ ] No tests are skipped or ignored
+- [ ] Flaky tests identified and fixed
+- [ ] Tests run quickly (<5 minutes total)
+
+### Handoff Format
+
+```markdown
+## 🤝 Agent Handoffs
+
+🤝 bob-eng: Tests written - 75 unit, 15 integration, 3 E2E
+🤝 bob-eng → bob-rev: All tests pass, ready for review
+```
+
+### Best Practices Reminder
+
+**When writing tests:**
+- Write tests with code (TDD if applicable)
+- Keep tests simple and focused
+- Use descriptive names (should/when/given-when-then)
+- One assert per test (when possible)
+- Keep tests fast (<100ms each)
+- Clean up after each test
+
+**What to avoid:**
+- Testing implementation details
+- Testing framework code
+- Duplicate test code (use factories)
+- Complex setup (simplify or split)
+- Skipping tests (fix them)