Commit 9eb15e1f1c12

@@ -0,0 +1,387 @@
+---
+name: Brainstorming
+description: Interactive design refinement through collaborative dialogue before implementation. USE WHEN user wants to design a feature OR plan architecture OR explore approaches OR needs help thinking through implementation before coding OR asks "how should I" build something. Asks questions one at a time, proposes alternatives, validates incrementally.
+---
+
+# Brainstorming
+
+Turn ideas into fully formed designs through natural collaborative dialogue before writing code.
+
+## Overview
+
+Help refine vague ideas into concrete, implementable designs by:
+- Understanding project context first
+- Asking focused questions (one at a time)
+- Proposing alternative approaches with trade-offs
+- Validating design incrementally
+- Documenting the final validated design
+
+## The Process
+
+### Phase 1: Understanding the Idea
+
+**Check context first:**
+
+```bash
+# Review current project state
+git log --oneline -10
+
+# Check existing patterns
+rg "similar-feature" --files-with-matches
+
+# Examine recent changes
+git diff main...HEAD --stat
+```
+
+**Ask questions one at a time:**
+- Prefer multiple choice when possible
+- Open-ended questions are fine for exploration
+- Focus on: purpose, constraints, success criteria
+- Don't overwhelm with multiple questions at once
+
+**Key questions to explore:**
+- What problem does this solve?
+- Who are the users?
+- What are the constraints (performance, compatibility, complexity)?
+- What defines success?
+- Are there existing patterns to follow?
+
+### Phase 2: Exploring Approaches
+
+**Propose 2-3 different approaches with trade-offs:**
+
+1. Lead with your recommended option
+2. Explain reasoning clearly
+3. Present trade-offs honestly
+4. Consider existing patterns in the codebase
+
+**Template for presenting options:**
+
+```
+I see [number] approaches:
+
+1. **[Approach Name]** (Recommended)
+   + [Advantage 1]
+   + [Advantage 2]
+   - [Disadvantage 1]
+
+2. **[Alternative Approach]**
+   + [Advantage]
+   - [Disadvantage]
+
+3. **[Another Alternative]**
+   + [Advantage]
+   - [Disadvantage]
+
+I recommend #1 because [specific reasoning based on context].
+```
+
+**Example:**
+```
+I see three approaches for implementing caching:
+
+1. **Redis with TTL** (Recommended)
+   + Persistent across restarts
+   + Already using Redis for sessions
+   + Supports complex invalidation patterns
+   - Adds network latency
+
+2. **In-memory cache (sync.Map)**
+   + Fastest access (no network)
+   + Simple implementation
+   - Lost on restart
+   - No sharing across instances
+
+3. **HTTP cache headers + CDN**
+   + Offloads to edge
+   + Reduces backend load
+   - Less control over invalidation
+   - Requires public endpoints
+
+I recommend #1 because you need cache persistence and already
+have Redis infrastructure in place.
+```
+
+### Phase 3: Presenting the Design
+
+**Break design into digestible sections (200-300 words each):**
+
+1. **Architecture Overview**: High-level structure, components, relationships
+2. **Component Breakdown**: Detailed responsibilities of each part
+3. **Data Flow**: How information moves through the system
+4. **Error Handling**: How failures are detected and handled
+5. **Testing Strategy**: How to verify correctness
+
+**Validate incrementally:**
+- Present one section at a time
+- After each section: "Does this look right so far?"
+- Be ready to go back and clarify
+- Don't proceed if user has concerns
+
+**Example section presentation:**
+
+```
+## Architecture Overview
+
+The caching layer sits between the API handlers and the database:
+
+```
+[API Handler] → [Cache Middleware] → [Database]
+                       ↓
+                   [Redis]
+```
+
+The middleware:
+- Checks Redis for cached responses
+- On cache miss, calls database and caches result
+- Invalidates cache on write operations
+- Uses key pattern: `cache:v1:{resource}:{id}`
+
+Does this high-level structure look right so far?
+```
+
+### Phase 4: After Design Validation
+
+**Document the validated design:**
+
+```bash
+# Create design document
+TOPIC="feature-name"
+DATE=$(date +%Y-%m-%d)
+DOC_PATH="docs/plans/${DATE}-${TOPIC}-design.md"
+
+cat > "$DOC_PATH" <<'EOF'
+# [Feature Name] Design
+
+**Date**: [Date]
+**Status**: Validated
+
+## Problem Statement
+[What we're solving]
+
+## Architecture
+[Validated architecture]
+
+## Components
+[Component breakdown]
+
+## Data Flow
+[How data moves]
+
+## Error Handling
+[Failure scenarios]
+
+## Testing Strategy
+[How to verify]
+
+## Implementation Notes
+[Important considerations]
+EOF
+
+git add "$DOC_PATH"
+```
+
+**Offer next steps:**
+- "Ready to set up for implementation?"
+- "Should I create a detailed implementation plan?"
+- "Want to break this into phases?"
+
+## Key Principles
+
+### YAGNI Ruthlessly
+**You Aren't Gonna Need It**
+
+During brainstorming, actively remove features that:
+- Sound nice but aren't required for the core use case
+- Could be added later if needed
+- Add complexity without clear value
+- Are "just in case" features
+
+**Example:**
+```
+User: "And we should probably add support for multiple formats: JSON, XML, YAML, TOML..."
+Assistant: "Let's start with just JSON since that's what you're using now. We can add other formats later if needed. Simpler is better."
+```
+
+### One Question at a Time
+
+**Don't do this:**
+```
+What problem are you solving? Who are the users? What are the
+performance requirements? Do you need offline support? What's
+the expected scale?
+```
+
+**Do this instead:**
+```
+What's the primary problem this feature solves?
+
+[Wait for answer]
+
+Got it. Who will be using this feature - developers, end users, or both?
+
+[Wait for answer]
+
+Thanks. Are there any performance constraints I should know about?
+```
+
+### Multiple Choice When Possible
+
+**Better:**
+```
+What's more important for this feature:
+
+A) Speed (sub-100ms response time)
+B) Reliability (never lose data)
+C) Simplicity (easy to maintain)
+
+Or something else?
+```
+
+**Instead of:**
+```
+What are your requirements for this feature?
+```
+
+### Explore Alternatives Always
+
+Never settle on first approach. Always:
+1. Identify at least 2-3 alternatives
+2. Present trade-offs
+3. Recommend one with reasoning
+4. Let user decide
+
+### Be Flexible
+
+If user seems confused or uncomfortable:
+- Back up and clarify
+- Ask simpler questions
+- Provide examples
+- Don't force forward progress
+
+## Integration with Other Skills
+
+**Before brainstorming:**
+- Check project context with **Grep** and **Read** tools
+- Review architecture patterns in codebase
+
+**After brainstorming:**
+- Use **TestDrivenDevelopment** for implementation
+- Create implementation plan (can be added as workflow)
+- Consider using **EnterPlanMode** for complex features
+
+**During brainstorming:**
+- Use **Notes** skill to capture key decisions
+- Reference **CORE** principles for technology choices
+
+## Examples
+
+**Example 1: Feature design request**
+```
+User: "I want to add caching to the API"
+
+→ Invoke Brainstorming skill
+→ Check existing codebase for caching patterns
+→ Ask: "What's driving this: reducing database load, improving response time, or both?"
+→ User: "Response time"
+→ Ask: "Should cache invalidate on writes, use TTL, or both?"
+→ User: "TTL with manual invalidation for writes"
+→ Propose three approaches: Redis, in-memory, CDN
+→ Present recommended approach (Redis) with reasoning
+→ Break down architecture into sections:
+  1. Middleware structure
+  2. Cache key strategy
+  3. Invalidation logic
+  4. Error handling
+→ Validate each section with user
+→ Document final design in docs/plans/
+→ Offer to create implementation plan
+```
+
+**Example 2: Architecture planning**
+```
+User: "How should I structure the authentication service?"
+
+→ Invoke Brainstorming skill
+→ Check existing patterns in codebase
+→ Ask: "What type of auth: OAuth, JWT, session-based, or something else?"
+→ User: "JWT"
+→ Ask: "Will you need refresh tokens or just access tokens?"
+→ User: "Both"
+→ Propose three architectural approaches:
+  1. Stateless JWT with refresh token store
+  2. Fully stateless (no refresh token persistence)
+  3. Hybrid (JWT + session validation)
+→ Recommend #1 with reasoning
+→ Present design in sections:
+  1. Token generation flow
+  2. Validation middleware
+  3. Refresh token rotation
+  4. Secret management (with agenix reference)
+→ Validate each section
+→ Document design
+→ Create implementation checklist
+```
+
+**Example 3: Exploring approaches before committing**
+```
+User: "I need to add real-time notifications"
+
+→ Invoke Brainstorming skill
+→ Ask: "How many concurrent users do you expect?"
+→ User: "Maybe 100-200"
+→ Ask: "Do clients need bi-directional communication or just server-to-client?"
+→ User: "Just server to client for now"
+→ Propose approaches:
+  1. WebSockets (most common)
+  2. Server-Sent Events (simpler for one-way)
+  3. Long polling (widest compatibility)
+→ Recommend SSE for your use case (simpler, one-way)
+→ Present design:
+  1. SSE endpoint structure
+  2. Connection management
+  3. Message format
+  4. Reconnection handling
+→ User validates
+→ Document and proceed to implementation
+```
+
+**Example 4: Refactoring planning**
+```
+User: "This module has gotten too complex, help me think through how to refactor it"
+
+→ Invoke Brainstorming skill
+→ Read the current module code
+→ Ask: "What's the main pain point: testing, understanding, or modifying?"
+→ User: "Hard to test, too many dependencies"
+→ Propose refactoring strategies:
+  1. Extract interfaces for dependencies (DI approach)
+  2. Split into smaller modules by domain
+  3. Event-driven with message passing
+→ Recommend #2 (splitting) based on code structure
+→ Present refactoring plan:
+  1. Identify domain boundaries
+  2. Define module interfaces
+  3. Migration strategy (incremental)
+  4. Testing approach for each phase
+→ Validate plan
+→ Create phased implementation checklist
+```
+
+## Common Pitfalls to Avoid
+
+**Don't:**
+- Jump to implementation before understanding
+- Present only one approach
+- Overwhelm with too many options (>3)
+- Skip validation of each design section
+- Forget to document the final design
+- Add features without clear requirements (fight YAGNI violations)
+
+**Do:**
+- Take time to understand context
+- Present clear trade-offs
+- Recommend an approach with reasoning
+- Validate incrementally
+- Document thoroughly
+- Remove unnecessary complexity

@@ -0,0 +1,578 @@
+---
+name: SystematicDebugging
+description: Evidence-based debugging methodology emphasizing observation over assumptions following the scientific method. USE WHEN user reports a bug OR system behavior is unexpected OR troubleshooting issues OR investigating errors OR debugging failures. Follows observe, hypothesize, test, verify cycle with disciplined evidence gathering.
+---
+
+# SystematicDebugging
+
+Disciplined evidence-based approach to finding and fixing bugs using the scientific method.
+
+## The Scientific Method for Debugging
+
+```
+OBSERVE → HYPOTHESIZE → TEST → VERIFY
+    ↑                              ↓
+    └──────────────────────────────┘
+         (Repeat until solved)
+```
+
+## Core Principle
+
+**Evidence Over Assumptions**
+
+Never assume you know what's wrong. Always:
+- Gather evidence first
+- Form hypothesis based on evidence
+- Test hypothesis with minimal changes
+- Verify the fix works
+
+## The Process
+
+### Phase 1: Observe (Don't Assume)
+
+**Gather evidence systematically:**
+
+```bash
+# Check application logs
+journalctl -u ${service} -n 100 --no-pager
+
+# Check system logs
+tail -f /var/log/syslog
+
+# Check service status
+systemctl status ${service}
+
+# Check resource usage
+top -bn1 | head -20
+
+# Check recent changes
+git log --oneline --since="1 week ago" -- ${relevant_paths}
+
+# Check environment
+env | grep -i ${service}
+```
+
+**Critical questions to answer:**
+1. What is the EXACT error message (copy it verbatim)?
+2. When did this start happening?
+3. What changed recently (code, config, environment)?
+4. Can you reproduce it reliably?
+5. What's the minimum reproduction case?
+
+**Document your observations:**
+```bash
+# Create debug log
+cat > /tmp/debug-$(date +%Y%m%d-%H%M%S).log <<EOF
+## Observations
+
+**Error**: [Exact error message]
+**Started**: [When it began]
+**Frequency**: [Always/Sometimes/Rare]
+**Recent changes**: [Git commits, deployments, config changes]
+**Environment**: [OS, version, dependencies]
+
+## Reproduction Steps
+1. [Step 1]
+2. [Step 2]
+3. [Observed result]
+4. [Expected result]
+EOF
+```
+
+### Phase 2: Form Hypothesis
+
+**Based on evidence, create testable hypothesis:**
+
+**Template:**
+```
+Given [observation],
+I hypothesize [root cause],
+because [reasoning].
+
+If this is true, then [expected outcome].
+```
+
+**Example:**
+```
+Given: Service fails to start after reboot with "connection refused"
+I hypothesize: Missing network dependency in systemd unit
+because: Service likely starts before network is ready
+
+If this is true, then: Adding After=network-online.target should fix it
+```
+
+**Document your hypothesis:**
+```bash
+cat >> /tmp/debug-*.log <<EOF
+
+## Hypothesis #1
+
+**Given**: [Observation]
+**Hypothesis**: [Root cause]
+**Reasoning**: [Why you think this]
+**Test**: [How to verify]
+**Expected**: [What should happen if correct]
+EOF
+```
+
+### Phase 3: Test Hypothesis
+
+**Design minimal, isolated test:**
+
+**Rules for testing:**
+1. **Change ONE variable at a time**
+2. **Add logging/instrumentation**
+3. **Create reproducible test case**
+4. **Document what you're changing**
+
+**Example - Add debugging:**
+```bash
+# Add logging to startup script
+cat > /tmp/debug-startup.sh <<'EOF'
+#!/bin/bash
+echo "DEBUG: Starting service at $(date)" >> /tmp/service-debug.log
+echo "DEBUG: Network status: $(ip addr show)" >> /tmp/service-debug.log
+exec /usr/bin/actual-service
+EOF
+```
+
+**Example - Test specific condition:**
+```bash
+# Test if file exists
+if [ -f /var/run/service.pid ]; then
+    echo "FOUND: PID file exists"
+    cat /var/run/service.pid
+else
+    echo "MISSING: PID file does not exist"
+    ls -la /var/run/
+fi
+```
+
+**Example - Isolate component:**
+```go
+// Add logging to isolate which component fails
+func StartService() error {
+    log.Println("DEBUG: Initializing database connection")
+    db, err := initDB()
+    if err != nil {
+        log.Printf("DEBUG: Database init failed: %v", err)
+        return err
+    }
+
+    log.Println("DEBUG: Starting HTTP server")
+    return startHTTP(db)
+}
+```
+
+**Document your test:**
+```bash
+cat >> /tmp/debug-*.log <<EOF
+
+## Test #1
+
+**Change**: [What you changed]
+**Expected**: [What should happen if hypothesis is correct]
+**Command**: \`[Command you ran]\`
+**Result**: [What actually happened]
+**Conclusion**: [Hypothesis confirmed/rejected]
+EOF
+```
+
+### Phase 4: Verify Fix
+
+**After implementing a fix:**
+
+1. **Verify bug no longer reproduces**
+2. **Verify no new bugs introduced**
+3. **Run full test suite**
+4. **Check logs for expected behavior**
+5. **Test edge cases**
+
+**Verification checklist:**
+```bash
+# 1. Original bug doesn't reproduce
+[reproduction command]
+# Expected: Works correctly
+
+# 2. Related functionality still works
+[test related features]
+
+# 3. Tests pass
+go test ./...
+pytest
+cargo test
+
+# 4. Clean logs
+journalctl -u ${service} -n 20 --no-pager
+# Expected: No errors
+
+# 5. Edge cases work
+[test boundary conditions]
+```
+
+**Add regression test:**
+```go
+// Prevent bug from returning
+func TestBugFix_NegativePriceHandling(t *testing.T) {
+    // Bug: Negative prices caused panic
+    // Fix: Added validation to reject negative prices
+    order := Order{Price: -10}
+    err := order.Validate()
+    if err == nil {
+        t.Error("Expected error for negative price, got nil")
+    }
+    if !strings.Contains(err.Error(), "negative") {
+        t.Errorf("Expected error about negative price, got: %v", err)
+    }
+}
+```
+
+**Document the fix:**
+```bash
+cat >> /tmp/debug-*.log <<EOF
+
+## Solution
+
+**Root cause**: [What was actually wrong]
+**Fix**: [What you changed]
+**Verification**:
+- [✓] Original bug resolved
+- [✓] No regressions
+- [✓] Tests pass
+- [✓] Regression test added
+
+**Files changed**:
+- [file1]: [description]
+- [file2]: [description]
+
+**Commit**: [commit hash]
+EOF
+
+# Save to history
+cp /tmp/debug-*.log ~/.config/claude/history/debugging/$(date +%Y-%m)/
+```
+
+## Debugging Checklist
+
+### Before Diving In
+
+- [ ] Read the COMPLETE error message (including stack trace)
+- [ ] Check logs for full context (before and after error)
+- [ ] Identify what changed recently (git log, deployments)
+- [ ] Create minimal reproduction case
+- [ ] State your hypothesis explicitly before testing
+
+### While Debugging
+
+- [ ] Test ONE hypothesis at a time
+- [ ] Add logging, don't assume
+- [ ] Document what you tried and results
+- [ ] Keep track of working states
+- [ ] Don't change multiple things simultaneously
+- [ ] Take breaks if stuck (fresh perspective helps)
+
+### After Fixing
+
+- [ ] Verify fix solves original problem
+- [ ] Check for side effects
+- [ ] Run full test suite
+- [ ] Add regression test
+- [ ] Remove debug logging
+- [ ] Document root cause
+- [ ] Update relevant documentation
+
+## Common Pitfalls
+
+### Don't Do This
+
+❌ **Changing multiple things without testing**
+```bash
+# Wrong: Shotgun debugging
+sed -i 's/timeout=5/timeout=30/' config.yaml
+systemctl restart service
+sed -i 's/retries=3/retries=10/' config.yaml
+systemctl restart service
+```
+
+❌ **Assuming you know the cause**
+```
+"It's probably the database connection"
+[Spends hours investigating database]
+[Actual cause: typo in config file]
+```
+
+❌ **Debugging without logs**
+```go
+// Wrong: No visibility
+func Process() error {
+    db.Connect()
+    data := fetch()
+    process(data)
+    return nil
+}
+```
+
+❌ **Skipping reproduction**
+```
+"User says it sometimes fails"
+[Tries to fix without reproducing]
+[Can't verify fix works]
+```
+
+### Do This Instead
+
+✅ **Change one thing, test, observe**
+```bash
+# Right: Systematic testing
+sed -i 's/timeout=5/timeout=30/' config.yaml
+systemctl restart service
+journalctl -u service -n 20  # Check result
+```
+
+✅ **Gather evidence first**
+```bash
+# Check recent changes
+git log --oneline --since="2 days ago"
+
+# Check logs
+journalctl -u service --since="2 days ago" | grep -i error
+
+# Check config
+diff config.yaml.backup config.yaml
+```
+
+✅ **Add comprehensive logging**
+```go
+// Right: Instrument for visibility
+func Process() error {
+    log.Println("DEBUG: Connecting to database")
+    if err := db.Connect(); err != nil {
+        log.Printf("DEBUG: DB connection failed: %v", err)
+        return err
+    }
+
+    log.Println("DEBUG: Fetching data")
+    data := fetch()
+    log.Printf("DEBUG: Fetched %d records", len(data))
+
+    log.Println("DEBUG: Processing data")
+    process(data)
+    return nil
+}
+```
+
+✅ **Create reproduction case**
+```bash
+# Minimal reproduction script
+cat > reproduce-bug.sh <<'EOF'
+#!/bin/bash
+set -e
+
+echo "Step 1: Start service"
+systemctl start service
+
+echo "Step 2: Send request"
+curl http://localhost:8080/trigger-bug
+
+echo "Step 3: Check logs"
+journalctl -u service -n 10
+EOF
+
+chmod +x reproduce-bug.sh
+./reproduce-bug.sh
+```
+
+## Debugging Tools by Language/Environment
+
+### NixOS/systemd Services
+```bash
+# Service status and recent logs
+systemctl status ${service}
+
+# Follow logs in real-time
+journalctl -u ${service} -f
+
+# Check service dependencies
+systemctl list-dependencies ${service}
+
+# Verify configuration
+nixos-rebuild build && nix-instantiate --eval '<nixpkgs/nixos>' -A config.systemd.services.${service}
+```
+
+### Go
+```go
+// Use delve debugger
+dlv debug ./cmd/app -- --config=dev.yaml
+
+// Add instrumentation
+import _ "net/http/pprof"
+
+// Runtime stack traces
+import "runtime/debug"
+debug.PrintStack()
+```
+
+### Python
+```python
+# Use pdb
+import pdb; pdb.set_trace()
+
+# Logging
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Trace function calls
+import sys
+sys.settrace(trace_function)
+```
+
+### Rust
+```rust
+// Use RUST_BACKTRACE
+RUST_BACKTRACE=1 cargo run
+
+// Debug logging
+env_logger::init();
+log::debug!("Value: {:?}", value);
+
+// Use rust-lldb
+rust-lldb target/debug/app
+```
+
+### Network Issues
+```bash
+# Check connectivity
+ping ${host}
+telnet ${host} ${port}
+curl -v http://${host}:${port}
+
+# Check DNS
+dig ${domain}
+nslookup ${domain}
+
+# Check open ports
+ss -tlnp | grep ${port}
+netstat -tlnp | grep ${port}
+
+# Packet capture
+tcpdump -i any -n port ${port}
+```
+
+## Integration with Other Skills
+
+**Before debugging:**
+- Use **Grep** and **Read** to examine code
+- Check **Git** history for recent changes
+- Review service configurations
+
+**After fixing:**
+- Use **TestDrivenDevelopment** to add regression tests
+- Update documentation with **Notes** skill
+- Consider if fix should be documented in troubleshooting guide
+
+**When debugging is extensive:**
+- Document the investigation process
+- Create **Notes** entry with solution
+- Add to troubleshooting documentation
+
+## Examples
+
+**Example 1: Service won't start**
+```
+User: "The jellyfin service fails to start after reboot"
+
+→ Invoke SystematicDebugging skill
+→ OBSERVE: Check systemctl status jellyfin
+→ OBSERVE: Check journalctl -u jellyfin
+→ Error: "Failed to bind to port 8096: address already in use"
+→ OBSERVE: Check what's using port 8096
+→ Find: Old process still running
+→ HYPOTHESIS: Process not cleaned up on shutdown
+→ TEST: Add KillMode=control-group to systemd unit
+→ TEST: Reboot and verify
+→ VERIFY: Service starts successfully
+→ FIX: Update NixOS configuration
+→ Add regression test in CI
+```
+
+**Example 2: Intermittent failures**
+```
+User: "API sometimes returns 500, can't reproduce consistently"
+
+→ Invoke SystematicDebugging skill
+→ OBSERVE: Gather error logs with timestamps
+→ OBSERVE: Check for patterns (time of day, request rate, specific endpoints)
+→ Pattern found: Errors increase under load
+→ HYPOTHESIS: Race condition or resource exhaustion
+→ TEST: Add connection pool monitoring
+→ Find: Database connection pool exhausted during spikes
+→ HYPOTHESIS: Connection pool too small
+→ TEST: Increase pool size from 10 to 50
+→ TEST: Load test with monitoring
+→ VERIFY: No more 500 errors under load
+→ FIX: Update configuration
+→ Add metrics for connection pool usage
+→ Set up alerts for pool exhaustion
+```
+
+**Example 3: Configuration issue after NixOS update**
+```
+User: "After updating to nixos-unstable, my service is broken"
+
+→ Invoke SystematicDebugging skill
+→ OBSERVE: What changed in the update?
+→ Check: nix store diff-closures
+→ Find: Service package updated from 2.1 to 2.2
+→ OBSERVE: Check service logs
+→ Error: "Unknown configuration option: legacy_mode"
+→ HYPOTHESIS: Config option removed in v2.2
+→ TEST: Check v2.2 changelog
+→ Confirmed: Option removed, replaced with new_mode
+→ FIX: Update NixOS config to use new_mode
+→ TEST: nixos-rebuild build
+→ TEST: nixos-rebuild switch
+→ VERIFY: Service starts successfully
+→ Document: Add note about migration in comments
+```
+
+**Example 4: Memory leak investigation**
+```
+User: "Service memory usage keeps growing until it crashes"
+
+→ Invoke SystematicDebugging skill
+→ OBSERVE: Monitor memory over time
+→ OBSERVE: Check for goroutine leaks (if Go)
+→ Find: Goroutines increasing steadily
+→ HYPOTHESIS: Goroutines not being cleaned up
+→ TEST: Add pprof profiling
+→ Analyze goroutine stack traces
+→ Find: WebSocket connections not closing properly
+→ HYPOTHESIS: Missing context cancellation
+→ TEST: Add context with timeout to WebSocket handler
+→ TEST: Monitor goroutine count
+→ VERIFY: Goroutines stable, memory stable
+→ FIX: Update WebSocket handler
+→ Add test: Verify connections close on timeout
+→ Add metrics: Track active WebSocket connections
+```
+
+**Example 5: Performance degradation**
+```
+User: "Queries are getting slower over time"
+
+→ Invoke SystematicDebugging skill
+→ OBSERVE: Measure current query performance
+→ OBSERVE: Check database indices
+→ OBSERVE: Check table sizes
+→ Find: Large table with no index on commonly queried column
+→ HYPOTHESIS: Missing index causing table scans
+→ TEST: Analyze query execution plan
+→ Confirmed: Full table scan on 10M rows
+→ HYPOTHESIS: Adding index will improve performance
+→ TEST: Add index in development environment
+→ TEST: Measure query time improvement
+→ Result: Query time: 5s → 50ms
+→ FIX: Add index migration
+→ VERIFY: Performance in production
+→ Document: Add comment explaining index purpose
+```

@@ -0,0 +1,283 @@
+---
+name: TestDrivenDevelopment
+description: Disciplined TDD workflow enforcing red-green-refactor cycle and the "iron law" of no production code without failing tests first. USE WHEN user wants to write tests first OR implement new feature with TDD OR fix bugs with test coverage OR explicitly requests TDD approach. Enforces systematic test-first development with verification at each step.
+---
+
+# TestDrivenDevelopment
+
+Strict test-driven development workflow based on the red-green-refactor cycle.
+
+## The Iron Law
+
+**NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+This is non-negotiable. Even when tempted to "just quickly fix" something, you MUST:
+1. Write a failing test that demonstrates the need
+2. Verify the test actually fails
+3. Write minimal code to make it pass
+4. Verify the test passes
+5. Refactor if needed
+
+## The RED-GREEN-REFACTOR Cycle
+
+### RED: Write Failing Test
+
+1. Write test that describes desired behavior
+2. Test MUST fail initially (if it passes, something's wrong)
+3. Failure message should be clear and specific
+
+**Example (Go):**
+```go
+func TestCalculateDiscount_TenPercent(t *testing.T) {
+    order := Order{Subtotal: 100.0, DiscountRate: 0.10}
+    got := order.CalculateTotal()
+    want := 90.0
+    if got != want {
+        t.Errorf("CalculateTotal() = %v, want %v", got, want)
+    }
+}
+```
+
+### Verify RED
+
+1. Run test suite
+2. Confirm new test fails
+3. Confirm failure reason matches expectation
+4. **STOP if test doesn't fail** - investigate why
+
+```bash
+go test ./...
+# Expected: FAIL - undefined: Order.CalculateTotal
+```
+
+### GREEN: Minimal Implementation
+
+1. Write ONLY enough code to make test pass
+2. Don't over-engineer
+3. Don't add features not tested
+4. Prioritize working over elegant
+
+**Example:**
+```go
+func (o Order) CalculateTotal() float64 {
+    return o.Subtotal * (1 - o.DiscountRate)
+}
+```
+
+### Verify GREEN
+
+1. Run full test suite
+2. Confirm ALL tests pass
+3. **STOP if any test fails** - fix before refactoring
+
+```bash
+go test ./...
+# Expected: PASS
+```
+
+### REFACTOR
+
+1. Improve code structure
+2. Eliminate duplication
+3. Enhance readability
+4. **Run tests after each change**
+
+**Example refactor:**
+```go
+func (o Order) CalculateTotal() float64 {
+    return o.ApplyDiscount(o.Subtotal)
+}
+
+func (o Order) ApplyDiscount(amount float64) float64 {
+    return amount * (1 - o.DiscountRate)
+}
+```
+
+## Good vs Bad Tests
+
+### Good Test (Tests Behavior)
+```go
+func TestCalculateTotal_WithDiscount(t *testing.T) {
+    order := Order{Items: []Item{{Price: 100}}, Discount: 0.1}
+    got := order.CalculateTotal()
+    want := 90.0
+    if got != want {
+        t.Errorf("got %v, want %v", got, want)
+    }
+}
+```
+
+### Bad Test (Tests Implementation)
+```go
+func TestCalculateTotal_CallsDiscountFunc(t *testing.T) {
+    // Testing HOW instead of WHAT
+    // Brittle - breaks with refactoring
+    // Don't do this
+}
+```
+
+### Good Test Characteristics
+- Tests behavior, not implementation
+- Clear, descriptive name
+- Single responsibility
+- Independent (no shared state)
+- Fast execution
+- Deterministic
+
+## Red Flags
+
+**STOP immediately if you catch yourself:**
+
+- ❌ Writing production code before a failing test
+- ❌ Modifying production code while tests are failing
+- ❌ Skipping the "verify RED" step
+- ❌ Writing overly complex implementation for green phase
+- ❌ Refactoring with failing tests
+- ❌ Adding features not covered by tests
+
+**When you notice these, return to RED phase.**
+
+## TDD Workflow Checklist
+
+**For each feature/fix:**
+
+- [ ] Write failing test (RED)
+- [ ] Run test, verify it fails with expected error
+- [ ] Write minimal code to pass (GREEN)
+- [ ] Run all tests, verify they pass
+- [ ] Refactor if needed
+- [ ] Run all tests again
+- [ ] Commit with test and implementation together
+
+## Language-Specific Examples
+
+### Go
+```go
+// RED: Test first
+func TestParseConfig_ValidYAML(t *testing.T) {
+    yaml := "port: 8080\nhost: localhost"
+    config, err := ParseConfig([]byte(yaml))
+    if err != nil {
+        t.Fatalf("unexpected error: %v", err)
+    }
+    if config.Port != 8080 {
+        t.Errorf("Port = %d, want 8080", config.Port)
+    }
+}
+
+// GREEN: Minimal implementation
+func ParseConfig(data []byte) (*Config, error) {
+    var cfg Config
+    err := yaml.Unmarshal(data, &cfg)
+    return &cfg, err
+}
+```
+
+### Python
+```python
+# RED: Test first
+def test_calculate_discount_ten_percent():
+    order = Order(subtotal=100.0, discount_rate=0.10)
+    assert order.calculate_total() == 90.0
+
+# GREEN: Minimal implementation
+class Order:
+    def __init__(self, subtotal, discount_rate):
+        self.subtotal = subtotal
+        self.discount_rate = discount_rate
+
+    def calculate_total(self):
+        return self.subtotal * (1 - self.discount_rate)
+```
+
+### Rust
+```rust
+// RED: Test first
+#[test]
+fn test_calculate_total_with_discount() {
+    let order = Order {
+        subtotal: 100.0,
+        discount_rate: 0.10,
+    };
+    assert_eq!(order.calculate_total(), 90.0);
+}
+
+// GREEN: Minimal implementation
+impl Order {
+    fn calculate_total(&self) -> f64 {
+        self.subtotal * (1.0 - self.discount_rate)
+    }
+}
+```
+
+## When NOT to Use TDD
+
+TDD isn't always the right choice:
+
+- **Exploratory coding**: When you're not sure what you're building yet (use Brainstorming skill first)
+- **UI prototyping**: Visual design often needs iteration before solidifying behavior
+- **Performance optimization**: Sometimes you need to measure first, then optimize
+- **Glue code**: Simple wiring between components may not need tests
+
+**For these cases**: Build first, then add tests for the stable parts.
+
+## Integration with Other Skills
+
+- **Before TDD**: Use **Brainstorming** skill to clarify requirements
+- **During TDD**: Use **SystematicDebugging** if tests reveal unexpected behavior
+- **After TDD**: Use code review workflows to validate test coverage
+
+## Examples
+
+**Example 1: Adding new feature with TDD**
+```
+User: "Add a discount calculation feature"
+→ Invoke TestDrivenDevelopment skill
+→ RED: Write test for CalculateDiscount expecting 10% off
+→ Verify: Run test, fails with "undefined: CalculateDiscount"
+→ GREEN: Implement minimal CalculateDiscount function
+→ Verify: Run test, passes
+→ REFACTOR: Extract discount logic to separate method
+→ Verify: Run all tests, still pass
+→ Feature complete with test coverage
+```
+
+**Example 2: Fixing a bug with TDD**
+```
+User: "Fix the bug where negative prices crash the app"
+→ Invoke TestDrivenDevelopment skill
+→ RED: Write test with negative price expecting error or zero
+→ Verify: Run test, crashes (reproduces bug)
+→ GREEN: Add validation to reject negative prices
+→ Verify: Run test, passes
+→ REFACTOR: Improve error message
+→ Bug fixed with regression test preventing recurrence
+```
+
+**Example 3: User explicitly requests TDD**
+```
+User: "Let's use TDD to build the authentication system"
+→ Invoke TestDrivenDevelopment skill
+→ Guide through RED-GREEN-REFACTOR for each auth feature:
+  - User registration
+  - Login validation
+  - Token generation
+  - Token verification
+→ Each feature gets test first, then implementation
+→ Comprehensive test coverage from the start
+→ Confidence in authentication security
+```
+
+**Example 4: Complex algorithm development**
+```
+User: "Implement a binary search algorithm"
+→ Invoke TestDrivenDevelopment skill
+→ RED: Test with sorted array, search for existing element
+→ GREEN: Implement basic binary search
+→ RED: Test with element not in array
+→ GREEN: Handle not found case
+→ RED: Test with empty array
+→ GREEN: Handle edge case
+→ REFACTOR: Simplify logic
+→ Algorithm complete with edge case coverage
+```

@@ -0,0 +1,477 @@
+---
+name: UsingGitWorktrees
+description: Creates isolated git worktrees with smart directory selection and safety verification for parallel development. USE WHEN starting feature work that needs isolation from current workspace OR before executing implementation plans OR working on multiple branches simultaneously OR need clean test environment. Creates isolated workspaces sharing the same repository.
+---
+
+# UsingGitWorktrees
+
+Create isolated git workspaces for parallel development without switching branches.
+
+## Overview
+
+Git worktrees create isolated working directories that share the same repository, allowing:
+- Work on multiple branches simultaneously
+- Isolated test environments
+- Clean baseline for new features
+- No stashing or switching required
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation
+
+**Announce at start:** "I'm using the UsingGitWorktrees skill to set up an isolated workspace."
+
+## Why Use Git Worktrees?
+
+### Benefits
+
+✅ **Multiple branches active**: Work on feature branch while keeping main branch clean
+✅ **Isolated testing**: Each worktree has its own working directory and build artifacts
+✅ **No switching**: No need to stash changes or switch branches
+✅ **Clean baselines**: Start new work with verified clean state
+✅ **Parallel CI**: Run tests in multiple worktrees simultaneously
+
+### vs. Branch Switching
+
+| Aspect | Branch Switching | Git Worktrees |
+|--------|------------------|---------------|
+| Working directory | One (must switch) | Multiple (parallel) |
+| Uncommitted changes | Must stash | Keep in original worktree |
+| Dependencies | Reinstall on switch | Separate per worktree |
+| Build artifacts | Shared (conflicts) | Isolated |
+| Test runs | Sequential only | Parallel capable |
+
+## Directory Selection Process
+
+Follow this priority order:
+
+### 1. Check for Existing Worktree Directory
+
+```bash
+# Check in priority order
+if [ -d .worktrees ]; then
+    WORKTREE_DIR=".worktrees"
+elif [ -d worktrees ]; then
+    WORKTREE_DIR="worktrees"
+fi
+```
+
+**If found:** Use that directory (`.worktrees` takes priority over `worktrees`)
+
+### 2. Check CLAUDE.md for Preference
+
+```bash
+if [ -f CLAUDE.md ]; then
+    grep -i "worktree.*director" CLAUDE.md
+fi
+```
+
+**If preference specified:** Use it without asking user
+
+### 3. Ask User
+
+If no directory exists and no CLAUDE.md preference:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden, recommended)
+2. worktrees/ (project-local, visible)
+3. ~/worktrees/<project-name>/ (global location)
+
+Which would you prefer?
+```
+
+**Recommendation:** `.worktrees/` keeps project directory clean while remaining local
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify directory is git-ignored before creating worktree:**
+
+```bash
+# Check if directory is properly ignored
+if ! git check-ignore -q .worktrees && ! git check-ignore -q worktrees; then
+    echo "WARNING: Worktree directory is not ignored!"
+    # Must fix before proceeding
+fi
+```
+
+**Why critical:** Prevents accidentally committing worktree contents to repository
+
+**If NOT ignored - MUST fix immediately:**
+
+```bash
+# Add to .gitignore
+echo ".worktrees/" >> .gitignore
+# OR
+echo "worktrees/" >> .gitignore
+
+# Commit the change
+git add .gitignore
+git commit -m "chore: ignore git worktree directory"
+```
+
+### For Global Directory (~/worktrees)
+
+No .gitignore verification needed - outside project entirely
+
+## Worktree Creation Steps
+
+### Step 1: Detect Project Name
+
+```bash
+PROJECT=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### Step 2: Determine Branch Name
+
+```bash
+# Sanitize branch name for filesystem
+BRANCH_NAME="feature/user-authentication"
+BRANCH_PATH=$(echo "$BRANCH_NAME" | tr '/' '-')  # feature-user-authentication
+```
+
+### Step 3: Construct Worktree Path
+
+```bash
+case $WORKTREE_DIR in
+  .worktrees|worktrees)
+    WORKTREE_PATH="$WORKTREE_DIR/$BRANCH_PATH"
+    ;;
+  ~/worktrees/*)
+    WORKTREE_PATH="$HOME/worktrees/$PROJECT/$BRANCH_PATH"
+    ;;
+esac
+```
+
+### Step 4: Create Worktree with New Branch
+
+```bash
+# Create worktree and branch in one command
+git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"
+
+# Navigate to new worktree
+cd "$WORKTREE_PATH"
+```
+
+**Alternative - checkout existing branch:**
+```bash
+# If branch already exists
+git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"
+```
+
+### Step 5: Auto-Detect and Run Project Setup
+
+Detect project type and install dependencies:
+
+```bash
+# Node.js / JavaScript
+if [ -f package.json ]; then
+    npm install
+fi
+
+# Rust
+if [ -f Cargo.toml ]; then
+    cargo build
+fi
+
+# Python
+if [ -f requirements.txt ]; then
+    pip install -r requirements.txt
+fi
+
+if [ -f pyproject.toml ]; then
+    poetry install
+    # OR
+    pip install -e .
+fi
+
+# Go
+if [ -f go.mod ]; then
+    go mod download
+fi
+
+# NixOS (from home repository pattern)
+if [ -f flake.nix ]; then
+    nix develop --command bash -c "echo 'Development environment ready'"
+fi
+```
+
+### Step 6: Verify Clean Baseline
+
+Run tests to ensure worktree starts in working state:
+
+```bash
+# Node.js
+npm test
+
+# Rust
+cargo test
+
+# Python
+pytest
+
+# Go
+go test ./...
+
+# NixOS
+nix build
+# OR
+make build
+```
+
+**If tests fail:**
+- Report failures clearly
+- Ask whether to proceed or investigate
+- Document known issues
+
+**If tests pass:**
+- Report success
+- Show test count and duration
+- Confirm ready for work
+
+### Step 7: Report Worktree Ready
+
+```
+Worktree created successfully
+
+Location: /path/to/project/.worktrees/feature-user-authentication
+Branch: feature/user-authentication
+Tests: ✓ 47 passing (2.3s)
+
+Ready to implement user authentication feature
+```
+
+## Managing Worktrees
+
+### List All Worktrees
+
+```bash
+git worktree list
+```
+
+**Output:**
+```
+/path/to/project        abc1234 [main]
+/path/to/.worktrees/feature-auth  def5678 [feature/user-authentication]
+/path/to/.worktrees/bugfix-db     ghi9012 [bugfix/database-connection]
+```
+
+### Remove Worktree
+
+```bash
+# Remove worktree (keeps branch)
+git worktree remove .worktrees/feature-auth
+
+# Force remove (even with uncommitted changes)
+git worktree remove --force .worktrees/feature-auth
+```
+
+### Prune Deleted Worktrees
+
+```bash
+# Clean up references to manually deleted worktrees
+git worktree prune
+```
+
+### Move to Different Worktree
+
+```bash
+# Just cd to it - no branch switching needed
+cd .worktrees/feature-auth
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` (takes priority) |
+| Neither exists | Check CLAUDE.md → Ask user |
+| Directory not ignored | Add to `.gitignore` + commit immediately |
+| Tests fail during setup | Report failures + ask user |
+| No package.json/Cargo.toml | Skip dependency install |
+| Worktree no longer needed | `git worktree remove <path>` |
+| Manual deletion cleanup | `git worktree prune` |
+
+## Common Patterns for Your Home Repository
+
+Based on your NixOS home repository structure:
+
+### Building a NixOS Configuration
+
+```bash
+# Create worktree for system change
+git worktree add .worktrees/sakhalin-upgrade -b feature/sakhalin-upgrade
+
+cd .worktrees/sakhalin-upgrade
+
+# Build without switching main worktree
+make host/sakhalin/build
+
+# If successful, deploy
+make host/sakhalin/switch
+```
+
+### Working on Multiple Hosts
+
+```bash
+# Multiple worktrees for different hosts
+git worktree add .worktrees/rhea-config -b feature/rhea-jellyfin
+git worktree add .worktrees/aion-config -b feature/aion-audio
+
+# Work on both simultaneously
+cd .worktrees/rhea-config
+make host/rhea/build
+
+cd ../aion-config
+make host/aion/build
+```
+
+### Testing Flake Changes
+
+```bash
+# Isolated worktree for flake updates
+git worktree add .worktrees/flake-update -b chore/flake-update
+
+cd .worktrees/flake-update
+
+# Update and test
+nix flake update
+make dry-build
+
+# If successful, merge to main
+```
+
+## Common Mistakes
+
+### ❌ Skipping Ignore Verification
+
+**Problem:** Worktree contents get tracked, pollute `git status` in main worktree
+**Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### ❌ Assuming Directory Location
+
+**Problem:** Creates inconsistency, violates project conventions
+**Fix:** Follow priority: existing → CLAUDE.md → ask user
+
+### ❌ Proceeding with Failing Tests
+
+**Problem:** Can't distinguish new bugs from pre-existing issues
+**Fix:** Report failures, get explicit permission to proceed
+
+### ❌ Hardcoding Setup Commands
+
+**Problem:** Breaks on projects using different tools
+**Fix:** Auto-detect from project files (package.json, Cargo.toml, etc.)
+
+### ❌ Forgetting to Remove Old Worktrees
+
+**Problem:** Disk space waste, confusion about active work
+**Fix:** Regularly run `git worktree list` and remove completed work
+
+### ❌ Committing from Wrong Worktree
+
+**Problem:** Changes go to wrong branch
+**Fix:** Always verify current branch before committing: `git branch --show-current`
+
+## Integration with Other Skills
+
+**Before UsingGitWorktrees:**
+- Use **Brainstorming** to clarify what feature needs isolation
+- Ensure design is validated before creating worktree
+
+**After UsingGitWorktrees:**
+- Use **WritingPlans** to create implementation plan
+- Use **TestDrivenDevelopment** for implementation in worktree
+- Use **Git** skill for branching and commit workflows
+
+**Cleanup after work:**
+```bash
+# Merge work back to main
+git checkout main
+git merge feature/user-authentication
+
+# Remove worktree
+git worktree remove .worktrees/feature-user-authentication
+
+# Delete branch if done
+git branch -d feature/user-authentication
+```
+
+## Examples
+
+**Example 1: Feature development in isolation**
+```
+User: "Set up isolated workspace for authentication feature"
+
+→ Invoke UsingGitWorktrees skill
+→ Announce: "I'm using the UsingGitWorktrees skill to set up an isolated workspace"
+→ Check for existing worktree directory
+→ Find: .worktrees/ exists
+→ Verify: git check-ignore confirms .worktrees/ is ignored
+→ Create: git worktree add .worktrees/feature-auth -b feature/user-authentication
+→ Setup: npm install
+→ Test: npm test → 47 passing
+→ Report: "Worktree ready at /path/to/project/.worktrees/feature-auth"
+→ Ready for implementation
+```
+
+**Example 2: Parallel host configurations**
+```
+User: "I need to work on both rhea and aion configurations simultaneously"
+
+→ Invoke UsingGitWorktrees skill
+→ Create worktree for rhea: .worktrees/rhea-jellyfin
+→ Create worktree for aion: .worktrees/aion-audio
+→ Both worktrees have clean baselines
+→ Can build and test both in parallel
+→ Switch between with cd, no branch switching needed
+```
+
+**Example 3: First-time setup with no worktree directory**
+```
+User: "Create worktree for database migration"
+
+→ Invoke UsingGitWorktrees skill
+→ Check: No .worktrees/ or worktrees/ directory exists
+→ Check: No CLAUDE.md preference
+→ Ask user: "Where should I create worktrees?"
+→ User selects: .worktrees/ (hidden)
+→ Verify: Not in .gitignore
+→ Fix: Add .worktrees/ to .gitignore
+→ Commit: "chore: ignore git worktree directory"
+→ Create: git worktree add .worktrees/db-migration -b feature/db-migration
+→ Setup and verify
+→ Ready for work
+```
+
+**Example 4: Cleanup after merge**
+```
+User: "Clean up the authentication worktree now that it's merged"
+
+→ Navigate to main worktree
+→ Verify feature branch merged: git branch --merged
+→ Remove worktree: git worktree remove .worktrees/feature-auth
+→ Delete branch: git branch -d feature/user-authentication
+→ Confirm: git worktree list shows worktree removed
+```
+
+## Red Flags
+
+**Never:**
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without explicit permission
+- Assume directory location when ambiguous
+- Leave old worktrees around indefinitely
+- Commit to wrong branch (verify with `git branch --show-current`)
+
+**Always:**
+- Follow directory priority: existing → CLAUDE.md → ask
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+- Report clear status when worktree is ready
+- Clean up worktrees when work is merged

