ai-playbook 1.0.0

package/prompts/architect/design-system.md

@@ -0,0 +1,140 @@
+# Design System Prompt
+
+**Role:** Architect  
+**Type:** System Design  
+**Context Needed:** Requirements, constraints, existing architecture, scale requirements
+
+## Template
+
+```
+Design [system name] with these requirements:
+
+## Problem Statement
+[What problem are we solving]
+
+## Requirements
+### Functional
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+### Non-functional
+- Scale: [Users/requests/data volume]
+- Performance: [Target latency, throughput]
+- Availability: [Uptime, regions]
+- Consistency: [Strong/eventual]
+
+## Constraints
+- Technology: [Required/forbidden]
+- Budget: [Cost constraints]
+- Timeline: [When needed]
+- Team: [Expertise, size]
+
+## Existing Architecture
+[Diagram or description of current system]
+
+## Questions to Answer
+1. [Key design decision]
+2. [Key design decision]
+3. [Key design decision]
+
+## Expected Deliverables
+- System architecture diagram
+- Component descriptions
+- Data flow diagram
+- Technology recommendations
+- Scalability analysis
+- Risk assessment
+- Migration plan (if applicable)
+```
+
+## When to Use
+
+- Designing new systems
+- Major architecture changes
+- Scalability improvements
+- System redesigns
+- Migration planning
+
+## Required Context
+
+- Business requirements
+- Current state architecture
+- Scale expectations
+- Constraints (budget, time, tech)
+- Team expertise
+- Growth projections
+
+## Expected Output
+
+- ✓ Architecture diagram
+- ✓ Component descriptions
+- ✓ Data flows
+- ✓ Technology choices justified
+- ✓ Scalability plan
+- ✓ Risk mitigation
+
+## Quality Gates
+
+```
+Completeness:
+  ✓ All requirements addressed
+  ✓ Constraints considered
+  ✓ Trade-offs explained
+
+Feasibility:
+  ✓ Team can build it
+  ✓ Timeline realistic
+  ✓ Budget reasonable
+
+Scalability:
+  ✓ Handles growth
+  ✓ Performance meets targets
+  ✓ No hard limits
+```
+
+## Example Usage
+
+```
+Design real-time notification system for 10M users
+
+## Problem Statement
+Send notifications to millions of users with <1s latency
+
+## Requirements
+### Functional
+- Support multiple notification types (email, SMS, push)
+- Target users based on preferences
+- Track delivery status
+- Support scheduling
+
+### Non-functional
+- Scale to 10M users
+- <1s delivery latency (p99)
+- 99.9% availability
+- Eventual consistency acceptable
+
+## Constraints
+- $50k/month budget
+- Team of 3 engineers
+- Existing PostgreSQL database
+- AWS infrastructure preferred
+
+## Existing Architecture
+[Current monolithic notification system, <100k users]
+
+## Questions to Answer
+1. Queue-based vs direct push?
+2. Single region or multi-region?
+3. How to handle backpressure?
+```
+
+## Tips
+
+- State clear requirements
+- List all constraints
+- Draw diagrams
+- Justify tech choices
+- Consider growth
+- Plan for failure
+- Think about operations

package/prompts/debugger/README.md

@@ -0,0 +1,96 @@
+# Debugger Prompts
+
+Reusable prompts for diagnosing and fixing issues.
+
+## Available Prompts
+
+### [diagnose-issue.md](diagnose-issue.md)
+
+**Use when:** Investigating production issues or debugging failures
+
+**Covers:**
+- Issue description
+- Reproduction steps
+- Error output and logs
+- Affected code
+- When it happens
+- Impact assessment
+
+**Good for:**
+- Production debugging
+- Test failures
+- Performance issues
+- Error investigation
+
+## Using Debug Prompts
+
+### Diagnosis Process
+
+1. **Describe issue** - What's happening?
+2. **Reproduction** - How to trigger it?
+3. **Gather logs** - Error messages, stack traces
+4. **Identify patterns** - When does it happen?
+5. **Hypothesize** - What could cause this?
+6. **Investigate** - Look for root cause
+7. **Fix** - Implement solution
+8. **Verify** - Confirm it's fixed
+
+## What Gets Delivered
+
+✓ Root cause identified  
+✓ Clear explanation  
+✓ Affected components mapped  
+✓ Fix proposal  
+✓ Verification plan  
+
+## Quality Gates
+
+Diagnosis must provide:
+
+✓ **Reproducibility** - Can be reproduced reliably  
+✓ **Root cause** - True cause identified  
+✓ **Evidence** - Backed by logs/data  
+✓ **Fix** - Solution that works  
+✓ **Verification** - How to confirm fixed  
+
+## Debug Checklist
+
+- [ ] Issue description clear
+- [ ] Reproduction steps documented
+- [ ] All logs gathered
+- [ ] Environment details noted
+- [ ] Recent changes identified
+- [ ] Root cause found
+- [ ] Fix is feasible
+- [ ] Can be verified
+- [ ] No side effects
+
+## Best Practices
+
+### Effective Debug Prompts
+
+- Be specific about symptoms
+- Include all error messages
+- Provide reproduction steps
+- List recent changes
+- Describe expected behavior
+- Note environment details
+- Provide logs/traces
+- Share context
+
+### Investigation Approach
+
+1. **Symptoms** - What do you observe?
+2. **Timeline** - When did it start?
+3. **Changes** - What changed recently?
+4. **Environment** - What's different?
+5. **Evidence** - What do logs show?
+6. **Hypothesis** - What could cause it?
+7. **Testing** - How to verify?
+8. **Fix** - What to change?
+
+## Related Documentation
+
+- See `../README.md` for overview
+- Check hooks/ for testing/validation
+- Review commands/ for debugging workflows

package/prompts/debugger/diagnose-issue.md

@@ -0,0 +1,141 @@
+# Diagnose Issue Prompt
+
+**Role:** Debugger  
+**Type:** Issue Diagnosis  
+**Context Needed:** Error logs, reproduction steps, environment details, affected code
+
+## Template
+
+```
+Diagnose [issue name]:
+
+## Issue Description
+[What's wrong]
+
+## Reproduction
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+Environment:
+- Node: [version]
+- OS: [OS]
+- Browser: [browser]
+- Time: [When it happens]
+
+## Error Output
+[Error message, stack trace, logs]
+
+## Affected Code
+File: [path]
+Line: [numbers]
+
+## When It Happens
+- Frequency: [Always/intermittent]
+- Recent changes: [What changed]
+- Only with: [Specific conditions]
+
+## Impact
+- Users affected: [Scope]
+- Severity: [Critical/High/Medium]
+- Business impact: [What breaks]
+
+## Expected Root Cause
+[Your theory if any]
+
+## Expected Deliverables
+- Root cause analysis
+- Affected components
+- Reproduction case
+- Fix proposal
+- Verification steps
+```
+
+## When to Use
+
+- Investigating production issues
+- Debugging failed tests
+- Analyzing error logs
+- Understanding why code fails
+- Performance issues
+
+## Required Context
+
+- Complete error message
+- Reproduction steps
+- Recent code changes
+- Environment details
+- System logs
+- Related code
+
+## Expected Output
+
+- ✓ Root cause identified
+- ✓ Clear explanation
+- ✓ Affected areas mapped
+- ✓ Fix proposal
+- ✓ Verification plan
+
+## Quality Gates
+
+```
+Analysis:
+  ✓ Root cause found
+  ✓ Well explained
+  ✓ Evidence provided
+
+Reproducibility:
+  ✓ Can be reproduced
+  ✓ Steps are clear
+  ✓ Conditions identified
+
+Solution:
+  ✓ Fix is feasible
+  ✓ No side effects
+  ✓ Can be verified
+```
+
+## Example Usage
+
+```
+Diagnose database connection timeouts in production
+
+## Issue Description
+API responses timeout at 10:00 PM every night
+
+## Reproduction
+Hard to reproduce locally, only happens in production
+
+Environment:
+- Node 18.12
+- PostgreSQL 14
+- AWS RDS Aurora
+- Production environment
+
+## Error Output
+timeout exceeded, ECONNREFUSED at socket.js:1025
+
+## Affected Code
+File: src/db/connection.ts
+Line: 45-60
+
+## When It Happens
+- Frequency: Nightly around 10:00 PM
+- Recent changes: None recently
+- Only with: Production database
+
+## Impact
+- Users affected: All users during window
+- Severity: Critical
+- Business impact: API unavailable for ~5 minutes
+```
+
+## Tips
+
+- Gather all logs available
+- Look at timing patterns
+- Check recent changes
+- Verify reproduction steps
+- Consider environment differences
+- Think about side effects
+- Look for cascading failures

package/prompts/developer/README.md

