@sylix/coworker 2.0.11 → 2.0.12

package/dist/skills/defaults/debugging/systematic-debugging.md

@@ -0,0 +1,249 @@
+---
+name: debugging
+description: Apply systematic debugging methodology to find and fix bugs efficiently.
+---
+
+# Systematic Debugging — CoWorker Edition
+
+Find bugs faster with a proven process.
+
+## When to Use This Skill
+
+- Any bug or issue
+- Test failures
+- Unexpected behavior
+- Performance problems
+
+## The Four-Phase Process
+
+### Phase 1: Root Cause Investigation
+
+**NEVER propose a fix without understanding the cause.**
+
+1. **Read error messages carefully**
+   - Note line numbers, file paths, error codes
+   - Use `executeRead` to examine failing code
+
+2. **Reproduce consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+
+3. **Check recent changes**
+   ```bash
+   git log --oneline -10
+   git diff HEAD~3
+   ```
+
+4. **Trace data flow backward**
+   - What code causes the error?
+   - What called that code?
+   - What value was passed?
+
+```python
+# Example: Trace back to find root cause
+# Error: Cannot read property 'name' of undefined
+# Location: user.profile.name
+
+# Step 1: Find where profile is set
+grep -r "user.profile" --include="*.js"
+
+# Step 2: Check if profile is always populated
+# In userService.js line 42:
+user.profile = await fetchProfile(user.id)
+# But what if fetchProfile returns null?
+
+# Step 3: Check fetchProfile
+async function fetchProfile(userId) {
+  const profile = await db.query(
+    'SELECT * FROM profiles WHERE user_id = ?', 
+    userId
+  );
+  return profile[0];  # Returns undefined if no profile!
+}
+
+# ROOT CAUSE: fetchProfile returns undefined for new users
+# FIX: Create profile if not exists, OR handle undefined
+```
+
+### Phase 2: Pattern Analysis
+
+1. **Find working examples**
+   - Search for similar code that works
+   - Compare implementations
+
+2. **Identify differences**
+   ```python
+   # Working:
+   def get_user(id: str) -> User:
+       return db.query("SELECT * FROM users WHERE id = ?", id).first()
+   
+   # Broken:
+   def get_order(id: str) -> Order:
+       return db.query("SELECT * FROM orders WHERE id = ?", id).first()
+   
+   # Difference: get_order returns None vs raising error
+   ```
+
+### Phase 3: Hypothesis & Testing
+
+1. **Form hypothesis**
+   ```
+   I think X is causing Y because Z
+   ```
+
+2. **Test minimally**
+   - Smallest possible change
+   - One variable at a time
+
+```python
+# Hypothesis: Missing database index causes slow query
+# Test: Add index, measure query time
+
+# Before
+await db.execute(
+    "SELECT * FROM orders WHERE user_id = ? AND status = ?",
+    user_id, "pending"
+)
+
+# Test with EXPLAIN
+EXPLAIN QUERY PLAN SELECT * FROM orders WHERE user_id = 1 AND status = 'pending'
+
+# Add index
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+```
+
+### Phase 4: Implementation
+
+1. **Create failing test first**
+   ```python
+   def test_order_get_by_user_pending():
+       orders = get_orders(user_id="123", status="pending")
+       assert len(orders) == 2
+       # This should fail before fix
+   ```
+
+2. **Implement fix**
+   - Address root cause
+   - One change at a time
+
+3. **Verify**
+   - Test passes
+   - No regressions
+
+## Tools & Techniques
+
+### Logging
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+def process_order(order_id):
+    logger.info(f"Processing order {order_id}")
+    
+    # Add debug points
+    logger.debug(f"Order data: {order_data}")
+    
+    try:
+        result = payment.charge(order_data)
+        logger.info(f"Payment successful: {result.id}")
+        return result
+    except Exception as e:
+        logger.error(f"Payment failed: {e}", exc_info=True)
+        raise
+```
+
+### Debugging with PDB
+
+```python
+import pdb; pdb.set_trace()
+
+# Common commands:
+# n = next line
+# s = step into function
+# c = continue
+# p variable = print variable
+# l = list code around
+# w = show call stack
+```
+
+### Interactive Debugging
+
+```typescript
+// VS Code debugger
+debugger;
+
+// Or browser DevTools
+console.log('User:', user);
+console.table(users);
+console.trace();
+```
+
+## Common Debugging Patterns
+
+### Null/Undefined
+
+```typescript
+// Problem
+const name = user.profile.name;  // TypeError
+
+// Solution with optional chaining
+const name = user?.profile?.name ?? 'Unknown';
+
+// Or explicit check
+if (user && user.profile) {
+  const name = user.profile.name;
+}
+```
+
+### Async Issues
+
+```javascript
+// Problem: Race condition
+await user.save();
+await sendEmail(user.email);  // Might run before save completes
+
+// Solution: Await properly
+await user.save();
+await sendEmail(user.email);
+
+// Or use transactions
+await db.transaction(async () => {
+  await user.save();
+  await sendEmail(user.email);
+});
+```
+
+### Memory Leaks
+
+```typescript
+// Problem: Event listener not cleaned up
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+}, []);
+
+// Solution: Clean up
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+  return () => {
+    window.removeEventListener('resize', handleResize);
+  };
+}, []);
+```
+
+## Red Flags
+
+Stop and return to Phase 1:
+
+- "Let me try changing X"
+- "Quick fix for now"
+- Proposing solutions before tracing
+- "One more attempt"
+
+## When to Escalate
+
+If you've tried 3+ fixes and they failed:
+- Architecture issue likely
+- Discuss with team
+- Consider pair debugging

package/dist/skills/defaults/devops/architecture-decision-records.md

@@ -0,0 +1,448 @@
+---
+name: architecture-decision-records
+description: Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
+---
+
+# Architecture Decision Records
+
+Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
+
+## When to Use This Skill
+
+- Making significant architectural decisions
+- Documenting technology choices
+- Recording design trade-offs
+- Onboarding new team members
+- Reviewing historical decisions
+- Establishing decision-making processes
+
+## Core Concepts
+
+### 1. What is an ADR?
+
+An Architecture Decision Record captures:
+
+- **Context**: Why we needed to make a decision
+- **Decision**: What we decided
+- **Consequences**: What happens as a result
+
+### 2. When to Write an ADR
+
+| Write ADR                  | Skip ADR               |
+| -------------------------- | ---------------------- |
+| New framework adoption     | Minor version upgrades |
+| Database technology choice | Bug fixes              |
+| API design patterns        | Implementation details |
+| Security architecture      | Routine maintenance    |
+| Integration patterns       | Configuration changes  |
+
+### 3. ADR Lifecycle
+
+```
+Proposed → Accepted → Deprecated → Superseded
+              ↓
+           Rejected
+```
+
+## Templates
+
+### Template 1: Standard ADR (MADR Format)
+
+```markdown
+# ADR-0001: Use PostgreSQL as Primary Database
+
+## Status
+
+Accepted
+
+## Context
+
+We need to select a primary database for our new e-commerce platform. The system
+will handle:
+
+- ~10,000 concurrent users
+- Complex product catalog with hierarchical categories
+- Transaction processing for orders and payments
+- Full-text search for products
+- Geospatial queries for store locator
+
+The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
+compliance for financial transactions.
+
+## Decision Drivers
+
+- **Must have ACID compliance** for payment processing
+- **Must support complex queries** for reporting
+- **Should support full-text search** to reduce infrastructure complexity
+- **Should have good JSON support** for flexible product attributes
+- **Team familiarity** reduces onboarding time
+
+## Considered Options
+
+### Option 1: PostgreSQL
+
+- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
+  search, PostGIS for geospatial, team has experience
+- **Cons**: Slightly more complex replication setup than MySQL
+
+### Option 2: MySQL
+
+- **Pros**: Very familiar to team, simple replication, large community
+- **Cons**: Weaker JSON support, no built-in full-text search (need
+  Elasticsearch), no geospatial without extensions
+
+### Option 3: MongoDB
+
+- **Pros**: Flexible schema, native JSON, horizontal scaling
+- **Cons**: No ACID for multi-document transactions (at decision time),
+  team has limited experience, requires schema design discipline
+
+## Decision
+
+We will use **PostgreSQL 15** as our primary database.
+
+## Rationale
+
+PostgreSQL provides the best balance of:
+
+1. **ACID compliance** essential for e-commerce transactions
+2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce
+   infrastructure complexity
+3. **Team familiarity** with SQL databases reduces learning curve
+4. **Mature ecosystem** with excellent tooling and community support
+
+The slight complexity in replication is outweighed by the reduction in
+additional services (no separate Elasticsearch needed).
+
+## Consequences
+
+### Positive
+
+- Single database handles transactions, search, and geospatial queries
+- Reduced operational complexity (fewer services to manage)
+- Strong consistency guarantees for financial data
+- Team can leverage existing SQL expertise
+
+### Negative
+
+- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
+- Vertical scaling limits may require read replicas sooner
+- Some team members need PostgreSQL-specific training
+
+### Risks
+
+- Full-text search may not scale as well as dedicated search engines
+- Mitigation: Design for potential Elasticsearch addition if needed
+
+## Implementation Notes
+
+- Use JSONB for flexible product attributes
+- Implement connection pooling with PgBouncer
+- Set up streaming replication for read replicas
+- Use pg_trgm extension for fuzzy search
+
+## Related Decisions
+
+- ADR-0002: Caching Strategy (Redis) - complements database choice
+- ADR-0005: Search Architecture - may supersede if Elasticsearch needed
+
+## References
+
+- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)
+- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
+- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`
+```
+
+### Template 2: Lightweight ADR
+
+```markdown
+# ADR-0012: Adopt TypeScript for Frontend Development
+
+**Status**: Accepted
+**Date**: 2024-01-15
+**Deciders**: @alice, @bob, @charlie
+
+## Context
+
+Our React codebase has grown to 50+ components with increasing bug reports
+related to prop type mismatches and undefined errors. PropTypes provide
+runtime-only checking.
+
+## Decision
+
+Adopt TypeScript for all new frontend code. Migrate existing code incrementally.
+
+## Consequences
+
+**Good**: Catch type errors at compile time, better IDE support, self-documenting
+code.
+
+**Bad**: Learning curve for team, initial slowdown, build complexity increase.
+
+**Mitigations**: TypeScript training sessions, allow gradual adoption with
+`allowJs: true`.
+```
+
+### Template 3: Y-Statement Format
+
+```markdown
+# ADR-0015: API Gateway Selection
+
+In the context of **building a microservices architecture**,
+facing **the need for centralized API management, authentication, and rate limiting**,
+we decided for **Kong Gateway**
+and against **AWS API Gateway and custom Nginx solution**,
+to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,
+accepting that **we need to manage Kong infrastructure ourselves**.
+```
+
+### Template 4: ADR for Deprecation
+
+```markdown
+# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL
+
+## Status
+
+Accepted (Supersedes ADR-0003)
+
+## Context
+
+ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility
+needs. Since then:
+
+- MongoDB's multi-document transactions remain problematic for our use case
+- Our schema has stabilized and rarely changes
+- We now have PostgreSQL expertise from other services
+- Maintaining two databases increases operational burden
+
+## Decision
+
+Deprecate MongoDB and migrate user profiles to PostgreSQL.
+
+## Migration Plan
+
+1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled
+2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency
+3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor
+4. **Phase 4** (Week 6): Remove MongoDB writes, decommission
+
+## Consequences
+
+### Positive
+
+- Single database technology reduces operational complexity
+- ACID transactions for user data
+- Team can focus PostgreSQL expertise
+
+### Negative
+
+- Migration effort (~4 weeks)
+- Risk of data issues during migration
+- Lose some schema flexibility
+
+## Lessons Learned
+
+Document from ADR-0003 experience:
+
+- Schema flexibility benefits were overestimated
+- Operational cost of multiple databases was underestimated
+- Consider long-term maintenance in technology decisions
+```
+
+### Template 5: Request for Comments (RFC) Style
+
+```markdown
+# RFC-0025: Adopt Event Sourcing for Order Management
+
+## Summary
+
+Propose adopting event sourcing pattern for the order management domain to
+improve auditability, enable temporal queries, and support business analytics.
+
+## Motivation
+
+Current challenges:
+
+1. Audit requirements need complete order history
+2. "What was the order state at time X?" queries are impossible
+3. Analytics team needs event stream for real-time dashboards
+4. Order state reconstruction for customer support is manual
+
+## Detailed Design
+
+### Event Store
+```
+
+OrderCreated { orderId, customerId, items[], timestamp }
+OrderItemAdded { orderId, item, timestamp }
+OrderItemRemoved { orderId, itemId, timestamp }
+PaymentReceived { orderId, amount, paymentId, timestamp }
+OrderShipped { orderId, trackingNumber, timestamp }
+
+```
+
+### Projections
+
+- **CurrentOrderState**: Materialized view for queries
+- **OrderHistory**: Complete timeline for audit
+- **DailyOrderMetrics**: Analytics aggregation
+
+### Technology
+
+- Event Store: EventStoreDB (purpose-built, handles projections)
+- Alternative considered: Kafka + custom projection service
+
+## Drawbacks
+
+- Learning curve for team
+- Increased complexity vs. CRUD
+- Need to design events carefully (immutable once stored)
+- Storage growth (events never deleted)
+
+## Alternatives
+
+1. **Audit tables**: Simpler but doesn't enable temporal queries
+2. **CDC from existing DB**: Complex, doesn't change data model
+3. **Hybrid**: Event source only for order state changes
+
+## Unresolved Questions
+
+- [ ] Event schema versioning strategy
+- [ ] Retention policy for events
+- [ ] Snapshot frequency for performance
+
+## Implementation Plan
+
+1. Prototype with single order type (2 weeks)
+2. Team training on event sourcing (1 week)
+3. Full implementation and migration (4 weeks)
+4. Monitoring and optimization (ongoing)
+
+## References
+
+- [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
+- [EventStoreDB Documentation](https://www.eventstore.com/docs)
+```
+
+## ADR Management
+
+### Directory Structure
+
+```
+docs/
+├── adr/
+│   ├── README.md           # Index and guidelines
+│   ├── template.md         # Team's ADR template
+│   ├── 0001-use-postgresql.md
+│   ├── 0002-caching-strategy.md
+│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
+│   └── 0020-deprecate-mongodb.md      # Supersedes 0003
+```
+
+### ADR Index (README.md)
+
+```markdown
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for [Project Name].
+
+## Index
+
+| ADR                                   | Title                              | Status     | Date       |
+| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
+| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
+| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
+| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |
+| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |
+
+## Creating a New ADR
+
+1. Copy `template.md` to `NNNN-title-with-dashes.md`
+2. Fill in the template
+3. Submit PR for review
+4. Update this index after approval
+
+## ADR Status
+
+- **Proposed**: Under discussion
+- **Accepted**: Decision made, implementing
+- **Deprecated**: No longer relevant
+- **Superseded**: Replaced by another ADR
+- **Rejected**: Considered but not adopted
+```
+
+### Automation (adr-tools)
+
+```bash
+# Install adr-tools
+brew install adr-tools
+
+# Initialize ADR directory
+adr init docs/adr
+
+# Create new ADR
+adr new "Use PostgreSQL as Primary Database"
+
+# Supersede an ADR
+adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"
+
+# Generate table of contents
+adr generate toc > docs/adr/README.md
+
+# Link related ADRs
+adr link 2 "Complements" 1 "Is complemented by"
+```
+
+## Review Process
+
+```markdown
+## ADR Review Checklist
+
+### Before Submission
+
+- [ ] Context clearly explains the problem
+- [ ] All viable options considered
+- [ ] Pros/cons balanced and honest
+- [ ] Consequences (positive and negative) documented
+- [ ] Related ADRs linked
+
+### During Review
+
+- [ ] At least 2 senior engineers reviewed
+- [ ] Affected teams consulted
+- [ ] Security implications considered
+- [ ] Cost implications documented
+- [ ] Reversibility assessed
+
+### After Acceptance
+
+- [ ] ADR index updated
+- [ ] Team notified
+- [ ] Implementation tickets created
+- [ ] Related documentation updated
+```
+
+## Best Practices
+
+### Do's
+
+- **Write ADRs early** - Before implementation starts
+- **Keep them short** - 1-2 pages maximum
+- **Be honest about trade-offs** - Include real cons
+- **Link related decisions** - Build decision graph
+- **Update status** - Deprecate when superseded
+
+### Don'ts
+
+- **Don't change accepted ADRs** - Write new ones to supersede
+- **Don't skip context** - Future readers need background
+- **Don't hide failures** - Rejected decisions are valuable
+- **Don't be vague** - Specific decisions, specific consequences
+- **Don't forget implementation** - ADR without action is waste
+
+## Resources
+
+- [Documenting Architecture Decisions (Michael Nygard)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
+- [MADR Template](https://adr.github.io/madr/)
+- [ADR GitHub Organization](https://adr.github.io/)
+- [adr-tools](https://github.com/npryce/adr-tools)