@@ -0,0 +1,495 @@
+---
+name: WritingPlans
+description: Creates comprehensive implementation plans with bite-sized tasks before touching code. USE WHEN user wants detailed implementation plan OR has spec/requirements for multi-step task OR needs to break down complex feature OR before starting significant coding work. Documents file paths, code examples, testing, and verification steps assuming engineer has minimal codebase context.
+---
+
+# WritingPlans
+
+Write comprehensive implementation plans that break complex features into bite-sized, testable tasks.
+
+## Overview
+
+Create detailed implementation plans that:
+- Break work into 2-5 minute tasks
+- Specify exact file paths and line numbers
+- Include complete code examples (not just descriptions)
+- Provide test commands with expected output
+- Follow DRY, YAGNI, TDD, and frequent commits
+- Assume engineer is skilled but unfamiliar with codebase
+
+**Announce at start:** "I'm using the WritingPlans skill to create a detailed implementation plan."
+
+## Principles
+
+### DRY (Don't Repeat Yourself)
+- Avoid duplicating code across the codebase
+- Extract common logic into reusable functions
+- Use existing utilities and patterns
+
+### YAGNI (You Aren't Gonna Need It)
+- Only implement what's required for current use case
+- Don't add features "just in case"
+- Can always add more later
+
+### TDD (Test-Driven Development)
+- Write tests before implementation
+- Verify tests fail first
+- Write minimal code to pass tests
+- Integrate with **TestDrivenDevelopment** skill
+
+### Frequent Commits
+- Commit after each completed task
+- Small, focused commits
+- Clear commit messages
+
+## Bite-Sized Task Granularity
+
+Each step is ONE action taking 2-5 minutes:
+
+**Example task breakdown:**
+1. Write the failing test ← step
+2. Run it to verify it fails ← step
+3. Implement minimal code to pass ← step
+4. Run tests to verify they pass ← step
+5. Commit the changes ← step
+
+**Not this:**
+1. "Implement user authentication" ← Too large
+2. "Add tests and implementation" ← Multiple actions
+
+## Plan Document Structure
+
+### Header Template
+
+Every plan MUST start with this header:
+
+```markdown
+# [Feature Name] Implementation Plan
+
+**Status**: Draft | In Progress | Complete
+**Created**: YYYY-MM-DD
+**Goal**: [One sentence describing what this builds]
+**Architecture**: [2-3 sentences about approach and key decisions]
+**Tech Stack**: [Key technologies, libraries, tools used]
+
+## Prerequisites
+
+- [ ] [Any setup needed before starting]
+- [ ] [Dependencies to install]
+- [ ] [Documentation to review]
+
+---
+```
+
+### Task Template
+
+```markdown
+### Task N: [Specific Component/Feature Name]
+
+**Purpose**: [Why this task exists, what it accomplishes]
+
+**Files:**
+- Create: `exact/path/to/newfile.go`
+- Modify: `exact/path/to/existing.go:123-145` (specify line ranges)
+- Test: `tests/exact/path/to/test_file.go`
+- Reference: `path/to/reference/pattern.go` (example to follow)
+
+**Dependencies**: [What must be completed before this task]
+
+---
+
+#### Step 1: Write the failing test
+
+```language
+// Complete code, not pseudocode
+func TestSpecificBehavior(t *testing.T) {
+    input := "test input"
+    result := FunctionUnderTest(input)
+    expected := "expected output"
+    if result != expected {
+        t.Errorf("got %v, want %v", result, expected)
+    }
+}
+```
+
+**Why this test**: [Explain what behavior it verifies]
+
+---
+
+#### Step 2: Run test to verify it fails
+
+**Command:**
+```bash
+go test ./path/to/package -v -run TestSpecificBehavior
+```
+
+**Expected output:**
+```
+FAIL: TestSpecificBehavior
+    undefined: FunctionUnderTest
+```
+
+**If different**: [Troubleshooting guidance]
+
+---
+
+#### Step 3: Write minimal implementation
+
+```language
+// Complete implementation, not "add code here"
+func FunctionUnderTest(input string) string {
+    // Minimal code to pass test
+    return "expected output"
+}
+```
+
+**Implementation notes**: [Explain key decisions]
+
+---
+
+#### Step 4: Run test to verify it passes
+
+**Command:**
+```bash
+go test ./path/to/package -v -run TestSpecificBehavior
+```
+
+**Expected output:**
+```
+PASS: TestSpecificBehavior (0.00s)
+```
+
+---
+
+#### Step 5: Refactor (if needed)
+
+**Optional improvements:**
+- Extract common logic
+- Improve naming
+- Add documentation
+
+**Run tests after each refactor**
+
+---
+
+#### Step 6: Commit
+
+```bash
+git add tests/path/to/test_file.go path/to/newfile.go
+git commit -m "feat: add specific feature
+
+- Add FunctionUnderTest with test
+- Handles [specific case]"
+```
+
+**Commit message format**: Follow repository conventions
+
+---
+```
+
+## Complete Example
+
+```markdown
+# User Authentication Implementation Plan
+
+**Status**: Draft
+**Created**: 2025-12-25
+**Goal**: Add JWT-based authentication to API endpoints
+**Architecture**: Middleware-based auth using JWT tokens with refresh token rotation. Secrets stored via agenix.
+**Tech Stack**: Go 1.21, golang-jwt/jwt/v5, agenix for secrets
+
+## Prerequisites
+
+- [ ] Review existing middleware patterns in `services/common/middleware/`
+- [ ] Read JWT token structure in `docs/auth.md`
+- [ ] Ensure agenix secret for JWT signing key exists
+
+---
+
+### Task 1: JWT Token Generation
+
+**Purpose**: Create function to generate access and refresh tokens
+
+**Files:**
+- Create: `services/auth/jwt.go`
+- Test: `services/auth/jwt_test.go`
+- Reference: `services/common/crypto/signing.go` (signing pattern)
+
+**Dependencies**: None
+
+---
+
+#### Step 1: Write the failing test
+
+```go
+package auth
+
+import (
+    "testing"
+    "time"
+)
+
+func TestGenerateTokenPair_ValidUser(t *testing.T) {
+    userID := "user-123"
+    tokens, err := GenerateTokenPair(userID)
+
+    if err != nil {
+        t.Fatalf("unexpected error: %v", err)
+    }
+
+    if tokens.AccessToken == "" {
+        t.Error("access token is empty")
+    }
+
+    if tokens.RefreshToken == "" {
+        t.Error("refresh token is empty")
+    }
+
+    if tokens.ExpiresIn <= 0 {
+        t.Error("expiration time is invalid")
+    }
+}
+```
+
+**Why this test**: Verifies token pair generation for authenticated user
+
+---
+
+#### Step 2: Run test to verify it fails
+
+**Command:**
+```bash
+go test ./services/auth -v -run TestGenerateTokenPair_ValidUser
+```
+
+**Expected output:**
+```
+FAIL: TestGenerateTokenPair_ValidUser
+    undefined: GenerateTokenPair
+```
+
+---
+
+#### Step 3: Write minimal implementation
+
+```go
+package auth
+
+import (
+    "time"
+
+    "github.com/golang-jwt/jwt/v5"
+)
+
+type TokenPair struct {
+    AccessToken  string
+    RefreshToken string
+    ExpiresIn    int64
+}
+
+func GenerateTokenPair(userID string) (*TokenPair, error) {
+    // TODO: Load secret from agenix in future task
+    secret := []byte("temp-secret-for-testing")
+
+    // Access token (15 minutes)
+    accessClaims := jwt.MapClaims{
+        "sub": userID,
+        "exp": time.Now().Add(15 * time.Minute).Unix(),
+    }
+    accessToken := jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims)
+    accessStr, err := accessToken.SignedString(secret)
+    if err != nil {
+        return nil, err
+    }
+
+    // Refresh token (7 days)
+    refreshClaims := jwt.MapClaims{
+        "sub": userID,
+        "exp": time.Now().Add(7 * 24 * time.Hour).Unix(),
+    }
+    refreshToken := jwt.NewWithClaims(jwt.SigningMethodHS256, refreshClaims)
+    refreshStr, err := refreshToken.SignedString(secret)
+    if err != nil {
+        return nil, err
+    }
+
+    return &TokenPair{
+        AccessToken:  accessStr,
+        RefreshToken: refreshStr,
+        ExpiresIn:    900, // 15 minutes in seconds
+    }, nil
+}
+```
+
+**Implementation notes**: Using temporary secret for testing; will integrate agenix in subsequent task
+
+---
+
+#### Step 4: Run test to verify it passes
+
+**Command:**
+```bash
+go test ./services/auth -v -run TestGenerateTokenPair_ValidUser
+```
+
+**Expected output:**
+```
+PASS: TestGenerateTokenPair_ValidUser (0.01s)
+```
+
+---
+
+#### Step 5: Commit
+
+```bash
+git add services/auth/jwt.go services/auth/jwt_test.go
+git commit -m "feat: add JWT token pair generation
+
+- Generate access token (15 min expiry)
+- Generate refresh token (7 day expiry)
+- Using temporary secret (agenix integration pending)"
+```
+
+---
+
+### Task 2: Agenix Secret Integration
+
+[Continue with next task...]
+
+---
+```
+
+## Plan Storage Location
+
+**Save all plans to:**
+```bash
+docs/plans/YYYY-MM-DD-<feature-name>.md
+```
+
+**Example:**
+```bash
+docs/plans/2025-12-25-jwt-authentication.md
+```
+
+**After writing plan:**
+```bash
+git add docs/plans/2025-12-25-jwt-authentication.md
+git commit -m "docs: add JWT authentication implementation plan"
+```
+
+## What to Include in Plans
+
+### ✅ Do Include
+
+- **Exact file paths** with line numbers for modifications
+- **Complete code** in examples (not "add validation here")
+- **Exact commands** to run with expected output
+- **Why decisions were made** (architecture choices)
+- **References** to existing patterns in codebase
+- **Verification steps** for each task
+- **Troubleshooting** guidance for common issues
+- **Dependencies** between tasks
+
+### ❌ Don't Include
+
+- Vague instructions like "add error handling"
+- Pseudocode or incomplete examples
+- Assumptions about what engineer knows
+- Commands without expected output
+- Tasks larger than 5 minutes
+- Implementation details without tests
+
+## Integration with Other Skills
+
+**Before WritingPlans:**
+- Use **Brainstorming** skill to clarify design and requirements
+- Ensure architecture decisions are made
+- Identify all components needed
+
+**While WritingPlans:**
+- Reference **TestDrivenDevelopment** for test-first approach
+- Check existing code patterns with **Grep** and **Read**
+- Reference **CORE** principles for technology choices
+
+**After WritingPlans:**
+- Plan is ready for implementation
+- Can be executed task-by-task
+- Each task should take 2-5 minutes
+- Progress can be tracked with **TodoWrite**
+
+## Examples
+
+**Example 1: Feature implementation plan**
+```
+User: "I need a detailed plan for adding caching to the API"
+
+→ Invoke WritingPlans skill
+→ Announce: "I'm using the WritingPlans skill to create a detailed implementation plan"
+→ Review existing API structure
+→ Check for caching patterns in codebase
+→ Break down into tasks:
+  1. Add cache configuration
+  2. Implement cache middleware
+  3. Add cache key generation
+  4. Implement cache invalidation
+  5. Add metrics for cache hits/misses
+→ Write complete plan with code examples
+→ Save to docs/plans/2025-12-25-api-caching.md
+→ Commit plan document
+→ Ready for implementation
+```
+
+**Example 2: Bug fix with test coverage**
+```
+User: "Create a plan to fix the authentication bug and add comprehensive tests"
+
+→ Invoke WritingPlans skill
+→ Review bug report and reproduction steps
+→ Identify root cause
+→ Break down into tasks:
+  1. Write test reproducing bug
+  2. Verify test fails
+  3. Fix bug with minimal change
+  4. Add edge case tests
+  5. Add integration tests
+→ Write plan with exact code and commands
+→ Save to docs/plans/2025-12-25-auth-bug-fix.md
+→ Ready for systematic implementation
+```
+
+**Example 3: Refactoring plan**
+```
+User: "Plan out refactoring the database layer to use a repository pattern"
+
+→ Invoke WritingPlans skill
+→ Analyze current database usage
+→ Design repository interfaces
+→ Break down into tasks:
+  1. Define repository interfaces
+  2. Implement user repository
+  3. Migrate user service to use repository
+  4. Add repository tests
+  5. Repeat for each entity
+→ Each task includes before/after code
+→ Includes migration strategy (incremental)
+→ Save plan with 20+ small tasks
+→ Can be implemented incrementally
+```
+
+## Common Pitfalls
+
+**Don't:**
+- Write plans with vague tasks
+- Skip exact file paths
+- Provide incomplete code examples
+- Forget test verification steps
+- Make tasks too large (>5 minutes)
+- Assume engineer knows codebase patterns
+
+**Do:**
+- Break work into bite-sized pieces
+- Include complete, runnable code
+- Specify expected output for commands
+- Reference existing patterns
+- Follow repository conventions
+- Make each task independently committable