@@ -0,0 +1,129 @@
+# Developer Prompts
+
+Reusable prompts for software development tasks.
+
+## Available Prompts
+
+### [implement-feature.md](implement-feature.md)
+
+**Use when:** Implementing new features or adding functionality
+
+**Covers:**
+- Feature specification
+- Constraints and patterns
+- Files to modify/create
+- Expected output
+- Quality gates
+
+**Template structure:**
+- Feature spec
+- Constraints
+- Files to modify
+- Expected output
+- Verification steps
+
+**Good for:**
+- New API endpoints
+- UI components
+- Services/utilities
+- Feature completeness
+
+### [fix-bug.md](fix-bug.md)
+
+**Use when:** Fixing bugs or resolving issues
+
+**Covers:**
+- Bug description
+- Reproduction steps
+- Root cause
+- Expected fix
+- Testing approach
+
+**Template structure:**
+- Bug description
+- Reproduction steps
+- Error information
+- Root cause (if known)
+- Expected fix
+- Testing plan
+
+**Good for:**
+- Production bugs
+- Test failures
+- Regressions
+- Performance issues
+
+## Using These Prompts
+
+### Basic Usage
+
+Copy the template from the relevant prompt and fill in:
+
+1. **Understand the prompt** - Read the template structure
+2. **Gather context** - Collect all needed information
+3. **Fill in template** - Complete each section
+4. **Provide to Claude** - Paste filled template
+5. **Review output** - Check against quality gates
+
+### Example
+
+```markdown
+Implement user profile update feature with these requirements:
+
+## Feature Spec
+- Users can edit name, email, avatar
+- Changes saved to database
+- Confirmation email sent
+- Duplicate emails rejected
+
+## Constraints
+- Follow existing middleware patterns
+- Use current auth system
+- Support file upload max 5MB
+- No breaking changes
+
+[... rest of template filled in ...]
+```
+
+## Quality Gates
+
+All developer prompts should include:
+
+✓ **Correctness** - Code works as intended  
+✓ **Testing** - 80%+ coverage  
+✓ **Quality** - Follows patterns  
+✓ **Performance** - No regressions  
+✓ **Documentation** - Clear code  
+
+## Best Practices
+
+### Writing Effective Prompts
+
+1. **Be specific** - "Add login" vs "Implement JWT-based login with refresh tokens"
+2. **Include constraints** - Tech stack, patterns, limitations
+3. **List files** - What needs to change
+4. **Define success** - Quality gates, test cases
+5. **Provide context** - Link to related code/specs
+
+### Gathering Context
+
+- Read relevant architecture docs
+- Check existing patterns in codebase
+- Review related features
+- Understand constraints
+- Define acceptance criteria
+
+### Iterating on Output
+
+1. Review initial output against quality gates
+2. Ask for clarifications
+3. Request refinements
+4. Verify against test cases
+5. Merge when ready
+
+## Related Documentation
+
+- See `../README.md` for overview
+- Check agents/ for available AI agents
+- Review hooks/ for automation
+- Explore commands/ for development workflows

package/prompts/developer/fix-bug.md

@@ -0,0 +1,136 @@
+# Fix Bug Prompt
+
+**Role:** Developer  
+**Type:** Bug Fix  
+**Context Needed:** Bug description, reproduction steps, error logs, affected code
+
+## Template
+
+```
+Fix [bug name] with these details:
+
+## Bug Description
+[What is the issue]
+
+## Reproduction Steps
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+Expected: [What should happen]
+Actual: [What happens instead]
+
+## Error Information
+[Error message, stack trace, logs]
+
+## Affected Code
+File: [file path]
+Line: [line numbers]
+[Code snippet if helpful]
+
+## Root Cause (if known)
+[What's causing the issue]
+
+## Expected Fix
+[How should it behave after fix]
+
+## Testing
+- Test case: [What to test]
+- Verification: [How to verify it's fixed]
+- Regression risk: [What could break]
+
+## Quality Gates
+✓ Fix does not break existing tests
+✓ New test covers the bug
+✓ Code follows patterns
+✓ Performance not degraded
+```
+
+## When to Use
+
+- Fixing reported bugs
+- Addressing test failures
+- Resolving production issues
+- Fixing regressions
+
+## Required Context
+
+- Bug description/title
+- Reproduction steps
+- Error logs/stack trace
+- Expected vs actual behavior
+- Affected code location
+- User impact assessment
+
+## Expected Output
+
+- ✓ Root cause identified
+- ✓ Bug is fixed
+- ✓ New test prevents regression
+- ✓ No test breakage
+- ✓ Code follows patterns
+
+## Quality Gates
+
+```
+Verification:
+  ✓ Can reproduce bug
+  ✓ Fix resolves issue
+  ✓ Error is gone
+  ✓ Behavior matches expected
+
+Testing:
+  ✓ New test fails without fix
+  ✓ New test passes with fix
+  ✓ All existing tests pass
+  ✓ No regressions
+
+Code Quality:
+  ✓ Minimal changes
+  ✓ Follows patterns
+  ✓ No new issues
+  ✓ Clear logic
+```
+
+## Example Usage
+
+```
+Fix payment processing timeout issue
+
+## Bug Description
+Payments timeout after 5 seconds, failing even for valid cards
+
+## Reproduction Steps
+1. Go to checkout
+2. Add test card
+3. Click "Process Payment"
+4. Wait > 5 seconds
+5. Timeout error appears
+
+Expected: Payment processes (usually < 3 seconds)
+Actual: Always times out after 5 seconds
+
+## Affected Code
+File: src/services/payment.ts
+Line: 45-60
+Methods: processPayment(), callGateway()
+
+## Root Cause
+Payment gateway timeout set to 5 seconds but API calls average 4+ seconds
+
+## Expected Fix
+Increase timeout to 10 seconds with proper error handling
+
+## Testing
+Test case: Payment with slow network
+Verification: Payment completes within 10 seconds
+Regression risk: Timeouts on truly broken connections
+```
+
+## Tips
+
+- Include all reproduction details
+- Show error messages exactly
+- Provide test cases
+- State expected behavior clearly
+- Consider edge cases
+- Think about similar issues