rulesets/root-cause-trace, branch main

docs(skills): tighten debug, root-cause-trace, and five-whys

2026-05-22T19:26:43+00:00

Three audit-pass fixes across the debugging skills. debug now captures environment and recent-change context (versions, flags, dataset, seed/clock, concurrency, recent commits) as a Phase-1 step. Many intermittent bugs live in state or environment, not a local code path, and "what changed recently" is often the fastest route to the cause. root-cause-trace's defense-in-depth said to add a check at every layer that could have caught the bad value, which breeds validation spam. It now adds checks only at boundary-owning layers (ingress, persistence, the invariant owner, final render), and says a pass-through function that owns neither a boundary nor an invariant shouldn't get a duplicate null check. five-whys now makes each link carry an evidence field and a counterfactual: if you remove this cause, does the symptom above still happen? That's the guard against a tidy chain that reads well but wouldn't have prevented the failure.

docs(skills): tighten descriptions under 1000 chars

2026-05-07T02:59:40+00:00

Trim each long description to <=1000 chars while preserving content (phases, when-to-use, when-not-to, companion references). Frees enough per-session skill-listing budget to quiet the truncation warning on small-context models.

refactor(debug): make debug a triage router, align specialist cross-refs

2026-05-06T10:23:01+00:00

I sharpened the debug skill so it stops duplicating root-cause-trace and five-whys. Phase 1 captures evidence and stops there. Phase 2 routes to the right specialist instead of asking why three times inline. Phases 3 and 4 keep the verify-and-fix discipline. I also updated the companion lines in root-cause-trace and five-whys so all three descriptions stay in sync.

feat: clean-room synthesis — brainstorm, memorize, root-cause-trace, five-whys

2026-04-19T19:40:34+00:00

Four new skills synthesized from patterns in NeoLabHQ/context-engineering-kit (GPL-3.0). Clean-room approach: extracted rubrics from the originals (triggers, phases, hard cases, footguns, novel patterns), then wrote from scratch without referencing their prose. Ideas and methods aren't copyrightable; wording is. These skills are independent works. brainstorm Turn a vague idea into a validated design doc. Three phases: one-question-at-a-time dialogue, six-approach exploration (three conventional + three diverse tail samples for anti-convergence), chunked design presentation with per-chunk validation. Output: docs/design/.md. Hands off to arch-decide / arch-design / implementation. memorize Curate session insights into project CLAUDE.md under a dedicated "## Memorized Insights" section. Grow-and- refine per ACE (arXiv:2510.04618): atomic, evidence- backed, non-redundant bullets. Args: --dry-run, --max, --target, --section, --source. Flags cross-project patterns for promotion to ~/code/rulesets/claude-rules/. Clearly delineates from auto-memory (private) and formal rules (stable policy). root-cause-trace Backward-walk technique for debugging. Observe symptom → identify immediate cause → walk up the call chain → find original trigger → fix at source + defense-in- depth at each intermediate layer. Instrumentation guidance (stack capture before the dangerous op, not after; stderr not framework logger in tests); test- pollution bisection. Companion to /debug — /debug is broader; this is specifically the backward walk. five-whys Iterative why-questioning from symptom to process/ decision root cause. Five is a convention, not a quota — stop when a cause, if eliminated, would prevent every symptom in the chain. Handles branching (multiple contributing causes). Validates chains by walking back from root to symptom. Refuses to terminate at "human error" or "not enough budget" — those have deeper whys. Companion to root-cause-trace (that's for code execution; this is for process). Makefile SKILLS extended. make install symlinks all four into ~/.claude/skills/ alongside existing skills. Lint clean.