mikeparcewski/wicked-garden / skills/engineering
wicked-garden-engineering
VerifiedEngineering domain skill: code review, architecture analysis, debugging, implementation planning, documentation, release PRs and scaffolds. Use when: "review this code / file / diff" (quality, patterns, maintainability; --focus, --persona, --scenarios); "review the architecture of X" / "evaluate component boundaries, coupling, or layer violations" (--scope module|service|system); "debug this error / bug / unexpected behavior" (root cause, reproduction, fix, prevention); "plan this change" / "implementation plan with file changes, risks and tests before writing code"; "generate API docs / README / guide / inline comments" (--type api|readme|guide|inline) or "docs drifted from code"; "prepare a release PR" (never tags or publishes); "scaffold a new CLI / service / library". NOT for reviewing an AI agent system (agentic review), a UI (product ux-review), a go/no-go verdict (archetype review), greenfield design (the solution-architect worker) or scaffolding a new MCP server (wicked-garden-mcp-scaffold).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.7 KB |
| refs/arch.md | markdown | 4.5 KB |
| refs/conformance.md | markdown | 3.8 KB |
| refs/debug.md | markdown | 4.0 KB |
| refs/docs.md | markdown | 5.8 KB |
| refs/engineering-checklists.md | markdown | 2.7 KB |
| refs/engineering-templates.md | markdown | 1.2 KB |
| refs/plan.md | markdown | 4.1 KB |
| refs/release.md | markdown | 7.4 KB |
| refs/review.md | markdown | 7.4 KB |
| refs/scaffold.md | markdown | 5.6 KB |
refs/debug.md
View on GitHub# debug — garden-specific debug rubric
Wicked-garden preferred debug process. The systematic method is the hypothesis loop —
gather context, form a hypothesis, test it, document the root cause — run inline on every
seat. This ref captures garden-specific heuristics and the standard output format.
## Garden-specific debug heuristics
### 1. Check the bus first (wicked-bus events)
Most garden failures surface as missing or malformed events. Before reading code:
```bash
wicked-bus query --limit 20 --format json # recent events
wicked-bus query --event "domain:*:failed" # failure events
```
### 2. Check the gate engine / wicked-vault availability
Gate failures that say `"gate: unavailable"` are almost always a loom/vault resolution issue, not a logic bug:
- Is `WICKED_LOOM_BIN` set correctly?
- Is `wicked-vault` available via `npx`?
- Is `WICKED_LOOM_CUTOVER=off` accidentally set?
### 3. Hook scripts: always run with `python3 -c "..."` test first
Hook issues are commonly cross-platform JSON output failures. Test the hook script standalone:
```bash
python3 scripts/hooks/script.py '{"event": "test"}' 2>&1
```
### 4. Scope creep as a bug category
When reviewing a diff that triggers a bug report, check if the diff contains changes *outside* the stated scope — scope creep often introduces subtle regressions.
## Six-step debugging process
1. **Understand** — expected vs actual behavior, reproduction steps, when it started
2. **Gather evidence** — logs, stack traces, recent changes, config drift
3. **Form hypothesis** — most likely cause + what would disprove it
4. **Test hypothesis** — targeted test, not random changes
5. **Implement fix** — minimal fix, verify resolution, add regression test
6. **Document** — root cause, fix rationale, prevention measure
## Issue categories
| Category | Examples |
|----------|---------|
| Logic errors | Wrong conditions, off-by-one, missing edge cases |
| State errors | Race conditions, stale closures, shared mutable state |
| Integration errors | API contract mismatch, auth failures, timeout, format mismatch |
| Performance | N+1 queries, missing indexes, memory leaks, unbounded loops |
| Environment | Config differences, missing env vars, version mismatches, permissions |
| Garden-specific | Loom unavailable, vault unresolvable, bus consumer not registered, hook cross-platform failure |
## Standard output format
````markdown
## Debug Analysis: {issue title}
### Symptom
{what was observed — exact error message or behavior}
### Root Cause
{underlying issue — not just the symptom}
**Confidence**: HIGH / MEDIUM / LOW
### Why This Happened
{explain the causal chain from trigger to symptom}
### Evidence
- `{file}:{line}` — {what was found}
- {log entry or test result}
### Reproduction Steps
1. {step}
2. {step}
3. Observe: {expected} vs {actual}
### Recommended Fix
```diff
- {bad code}
+ {fixed code}
```
**Rationale**: {why this fixes the root cause, not just the symptom}
### Verification
1. {how to verify the fix works}
2. {what to monitor after deploying}
### Prevention
- {test to add}
- {monitoring/alerting to add}
- {code pattern to avoid}
### Alternative Explanations
{only if confidence is not HIGH — other possible causes}
````
## Debugging techniques
### Stack trace analysis — work backwards
```
Error: Cannot read property 'id' of undefined
at getUserName (user.js:42) ← What is undefined here?
at renderProfile (profile.js:15) ← What data was passed?
at App.render (App.js:88) ← Where did this come from?
```
### Binary search with git bisect
```bash
git bisect start
git bisect bad HEAD
git bisect good v1.2.0
# test each commit git bisect suggests
```
### Async timing issues — common pattern
```javascript
// Bug: result is undefined — await missing
let result;
fetchData().then(data => result = data);
console.log(result); // undefined!
// Fix
const result = await fetchData();
```
### Null/undefined — prefer optional chaining
```javascript
// Bug
user.profile.name // profile might be null
// Fix
user?.profile?.name ?? 'Unknown'
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |