Menú
Use when encountering any bug, test failure, or unexpected behavior in a bones workspace, before proposing fixes
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
After a bones swarm session closes, decide what to do with the open leaf — fan-in to trunk, keep open, or abandon — and (optionally) materialize trunk into the git worktree, push, and open a PR for the swarmed changes. Use when implementation is complete, all tests pass, and you need to integrate the work back into the bones hub trunk.
MANDATORY at the start of every Claude Code session in a bones workspace (any directory whose tree contains `.bones/`). Establishes how to find and use bones-powers skills and overrides default system-prompt workflow defaults (brainstorm → spec → plan loops, "let's think about this together" patterns) for bones primitives. Must be invoked via the Skill tool BEFORE any response — including clarifying questions, including "I'll just take a quick look first." If `.bones/` exists in the cwd or a parent, this skill applies.
Open, work in, and close a bones swarm session — the slot-shaped lane that bundles a worktree, a claimed task, and an open hub branch. Use when starting feature work that needs isolation from current workspace, before executing implementation plans, or when you need a worktree for parallel work in a bones workspace.
Use IMMEDIATELY in a bones workspace whenever the user asks to orchestrate, dispatch, run, execute, parallelize, fan out, split, or otherwise coordinate work across multiple slots, agents, subagents, waves, or a plan with `[slot: name]` annotations. Drives the swarm dispatch loop end-to-end via the Task tool, advancing waves on full success and surfacing failures without auto-retrying. Fires on phrases like "run the plan", "dispatch the swarm", "kick off slots", "orchestrate the work", "parallel agents", "do this in parallel", or any reference to `.bones/swarm/dispatch.json`.
Use when implementing any feature or bugfix in a bones workspace, before writing implementation code
| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior in a bones workspace, before proposing fixes |
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
Violating the letter of this process is violating the spirit of debugging.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
Use for ANY technical issue:
Use this ESPECIALLY when:
Don't skip when:
You MUST complete each phase before proceeding to the next.
BEFORE attempting ANY fix:
Read Error Messages Carefully
Reproduce Consistently
Check Recent Changes
Gather Evidence in Multi-Component Systems
WHEN system has multiple components (CI → build → signing, API → service → database):
BEFORE proposing fixes, add diagnostic instrumentation:
For EACH component boundary:
- Log what data enters component
- Log what data exits component
- Verify environment/config propagation
- Check state at each layer
Run once to gather evidence showing WHERE it breaks
THEN analyze evidence to identify failing component
THEN investigate that specific component
Example (multi-layer system):
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# Layer 2: Build script
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"
This reveals: Which layer fails (secrets → workflow ✓, workflow → build ✗)
Trace Data Flow
WHEN error is deep in call stack:
See root-cause-tracing.md in this directory for the complete backward tracing technique.
Quick version:
Find the pattern before fixing:
Find Working Examples
Compare Against References
Identify Differences
Understand Dependencies
Scientific method:
Form Single Hypothesis
Test Minimally
Verify Before Continuing
When You Don't Know
Fix the root cause, not the symptom:
Create Failing Test Case
test-driven-development skill for writing proper failing testsImplement Single Fix
Verify Fix
If Fix Doesn't Work
If 3+ Fixes Failed: Question Architecture
Pattern indicating architectural problem:
STOP and question fundamentals:
Discuss with your human partner before attempting more fixes
This is NOT a failed hypothesis - this is a wrong architecture.
When debugging in a bones workspace:
bones status (not git status) to confirm a clean working tree during phase 1 (root-cause investigation)..bones/leaves/<slot>/leaf.log. Tail this for trace data during phase 2 (pattern analysis).bones swarm join --slot=debug-<id> --task-id=<id>) to reproduce a bug without polluting the main workspace.bones swarm commit -m 'debug snapshot' so it's recorded on the leaf — swarm close --result=fail does not lose committed work.If you catch yourself thinking:
ALL of these mean: STOP. Return to Phase 1.
If 3+ fixes failed: Question the architecture (see Phase 4.5)
Watch for these redirections:
When you see these: STOP. Return to Phase 1.
| Excuse | Reality |
|---|---|
| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
| Phase | Key Activities | Success Criteria |
|---|---|---|
| 1. Root Cause | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare | Identify differences |
| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |
If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
But: 95% of "no root cause" cases are incomplete investigation.
These techniques are part of systematic debugging and available in this directory:
root-cause-tracing.md - Trace bugs backward through call stack to find original triggerdefense-in-depth.md - Add validation at multiple layers after finding root causecondition-based-waiting.md - Replace arbitrary timeouts with condition pollingRelated skills:
From debugging sessions: