@pennyfarthing/core 7.4.0 → 7.4.1

package/pennyfarthing-dist/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: systematic-debugging
+description: Systematic debugging approach for isolating and fixing issues. Use when debugging failures, investigating errors, bisecting regressions, or validating fixes.
+---
+
+# Systematic Debugging Skill
+
+**Purpose:** Guide methodical debugging to find root causes, not just symptoms.
+
+**Use when:** Bug reports, test failures, unexpected behavior, regressions.
+
+---
+
+## When to Use This Skill
+
+- Debugging test failures or unexpected behavior
+- Investigating error messages or stack traces
+- Bisecting to find when a regression was introduced
+- Validating that a fix addresses root cause, not just symptoms
+- Intermittent failures that are hard to reproduce
+
+---
+
+## The Debugging Cycle
+
+```
+1. REPRODUCE  → Make the failure happen reliably
+2. ISOLATE    → Narrow down to minimal reproducer
+3. HYPOTHESIZE → Form theory about root cause
+4. TEST       → Validate or invalidate hypothesis
+5. FIX        → Implement solution
+6. VERIFY     → Confirm fix addresses root cause
+```
+
+### Quick Reference
+
+| Phase | Question to Answer | Output |
+|-------|-------------------|--------|
+| REPRODUCE | Can I make it fail consistently? | Reliable reproduction steps |
+| ISOLATE | What's the minimal code/input that triggers it? | Minimal reproducer |
+| HYPOTHESIZE | What could cause this behavior? | Ranked list of theories |
+| TEST | Does evidence support my theory? | Confirmed or refuted hypothesis |
+| FIX | What's the minimal change to fix it? | Working code |
+| VERIFY | Does the fix address root cause? | Regression test |
+
+---
+
+## Phase 1: REPRODUCE
+
+**Goal:** Make the failure happen reliably.
+
+### Steps
+
+1. **Document exact error** - Copy the full error message, stack trace, logs
+2. **Capture environment** - Versions, configuration, system state
+3. **Create reproduction steps** - Exact commands/actions to trigger
+4. **Test reproduction** - Run it 3+ times to confirm consistency
+
+### For Intermittent Failures
+
+| Pattern | Approach |
+|---------|----------|
+| Race condition | Add delays, run in tight loop, stress test |
+| State-dependent | Reset to clean state, document preconditions |
+| Environment-specific | Compare working vs failing environments |
+| Timing-dependent | Add timestamps, check for timeouts |
+
+### Example
+
+```bash
+# Document the failure
+$ npm test -- -t "user authentication"
+# Error: Expected 200 but got 401
+
+# Capture environment
+$ node --version  # v18.17.0
+$ npm --version   # 9.6.7
+
+# Reproduction steps
+1. Start fresh database: docker-compose down -v && docker-compose up -d
+2. Run: npm test -- -t "user authentication"
+3. Observe: 401 error on third test
+
+# Verify reproduction
+$ npm test -- -t "user authentication"  # Fails
+$ npm test -- -t "user authentication"  # Fails
+$ npm test -- -t "user authentication"  # Fails - consistent!
+```
+
+---
+
+## Phase 2: ISOLATE
+
+**Goal:** Narrow down to the smallest code/input that triggers the bug.
+
+### Techniques
+
+#### Binary Search (Code)
+
+```
+1. Find a known-good commit
+2. Find the failing commit
+3. git bisect between them
+4. Each step: test, mark good/bad
+5. Arrive at first bad commit
+```
+
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good v1.2.0
+# Git checks out middle commit
+npm test -- -t "failing test"
+git bisect bad  # or good
+# Repeat until found
+git bisect reset
+```
+
+#### Minimal Reproducer
+
+1. Start with failing test/code
+2. Remove components one at a time
+3. Stop when removal fixes the bug
+4. The last removed component is involved
+
+#### Variable Elimination
+
+| Remove | Still fails? | Conclusion |
+|--------|--------------|------------|
+| External API calls | Yes | Not API-related |
+| Database queries | No | Database-related |
+| Specific table | Yes | Not that table |
+| Auth middleware | No | Auth is involved |
+
+### Example
+
+```typescript
+// Full failing code
+async function createUser(data) {
+  validateInput(data);
+  const hash = await hashPassword(data.password);
+  const user = await db.insert({ ...data, password: hash });
+  await sendWelcomeEmail(user.email);
+  return user;
+}
+
+// Minimal reproducer (isolated the issue)
+async function createUser(data) {
+  const user = await db.insert(data);  // Fails here!
+  return user;
+}
+// Conclusion: Issue is in db.insert, not validation/email
+```
+
+---
+
+## Phase 3: HYPOTHESIZE
+
+**Goal:** Form testable theories about root cause.
+
+### Common Root Causes
+
+| Category | Examples |
+|----------|----------|
+| State | Uninitialized variable, stale cache, leftover data |
+| Timing | Race condition, timeout, async ordering |
+| Input | Edge case, null/undefined, empty collection, boundary |
+| Environment | Missing env var, wrong version, config mismatch |
+| Logic | Off-by-one, wrong operator, incorrect condition |
+
+### Hypothesis Formation
+
+1. **Read the error message carefully** - Often tells you exactly what's wrong
+2. **Check recent changes** - `git log --oneline -20`, `git diff HEAD~5`
+3. **Consider edge cases** - What if null? Empty? Max value?
+4. **Look for patterns** - When does it fail vs succeed?
+
+### Rank Hypotheses
+
+```
+Hypothesis 1 (HIGH): Database connection timing out
+- Evidence: Error mentions timeout, happens under load
+- Test: Check connection pool settings
+
+Hypothesis 2 (MEDIUM): Invalid input not validated
+- Evidence: Stack trace shows null pointer in parser
+- Test: Add input validation logging
+
+Hypothesis 3 (LOW): Bug in library
+- Evidence: Nothing obvious in our code
+- Test: Check library issues, try downgrade
+```
+
+---
+
+## Phase 4: TEST
+
+**Goal:** Validate or invalidate each hypothesis.
+
+### Testing Approaches
+
+| Approach | When to Use |
+|----------|-------------|
+| Add logging | Need to see values at runtime |
+| Debugger breakpoint | Need to inspect state interactively |
+| Unit test | Can isolate the specific function |
+| Print statements | Quick check in specific location |
+| Assertion | Verify assumption holds |
+
+### Logging Strategy
+
+```typescript
+// Add strategic logging
+console.log('[DEBUG] Input:', JSON.stringify(data));
+console.log('[DEBUG] Before DB call, user:', user?.id);
+console.log('[DEBUG] After DB call, result:', result);
+console.log('[DEBUG] Query took:', endTime - startTime, 'ms');
+```
+
+### Hypothesis Testing
+
+```
+HYPOTHESIS: Connection pool exhausted under load
+
+TEST 1: Check pool stats
+> db.pool.stats()
+{ active: 50, idle: 0, waiting: 12 }  // Pool full!
+
+TEST 2: Increase pool size
+> config.pool.max = 100
+> Rerun test
+> PASS
+
+CONCLUSION: Hypothesis confirmed. Pool too small.
+```
+
+### When Hypothesis is Wrong
+
+If evidence doesn't support your theory:
+1. Don't force-fit the evidence
+2. Return to HYPOTHESIZE phase
+3. Form new theory based on new observations
+4. Repeat until you find the cause
+
+---
+
+## Phase 5: FIX
+
+**Goal:** Implement the minimal change that fixes the issue.
+
+### Fix Principles
+
+1. **Fix the root cause, not the symptom**
+   - BAD: Add try/catch to hide the error
+   - GOOD: Fix why the error occurs
+
+2. **Minimal change**
+   - Change only what's necessary
+   - Don't refactor while fixing bugs
+
+3. **One fix per bug**
+   - Don't bundle unrelated changes
+   - Makes it clear what fixed what
+
+### Fix Template
+
+```typescript
+// BEFORE: Bug - pool exhaustion under load
+const pool = new Pool({ max: 10 });
+
+// AFTER: Fix - increase pool size based on expected load
+const pool = new Pool({
+  max: 50,  // Increased from 10 to handle peak load
+  idleTimeoutMillis: 30000,
+});
+```
+
+---
+
+## Phase 6: VERIFY
+
+**Goal:** Confirm the fix addresses root cause and doesn't break anything else.
+
+### Verification Checklist
+
+- [ ] Original reproduction steps now pass
+- [ ] New test case covers the bug (regression test)
+- [ ] Existing tests still pass
+- [ ] Fix doesn't introduce new issues
+- [ ] Fix addresses root cause, not just symptom
+
+### Write a Regression Test
+
+```typescript
+// This test should have caught the bug
+test('handles concurrent requests without pool exhaustion', async () => {
+  const requests = Array(100).fill(null).map(() => api.createUser());
+  const results = await Promise.all(requests);
+  expect(results.every(r => r.status === 201)).toBe(true);
+});
+```
+
+### Symptom vs Root Cause Check
+
+Ask yourself:
+- "Would this bug happen again in a different form?"
+- "Did I fix WHY it happened, or just WHAT happened?"
+
+| Fix | Symptom or Root Cause? |
+|-----|------------------------|
+| Add null check | Symptom (why is it null?) |
+| Initialize variable properly | Root cause |
+| Increase timeout | Symptom (why is it slow?) |
+| Fix N+1 query | Root cause |
+
+---
+
+## Debugging Anti-Patterns
+
+### What NOT to Do
+
+| Anti-Pattern | Why It's Bad | Instead |
+|--------------|--------------|---------|
+| Random changes | Introduces new bugs, wastes time | Follow the cycle |
+| Fix without reproducing | Can't verify fix works | Always reproduce first |
+| Blame external factors | Delays finding real cause | Assume it's your code |
+| Skip verification | Bug may not be fixed | Always verify |
+| Big refactor as "fix" | Hides what actually fixed it | Minimal changes |
+
+### Common Traps
+
+1. **Confirmation bias** - Looking for evidence that supports your theory
+2. **Premature optimization** - Fixing performance before correctness
+3. **Tunnel vision** - Fixating on one hypothesis
+4. **Solution jumping** - Skipping to fix before understanding
+
+---
+
+## Quick Debugging Commands
+
+### Git Bisect (Find Regression)
+
+```bash
+git bisect start
+git bisect bad                 # Current commit is bad
+git bisect good v1.0.0         # Known good commit
+# Run test, then:
+git bisect good  # or bad
+# Repeat until found
+git bisect reset
+```
+
+### Find Recent Changes
+
+```bash
+# What changed recently?
+git log --oneline -20
+git diff HEAD~5
+
+# Who changed this file?
+git blame path/to/file.ts
+
+# When did this line change?
+git log -p -S "problematic code" -- path/to/file.ts
+```
+
+### Check Running Processes
+
+```bash
+# What's using resources?
+ps aux | grep node
+lsof -i :3000
+
+# Check memory/CPU
+top -l 1 | head -20
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | How It Complements |
+|-------|-------------------|
+| `/testing` | Run tests to verify fixes |
+| `/dev-patterns` | Avoid common pitfalls |
+| `/agentic-patterns` | ReAct pattern for systematic investigation |
+
+---
+
+**Remember:** Debugging is detective work. Follow the evidence, test your theories, and fix the root cause. Rushing leads to band-aid fixes that break later.

package/pennyfarthing-dist/skills/testing/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: testing
+description: Test commands and patterns for TDD workflow. This skill should be used when running tests, debugging test failures, setting up test infrastructure, or writing new tests. Provides framework-agnostic patterns that projects customize.
+---
+
+# Testing Skill
+
+## When to Use This Skill
+
+- Running tests (backend, frontend, or all)
+- Debugging test failures
+- Setting up test containers/infrastructure
+- Writing new tests
+- Pre-commit verification
+- Understanding TDD workflow
+
+## TDD Workflow (RED → GREEN → REFACTOR)
+
+```
+1. TEA writes failing tests (RED)
+2. Dev implements code to pass tests (GREEN)
+3. Dev refactors while keeping tests GREEN
+4. Reviewer validates quality
+```
+
+## Quick Reference
+
+```bash
+# Setup test infrastructure (run once per session)
+# Project-specific: check your justfile or package.json
+
+# Run all tests
+just test              # If using just
+npm test               # If using npm
+go test ./...          # If using Go directly
+
+# Run specific test patterns
+just test-api -run "TestName"     # Go pattern
+npm test -- -t "test name"        # Jest/Vitest pattern
+```
+
+## Test Command Patterns
+
+### Go (Backend)
+
+```bash
+# Run all tests
+go test ./...
+
+# Run tests in specific package
+go test ./internal/handlers
+
+# Run tests matching pattern
+go test -run "TestCreate" ./...
+
+# Verbose output
+go test -v ./internal/handlers
+
+# With coverage
+go test -cover ./...
+```
+
+### Node/React (Frontend)
+
+```bash
+# Run all tests (Vitest)
+npm test
+
+# Run tests matching pattern
+npm test -- -t "button"
+
+# Watch mode
+npm test -- --watch
+
+# Coverage
+npm test -- --coverage
+```
+
+## Test File Naming Conventions
+
+| Type | Go Pattern | TypeScript Pattern |
+|------|------------|-------------------|
+| Unit test | `*_test.go` | `*.test.ts`, `*.test.tsx` |
+| Integration | `*_integration_test.go` | `*.integration.test.ts` |
+| E2E | N/A | `*.e2e.test.ts` |
+
+## Reference Documentation
+
+- **Troubleshooting:** See `references/troubleshooting.md`
+- **TDD Policy:** See `references/tdd-policy.md` (project-specific)
+- **Backend Patterns:** See `references/backend-patterns.md` (project-specific)
+- **Frontend Patterns:** See `references/frontend-patterns.md` (project-specific)
+
+## Project Customization
+
+Projects should create their own testing skill in `.claude/project/skills/testing/` with:
+- Project-specific test commands
+- Custom patterns and conventions
+- Infrastructure setup instructions

package/pennyfarthing-dist/skills/testing/references/troubleshooting.md

@@ -0,0 +1,124 @@
+# Test Troubleshooting Guide
+
+## Tests Timing Out
+
+```bash
+# Ensure test infrastructure is running
+just test-setup        # Or project-specific setup command
+
+# Check container status
+docker ps
+
+# Increase timeout if needed
+go test -timeout 60s ./...
+```
+
+## "No Tests to Run" Message
+
+### Go Tests
+
+The `-run` flag filters by **test function name**, not by file or domain:
+- `-run "User"` matches `TestUserCreate` but NOT `TestCreateAccount`
+- The pattern is a regex, case-sensitive
+
+```bash
+# Run ALL tests in a package (no name filter)
+go test ./internal/handlers/...
+
+# Run tests with "Create" in name in specific package
+go test -run "Create" ./internal/handlers
+```
+
+### JavaScript/TypeScript Tests
+
+The `-t` flag filters by test description:
+
+```bash
+# Run tests matching description
+npm test -- -t "should create user"
+
+# Run all tests in a file
+npm test -- path/to/file.test.ts
+```
+
+## Case Sensitivity
+
+### Go
+- `-run "User"` - Correct (matches TestUser...)
+- `-run "user"` - Won't match (Go regex is case-sensitive)
+
+### Jest/Vitest
+- `-t "user"` - Case-insensitive by default
+
+## Package/Path Format
+
+### Go
+```bash
+./internal/handlers      # Correct - relative with ./
+internal/handlers        # May not work without ./
+./internal/handlers/...  # Include subpackages
+```
+
+### Node
+```bash
+src/components           # Relative path
+./src/components         # Also works
+```
+
+## Tests Passing Locally but Failing in CI
+
+1. **Environment differences** - Check env vars
+2. **Race conditions** - Run tests multiple times locally
+3. **Database state** - Ensure clean state between tests
+
+```bash
+# Run full test suite to catch integration issues
+just test
+
+# Run tests with race detection (Go)
+go test -race ./...
+```
+
+## Container Issues
+
+```bash
+# Restart test containers
+docker-compose -f docker-compose.test.yml down
+docker-compose -f docker-compose.test.yml up -d
+
+# Check container logs
+docker logs <container-name>
+
+# Verify connectivity
+docker exec <container-name> pg_isready  # Postgres
+docker exec <container-name> redis-cli ping  # Redis
+```
+
+## Database Connection Errors
+
+```bash
+# Check environment variables
+echo $TEST_DATABASE_URL
+
+# Verify database is accepting connections
+psql $TEST_DATABASE_URL -c "SELECT 1"
+```
+
+## Common Patterns
+
+### Flaky Tests
+
+1. Check for timing dependencies
+2. Look for shared state between tests
+3. Ensure proper cleanup in teardown
+4. Consider using test isolation
+
+### Memory Issues
+
+```bash
+# Run with memory limit (Go)
+go test -memprofile mem.out ./...
+
+# Check for goroutine leaks
+go test -race ./...
+```