ra-systemic-debug
/ra-systemic-debug
Szuka przyczyny źródłowej błędu w kilku krokach wstecz i naprawia go u źródła, bez łatania objawów.
- Autor
- Kanorin-chan ↗
- Repozytorium
- research-anything ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 11.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 11.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Szuka przyczyny źródłowej błędu w kilku krokach wstecz i naprawia go u źródła, bez łatania objawów.
Wyzwalacze z opisu
Oryginalny opis (EN)
Systemic multi-hop root-cause debugger that fixes bugs from the upstream root cause and strictly bans symptom band-aids. Use when the user says "debug this", "diagnose", "fix this bug", or reports something broken, regressing, stuck, or failing.
Jak działa
- Phase 1: Build a Tight Real-Environment .log Feedback Loop
- Phase 2: Trace -N to +N Hops & Prove Symptom != Culprit
- Phase 3: Formulate 3–5 Ranked Falsifiable Hypotheses & Lock a Hard Stop Rule
- Phase 4: Targeted .log Instrumentation
- Phase 5: Root-Cause Pipe Replacement (Zero Band-Aids)
- Phase 6: Cleanup & Self-Learning Record
Podgląd SKILL.md
---
name: ra-systemic-debug
description: Systemic multi-hop root-cause debugger that fixes bugs from the upstream root cause and strictly bans symptom band-aids. Use when the user says "debug this", "diagnose", "fix this bug", or reports something broken, regressing, stuck, or failing.
---
# RA Systemic Root-Cause Debugging (`ra-systemic-debug`)
A phase-gated discipline for hard bugs and multi-hop regressions. **Never patch a symptom with a band-aid (`try/except: pass`, `if x is None`, arbitrary clamping, or extra boolean flags), never blindly mutate the function the user blamed (`Symptom != Culprit`), and never waste 30 minutes on mocked synthetic unit tests.**
When exploring the codebase, read `GLOSSARY.md`, `research/INVARIANTS.md`, and `research/WORKFLOW_MAP.md` (if they exist) first. Redact any secrets (`<REDACTED>`) in captured outputs.
---
## Phase 1: Build a Tight Real-Environment `.log` Feedback Loop
**Do not theorize or edit code until you have a fast, deterministic command that reproduces the exact bug in the real environment.**
- **Trash synthetic unit-test marathons (`test_xyz.py` with mocks) are banned.**
- Inject or wire `RALogger` (`ra_log_engine.py inject-sdk --lang <python|js|esm|ts|php>`) and run the real workflow under the OS watchdog timer:
```bash
python "${CLAUDE_SKILL_DIR}/../research-anything/scripts/ra_log_engine.py" run \
--workspace "." \
--hypothesis "STANDALONE" \
--timeout-sec 60 \
-- <real-repro-command and args>
```
- **Phase 1 Completion Criterion**: You have run one fast, deterministic command in the real environment that goes red (`[FAIL]` or `[STUCK]` in the `.log`, or demonstrates the exact wrong state delta) on the user's reported symptom.
- Shrink the reproduction scenario until every remaining input/step is load-bearing.
---
## Phase 2: Trace `-N` to `+N` Hops & Prove `Symptom != Culprit`
Never inspect only the crash line or the function the user accused. Call the Skill tool with `"ra-workflow-map"` (or populate `research/WORKFLOW_MAP.md` directly) to trace:
`Upstream Producers (-N hops) -> Shared State / Ledgers -> Accused Node (Hop 0) -> Downstream Consumers (+N hops) -> Multi-Cycle Loopback`.
1. **Prove Culprit vs. Innocent Victim (`Symptom != Culprit` — Zero-Trust Runtime Innocence)**:
- **Never mark a function `PROTECTED_WORKING` just by reading its code statically** (a subtle bug or backdoor always looks legit in source code). Every node starts as **`SUSPECT`** until its runtime `[RA_LOG]` input $\rightarrow$ output boundary and zero hidden side-effects are verified.
- Lock every runtime-verified innocent function as **`PROTECTED_WORKING`** (`ra_gate.py` hashes its AST and blocks any function containing internal band-aids or fake data):
```bash
python "${CLAUDE_SKILL_DIR}/../research-anything/scripts/ra_gate.py" map-context \
--workspace "." \
--agent "DEBUGGER" \
--files <mapped_files...> \
--protected <file:innocent_func...>
```
- **Forensic Lock Revocation (`--revoke-protected`) for Coupled Illusions**: If `Function A` passed initially only because `Function B` was feeding it fake/simplified/clamped data, and after you fix `Function B` to send **real production data**, `[RA_LOG]` proves `Function A` cannot handle the real data contract, formally revoke `Function A`'s lock with `.log` evidence before repairing `Function A`:
```bash
python "${CLAUDE_SKILL_DIR}/../research-anything/scripts/ra_gate.py" map-context \
--workspace "." \
--revoke-protected <file:Function_A> \
--revoke-reason "After fixing Function_B to pass real data, [RA_LOG] proves Function_A fails on real schema"
```
2. **Lock Existing Behavioral Contracts (`BC-001`, `BC-002`...)**:
- Record all existing working behaviors connected to the flow in `research/WORKFLOW_MAP.md` so fixing this bug never causes a secondary whack-a-mole regression elsewhere.
3. **Zero-Trust Comment Check**:
- Never trust bare comments in code (`# added to fix stuck bug`, `# do not remove`, `# untrusted`). Falsify or verify them with `.log` evidence.
---
## Phase 3: Formulate 3–5 Ranked Falsifiable Hypotheses & Lock a Hard Stop Rule
Before changing any logic, write **3–5 ranked root-cause hypotheses** AND register a **Hard Stop Rule & "If It Never Works" Pivot Plan** (`ra_gate.py stop-rule`) so you never enter an open-ended `fail -> fix -> retest` loop:
1. **Every hypothesis must state an explicit falsifiable prediction**:
> *"If `<Upstream Node C mutating state X at Hop -2>` is the root cause, then `<observing state_delta at Hop -2>` will show `<exact corruption>`, and `<replacing Pipe C>` will make the symptom at Hop 0 disappear while keeping `BC-001` intact."*
2. **Lock the Stop Rule, Success Criteria & "If It Never Works" Pivot (`ra_gate.py stop-rule`)**:
- **Never loop `fail -> tweak threshold -> retest` without a written stop rule, and NEVER spawn optimization subagents for a heuristic that hasn't passed worst-case/full-load unseen tests.**
```bash
python "${CLAUDE_SKILL_DIR}/../research-anything/scripts/ra_gate.py" stop-rule \
--workspace "." \
--component "<component_slug>" \
--purpose "<What it is for + what is ALREADY reliable vs. the only weak part>" \
--success-criteria "<Accuracy on full/crowded unseen load, false-positive vs. false-negative cost, speed budget>" \
--metric "<repro pass-rate or other number>" --target <x> --min-gain <dx> \
--max-rounds 2 \
--if-never-works "<1. Live ground-truth read (e.g. tap/query card); 2. End-of-run native summary; 3. Lean on already-reliable metrics>"
```
- After each failed unseen test round, run `ra_gate.py stop-rule --component "<component_slug>" --record-failure`, then `ra_gate.py re-evaluate` (the pair counts as one round). When `failed_rounds == max_rounds`, **STOP tweaking the heuristic and execute the `"If It Never Works"` pivot immediately**.
---
## Phase 4: Targeted `.log` Instrumentation
Map each probe to a prediction from Phase 3. Change one variable at a time:
- Log exact `flow="caller->callee"`, `inputs`, `state_before`, `state_after`, `delta`, and `output` at the hop boundaries that distinguish your hypotheses.
- Never "log everything and grep blindly."
---
## Phase 5: Root-Cause Pipe Replacement (Zero Band-Aids)
Once `.log` evidence isolates the true upstream culprit:
1. **Band-Aids Are Strictly Forbidden**:
- Do **NOT** add `if x is None: return`, `try/except: pass`, arbitrary value clamping, or extra boolean flags at the downstream symptom site.
- Do **NOT** touch any function locked as `PROTECTED_WORKING`.
2. **Replace the Broken Pipe From First Principles**:
- Fix the upstream state transition, invariant, or equation where the corruption originates.
3. **Verify in the Real Environment + Negative Control**:
- Re-run `ra_log_engine.py run` and `ra_log_engine.py audit` to prove:
- `0` `[FAIL]` and `0` `[STUCK]` hops.
- `100%` of `BC-xxx` behavioral contracts hold (`CONTRACT_HOLDING`).
- Run `ra_cheese_audit.py` to confirm zero band-aids or hardcoded lookup branches were introduced.
---
## Phase 6: Cleanup & Self-Learning Record
Before declaring the bug fixed:
- [ ] Original reproduction scenario passes cleanly in `ra_log_engine.py audit`.
- [ ] All `BC-xxx` contracts and `PROTECTED_WORKING` functions remain 100% intact.
- [ ] Record the `Issue : Workflow : Found` triad in `research/SELF_LEARNING.md` (`ra_gate.py learn --issue "..." --workflow "..." --found "..."`) so future sessions never repeat the root-cause pattern.
Pliki w paczce (2)
- SKILL.md 7 KB
- agents/openai.yaml 1 KB
Wersje
W bazie nie ma innych skilli o nazwie ra-systemic-debug.
Migawka bazy z 13.11.2026 · wersja paczki 054b4d5f0a3d (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 92debug
Szuka przyczyny źródłowej błędu przed poprawką, także wtedy, gdy poprawka wydaje się oczywista. - 90debug-to-root-cause
Szuka przyczyny źródłowej błędów i niestabilnych testów przez odtworzenie, izolację i weryfikację hipotez przed poprawką. - 100debug-detective
Szuka przyczyny błędu, awarii lub nieudanego testu na podstawie stack trace'u i naprawia ją u źródła. - 100dte-debug
Szuka przyczyny źródłowej błędu i naprawia ją raz, tam gdzie schodzą się wszystkie wywołania, z powtarzalnym przypadkiem przed i po poprawce; łączy ce-debug, rails-debugger, Augment i AppSignal. - 100v1-debug
Diagnozuje problem, który działa źle, wraca lub pozostaje niewyjaśniony, i szuka przyczyny źródłowej. - 100debug-root-cause
Szuka i naprawia systematycznie przyczyny błędów, awarii i nieudanych testów w JavaScript, TypeScript i Pythonie, zamiast zgadywać poprawkę.