Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

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.

Licencja
MIT
Ostatnia zmiana repozytorium
11.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 11.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

debug thisdiagnosefix this bug
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

  1. Phase 1: Build a Tight Real-Environment .log Feedback Loop
  2. Phase 2: Trace -N to +N Hops & Prove Symptom != Culprit
  3. Phase 3: Formulate 3–5 Ranked Falsifiable Hypotheses & Lock a Hard Stop Rule
  4. Phase 4: Targeted .log Instrumentation
  5. Phase 5: Root-Cause Pipe Replacement (Zero Band-Aids)
  6. Phase 6: Cleanup & Self-Learning Record
Sekcje z nagłówków SKILL.md, w oryginale · 107 linii, 988 słów
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ę.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.