wicked-garden 12.27.0

package/skills/engineering/debugging/refs/process.md

@@ -0,0 +1,203 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Debugging Process & Checklists
+
+## Systematic Debugging Process
+
+### 1. Understand the Problem
+- What is expected vs actual behavior?
+- When did it start? Can it be reproduced?
+- What changed recently?
+- Is it environment-specific?
+- Does it happen consistently?
+
+### 2. Gather Evidence
+- Read logs and stack traces
+- Review recent changes (git log)
+- Identify patterns
+- Collect error messages
+- Check monitoring/metrics
+- Review environment variables
+
+### 3. Form Hypothesis
+- What is the most likely cause?
+- What evidence supports this?
+- What would disprove this?
+- Are there alternative explanations?
+
+### 4. Test Hypothesis
+- Design targeted test
+- Observe results
+- Document findings
+- Refine hypothesis if needed
+
+### 5. Implement Fix
+- Develop minimal fix
+- Verify resolution
+- Add regression tests
+- Test edge cases
+
+### 6. Document
+- Root cause and fix
+- Add monitoring/alerting
+- Update runbooks
+- Share learnings
+
+## Issue Categories
+
+### Logic Errors
+- Incorrect conditions (>, >=, ==, ===)
+- Off-by-one errors
+- Wrong operators
+- Missing edge cases
+
+### State Errors
+- Race conditions
+- Stale closures
+- Shared mutable state
+- Incorrect state initialization
+
+### Integration Errors
+- API mismatch (contract changed)
+- Auth issues (expired tokens)
+- Timeouts (slow external service)
+- Network errors
+
+### Performance Issues
+- N+1 queries
+- Missing indexes
+- Memory leaks
+- Inefficient algorithms
+- Unoptimized database queries
+
+### Environment Issues
+- Config differences (dev vs prod)
+- Missing environment variables
+- Permission problems
+- Dependency version mismatches
+
+## Output Template
+
+```markdown
+## Debug Analysis: {Issue}
+
+### Problem Summary
+{Clear description}
+
+### Evidence
+- {Key findings}
+
+### Root Cause
+{Most likely cause}
+
+**Confidence**: HIGH / MEDIUM / LOW
+
+### Why This Happened
+{Underlying cause}
+
+### Reproduction
+1. {Step 1}
+2. {Observe: expected vs actual}
+
+### Recommended Fix
+```diff
+{Code change}
+```
+
+**Rationale**: {Why this fixes it}
+
+### Verification
+- {How to verify}
+- {What to monitor}
+
+### Prevention
+- {How to avoid}
+- {Tests to add}
+```
+
+## Tools by Environment
+
+### Browser DevTools
+- Console: Logging, errors, warnings
+- Network: Request/response inspection
+- Sources: Breakpoint debugging
+- Performance: Profiling, timeline
+- Memory: Heap snapshots, leak detection
+
+### Node.js
+- `node --inspect`: Chrome DevTools debugging
+- Error stack traces: Call hierarchy
+- `console.trace()`: Full stack trace
+- Profiling: `node --prof`
+
+### Database
+- EXPLAIN plans: Query execution analysis
+- Slow query logs: Performance issues
+- Connection monitoring: Pool usage
+- Index analysis: Missing indexes
+
+## Severity Levels
+
+### CRITICAL
+- Production down
+- Data loss
+- Security breach
+- Payment processing broken
+- Users completely blocked
+
+**Action**: Immediate fix, all hands
+
+### HIGH
+- Major functionality broken
+- Performance severely degraded
+- Many users affected
+- Revenue impacting
+
+**Action**: Fix within hours, escalate
+
+### MEDIUM
+- Feature broken
+- Workaround available
+- Some users affected
+- Degraded experience
+
+**Action**: Fix within days, prioritize
+
+### LOW
+- Minor issue
+- Edge case
+- Cosmetic problem
+- Few users affected
+
+**Action**: Backlog, fix when convenient
+
+## Debugging Checklist
+
+### Initial Investigation
+- [ ] Can you reproduce the issue?
+- [ ] What are the exact error messages?
+- [ ] When did it start happening?
+- [ ] What changed recently?
+- [ ] Is it environment-specific?
+
+### Evidence Gathering
+- [ ] Checked application logs
+- [ ] Reviewed stack traces
+- [ ] Inspected network requests
+- [ ] Checked database queries
+- [ ] Reviewed recent commits
+
+### Testing
+- [ ] Isolated the problem area
+- [ ] Tested hypothesis
+- [ ] Verified fix resolves issue
+- [ ] Tested edge cases
+- [ ] Checked for side effects
+
+### Prevention
+- [ ] Added regression test
+- [ ] Updated documentation
+- [ ] Added monitoring/alerting
+- [ ] Shared learnings with team

package/skills/engineering/docs/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: docs
+description: |
+  Use when generating documentation from code, auditing documentation coverage for gaps, or detecting
+  code-doc drift after a refactor. Covers generate (API docs, READMEs), audit (coverage metrics,
+  undocumented exports), and sync (stale docs detection) in one skill.
+  NOT for architecture documentation (use the architecture skill) or product requirements (use product/requirements-analysis).
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+
+# Documentation Engineering Skill
+
+Generate, audit, and sync documentation across the codebase.
+
+## Quick Start
+
+### Generate docs from code
+
+```bash
+/wicked-garden:engineering:docs <file-or-component> --type api|readme|guide|inline
+```
+
+Extracts types, signatures, and comments to produce API docs, READMEs, or inline comments.
+
+### Audit documentation coverage
+
+```bash
+/wicked-garden:engineering:docs <path> --audit
+```
+
+Reports coverage (documented vs total exports), quality score, and prioritized gaps.
+
+### Detect stale docs after code changes
+
+```bash
+/wicked-garden:engineering:docs <path> --sync
+```
+
+Identifies documentation that has drifted from implementation after a refactor or rename.
+
+## Generate
+
+Transform code into documentation:
+- Extract types, method signatures, and inline comments
+- Generate API reference (JSDoc / docstring style)
+- Create or update README files
+- Add inline comments where missing
+
+**Output**: Markdown docs ready to commit, or inline comment patches.
+
+## Audit
+
+Evaluate documentation health across the codebase:
+- Find undocumented exported functions, classes, and API endpoints
+- Calculate coverage percentage and quality score (description + params + examples)
+- Prioritize gaps: High = public APIs, Medium = internal utilities, Low = private/test
+
+**Quality Score (0-100)**:
+- Has description: +25
+- Has parameters: +25
+- Has examples: +30
+- Has edge cases: +20
+
+**Coverage Report format**:
+```markdown
+# Documentation Coverage Report
+
+## Summary
+| Category  | Total | Documented | Coverage |
+|-----------|-------|------------|----------|
+| Functions | 145   | 98         | 67.6%    |
+
+## Top Issues
+### Undocumented Public Functions (12)
+- `src/api/auth.ts::authenticate` — Core auth
+```
+
+## Sync
+
+Detect and fix documentation drift:
+- Compare code signatures against existing doc strings
+- Flag mismatched parameter names, changed return types, removed methods
+- Suggest specific doc updates with before/after diffs
+
+## Integration
+
+- Use `wicked-garden:search` to scope the file set before auditing
+- Native TaskCreate (with `metadata.event_type="task"`) tracks doc tasks
+- CI: run audit in `--report` mode to gate PRs that drop below coverage threshold
+
+## Best Practices
+
+1. Prioritize public APIs first — that is what users see
+2. Set realistic targets — 80% with good quality beats 100% with stubs
+3. Run sync after every significant refactor — don't let drift accumulate
+4. Automate in CI — block PRs that reduce coverage

package/skills/engineering/engineering/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: engineering
+description: |
+  Senior engineering guidance on implementation, code quality, and maintainability. Use when reviewing
+  code for R1-R6 standards violations (dead code, bare panics, magic values, swallowed errors,
+  unbounded ops, god functions) or getting cross-cutting implementation advice.
+  NOT for architecture decisions (use the architecture skill) or debugging (use the debugging skill).
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+
+# Engineering Skill
+
+Provide senior engineering guidance on code quality, architecture, and implementation.
+
+## What This Skill Does
+
+1. **Implementation Planning** - Guide on how to build features with quality
+2. **Code Review** - Assess quality, patterns, maintainability
+3. **Architecture Guidance** - Evaluate structure and design decisions
+4. **Best Practices** - Share knowledge on conventions and patterns
+
+## Key Principles
+
+### Code Quality
+- Clear naming and organization
+- DRY (Don't Repeat Yourself)
+- SOLID principles
+- Consistent style
+
+### Architecture
+- Design patterns
+- Separation of concerns
+- Component boundaries
+- Dependency management
+
+### Maintainability
+- Easy to understand and modify
+- Easy to test
+- Well-documented
+- Error handling
+
+### Performance
+- Efficient algorithms and data structures
+- Resource management
+- Caching strategies
+
+## Review Process
+
+Use comprehensive checklists covering:
+- Structure (patterns, abstractions, dependencies)
+- Quality (naming, duplication, style)
+- Error handling (recovery, messages)
+- Maintainability (clarity, configuration)
+- Performance (queries, data structures)
+- **Agent overstepping** (unnecessary changes, commented-out code, scope creep)
+
+See [refs/checklists.md](refs/checklists.md) for detailed review checklists and severity guidelines.
+
+## Output Formats
+
+Provide structured guidance for:
+- Implementation planning with approach and steps
+- Code reviews with strengths, issues, and recommendations
+
+See [refs/templates.md](refs/templates.md) for output templates and focus areas.
+
+## Integration with Specialists
+
+Frontend (React/CSS/browser), backend (APIs/databases/server-side), and debugging
+(error investigation, root-cause analysis) are handled **inline** by this skill —
+apply the relevant checklist from `refs/`. For genuinely structural work (system
+boundaries, cross-cutting design trade-offs), dispatch the architecture specialist:
+- `wicked-garden:engineering:solution-architect` — system design, structural trade-offs
+
+## Integration with wicked-crew
+
+Engaged during:
+- **Build Phase**: Implementation guidance and pattern recommendations
+- **Review Phase**: Code quality and architecture review
+- **Error Recovery**: When issues are encountered during development
+
+## Notes
+
+- Always explain the "why" behind recommendations
+- Be constructive, not critical
+- Offer alternatives with tradeoffs
+- Encourage questions and discussion

package/skills/engineering/engineering/refs/checklists.md

@@ -0,0 +1,91 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Engineering Review Checklists
+
+## Structure Checklist
+- [ ] Follows established patterns
+- [ ] Appropriate abstraction level
+- [ ] Clear boundaries/interfaces
+- [ ] No circular dependencies
+- [ ] Separation of concerns
+
+## Quality Checklist
+- [ ] Clear naming
+- [ ] No unnecessary duplication
+- [ ] Appropriate comments (not excessive)
+- [ ] Consistent style
+- [ ] Single responsibility
+
+## Error Handling Checklist
+- [ ] Errors handled appropriately
+- [ ] No swallowed exceptions
+- [ ] Meaningful error messages
+- [ ] Recovery strategies
+
+## Maintainability Checklist
+- [ ] Easy to understand
+- [ ] Easy to modify
+- [ ] No magic numbers/strings
+- [ ] Configuration externalized
+
+## Performance Checklist
+- [ ] No obvious N+1 queries
+- [ ] Appropriate data structures
+- [ ] No unnecessary computation
+- [ ] Caching where appropriate
+
+## Common Issues to Watch For
+
+### Code Smells
+- Magic numbers/strings (use constants)
+- Long functions (break into smaller)
+- Deep nesting (refactor to early returns)
+- Duplicated code (extract to shared)
+- Poor naming (rename for clarity)
+- Missing error handling
+- Resource leaks (unclosed connections)
+
+### Good Patterns
+- Single responsibility
+- Clear separation of concerns
+- Defensive programming
+- Meaningful abstractions
+- Consistent error handling
+
+## Agent Overstepping Checklist
+
+Detect patterns where AI agents make changes beyond what was requested:
+
+### Unnecessary Changes (HIGH)
+- [ ] Code modified that wasn't part of the task scope
+- [ ] Working logic replaced with "simplified" alternatives
+- [ ] Variable/function renames unrelated to the task
+- [ ] Import reorganization or style changes outside scope
+- [ ] Added abstractions or helpers for one-time operations
+
+### Commented-Out Code (HIGH)
+- [ ] Working code commented out instead of removed
+- [ ] Logic replaced with TODO comments
+- [ ] Conditional blocks disabled via comments
+- [ ] Backward-compatibility shims with "// removed" markers
+
+### Over-Engineering (MEDIUM)
+- [ ] New configuration options nobody asked for
+- [ ] Feature flags for non-flagged features
+- [ ] Added error handling for impossible scenarios
+- [ ] Premature abstractions ("just in case" utilities)
+- [ ] Extra validation layers beyond system boundaries
+
+### Scope Creep Indicators
+- [ ] Files modified that weren't mentioned in the task
+- [ ] Refactoring mixed into bug fixes
+- [ ] Style changes bundled with feature work
+- [ ] Documentation updates for unchanged code
+
+## Severity Guidelines
+
+- **HIGH**: Will cause bugs, broken patterns, production issues, major maintainability problems
+- **MEDIUM**: Should fix, not blocking, tech debt accumulation
+- **LOW**: Nice to have, style preferences, minor improvements

package/skills/engineering/engineering/refs/templates.md

@@ -0,0 +1,71 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# Engineering Output Templates
+
+## Implementation Guidance Template
+
+```markdown
+## Implementation Plan: {Feature}
+
+### Approach
+{High-level strategy}
+
+### Steps
+1. {Step with rationale}
+2. {Step with rationale}
+
+### Key Patterns
+- {Pattern and why it fits}
+
+### Considerations
+- {Important notes or tradeoffs}
+```
+
+## Code Review Template
+
+```markdown
+## Engineering Review
+
+### Strengths
+- {Good practices observed}
+
+### Issues
+| Severity | Issue | Location | Fix |
+|----------|-------|----------|-----|
+| HIGH/MEDIUM/LOW | {Description} | file:line | {Recommendation} |
+
+### Recommendations
+1. {Priority item}
+2. {Secondary item}
+```
+
+## Key Focus Areas
+
+### Code Quality
+- Clear naming and organization
+- DRY (Don't Repeat Yourself)
+- SOLID principles
+- Consistent style
+- Appropriate comments
+
+### Architecture
+- Design patterns
+- Separation of concerns
+- Abstraction levels
+- Component boundaries
+- Dependency management
+
+### Maintainability
+- Easy to understand
+- Easy to modify
+- Easy to test
+- Well-documented
+- Error handling
+
+### Performance
+- Efficient algorithms and data structures
+- Resource management
+- Caching strategies
+- Database query optimization

package/skills/engineering/frontend/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: frontend
+description: |
+  Frontend engineering specialist for React, CSS, browser APIs, component
+  design, accessibility, and performance. This skill should be used when the
+  user asks about UI implementation, component review, or frontend-specific questions.
+
+  Use when: "build a React component", "CSS layout issue", "frontend performance",
+  "browser API", "component design", "accessibility check", "responsive design"
+portability: portable
+# TODO #339: When Claude Code supports 'paths' in skill frontmatter for
+# file-context auto-activation, add:
+#   paths: ["**/*.tsx", "**/*.jsx", "**/*.css", "**/*.scss", "**/components/**"]
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+
+# Frontend Skill
+
+Specialized frontend engineering guidance for React, CSS, and browser-based applications.
+
+## When to Use
+
+- Building React components
+- CSS and styling questions
+- Browser API usage
+- Frontend performance optimization
+- Accessibility (a11y) guidance
+- User says "frontend", "React", "CSS", "component", "UI"
+
+## Key Focus Areas
+
+### React Patterns
+- Component composition and single responsibility
+- Hook usage (useState, useEffect, custom hooks)
+- State management (context, props, lifting state)
+- Performance (memo, useMemo, useCallback)
+- Error boundaries
+
+### CSS & Styling
+- Responsive design (flexbox, grid, media queries)
+- Modern CSS (custom properties, container queries)
+- Animations (GPU-accelerated)
+- Theming and design systems
+
+### Browser APIs
+- Fetch API and async operations
+- Local/Session Storage
+- Event handling
+- Performance API
+
+### Accessibility
+- Semantic HTML elements
+- ARIA labels and roles
+- Keyboard navigation
+- Screen reader compatibility
+- WCAG color contrast
+
+### Performance
+- Code splitting and lazy loading
+- Bundle optimization
+- Image optimization
+- Virtual scrolling
+- Debouncing and throttling
+
+## Review Process
+
+Use comprehensive checklists for:
+- Component quality (responsibility, props, composition)
+- React best practices (hooks, effects, state)
+- Styling (responsiveness, consistency)
+- Accessibility (semantic HTML, keyboard nav, ARIA)
+
+See [refs/checklists.md](refs/checklists.md) for detailed checklists, anti-patterns, and output templates.
+
+## Code Patterns
+
+Common React and CSS patterns for:
+- Component structure with TypeScript
+- Custom hooks (debounce, etc.)
+- Responsive design
+- Accessibility patterns
+- Performance optimization
+
+See [refs/patterns.md](refs/patterns.md) for code examples and best practices.
+
+## Notes
+
+- Prioritize accessibility from the start
+- Mobile-first responsive design
+- Use semantic HTML before reaching for ARIA
+- Test with keyboard navigation and screen readers