Skill 99 — Wildcard Debugger (Fallback)

Purpose: When the workflow is stuck, this skill runs a structured debug loop:

• •build hypotheses
• •gather evidence
• •attempt minimal fixes
• •verify
• •stop with a clear root-cause report

Protocols:

• •[[docs/PROTOCOLS/VAULT_PROBE]]
• •[[docs/PROTOCOLS/EVIDENCE]]
• •[[docs/PROTOCOLS/RUN_LOGGING]]
• •[[docs/PROTOCOLS/PATCH_GATE]]
• •[[docs/PROTOCOLS/CONTEXT_BUDGET]]

Tools:

• •[[tools/repl/README]] — suggest patches + gated apply

Inputs (from Orchestrator)

• •The failing command (required)
• •The error output (required) — ideally as a path to a log file under artifacts/_runs/
• •The task slug (optional but recommended)
• •What was tried already (optional)

Outputs (must write)

• •artifacts/debug_report.md
• •artifacts/debug_steps.json
• •[[docs/skills/99_wildcard_debugger/SUMMARY]]

Run log (mandatory)

Create: artifacts/_runs/<timestamp>_99_wildcard_debugger/ with:

• •COMMANDS.md (every command tried)
• •LOG.txt (full outputs)

Caps (must obey)

• •Max iterations: 30
• •Stop early if: 5 iterations without new evidence or a narrowed hypothesis
• •Prefer minimal diffs; do not do sweeping refactors without explicit approval

Debug loop (repeat until fixed or caps hit)

1. •Reproduce the failure (run the exact failing command).
2. •Extract the most specific error signal:
   • •stack trace line(s)
   • •file paths
   • •error codes/messages
3. •Generate 2–4 hypotheses.
4. •For each hypothesis, run targeted probes:
   • •probe search for error strings/symbols
   • •probe open around suspected files/lines
   • •config lookup (package.json, env vars)
5. •Choose the best hypothesis, apply the smallest change:
   • •generate a patch (read-only):
     • •node tools/repl/repl.mjs suggest replace ... > artifacts/_runs/<ts>_99_wildcard_debugger/PATCH.diff
   • •validate the patch (policy + git apply --check):
     • •node tools/repl/repl.mjs patch check --patch artifacts/_runs/<ts>_99_wildcard_debugger/PATCH.diff
   • •apply via the single write gate:
     • •node tools/repl/repl.mjs patch apply --patch artifacts/_runs/<ts>_99_wildcard_debugger/PATCH.diff
6. •Re-run the failing command.
7. •Log what changed and what you learned.

Reporting requirements

Write artifacts/debug_report.md with:

• •Symptom (exact failure)
• •Root cause (or top hypotheses if unresolved)
• •Evidence pointers (path:Lx-Ly)
• •Fix applied (or recommended next steps)
• •How to verify

Write artifacts/debug_steps.json as an array of iterations:

• •{i, hypothesis, probes, change, result}

Definition of Done

• • Either the failing command succeeds, OR you produce a crisp report with next data needed
• • Debug report includes evidence pointers and repro steps
• • Artifacts + summary exist