Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

debugging-difficult-bugs

/debugging-difficult-bugs

Dodaje do prawdziwej ścieżki kodu tymczasowe logowanie JSONL, odtwarza błąd, czyta log i dopiero naprawia, gdy samo czytanie kodu nie wystarcza, na przykład przy stanie runtime, kolejności, cache, strumieniach i współbieżności.

Repozytorium
carbon ↗
Licencja
AGPL-3.0
Ostatnia zmiana repozytorium
27.10.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
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

Co robi i kiedy

Dodaje do prawdziwej ścieżki kodu tymczasowe logowanie JSONL, odtwarza błąd, czyta log i dopiero naprawia, gdy samo czytanie kodu nie wystarcza, na przykład przy stanie runtime, kolejności, cache, strumieniach i współbieżności.

Oryginalny opis (EN)

Runtime-instrumentation debugging for bugs that static reading can't pin down — add temporary unconditional JSONL logging to the real code path, reproduce, read the log, then fix. Use when /root-cause lands at MEDIUM/LOW confidence, when a bug involves runtime state, ordering, caching, streaming, concurrency, or manual/UI reproduction, or before a second speculative fix. Skip when a stack trace or a deterministic failing test already proves the cause.

Jak działa

  1. Step 1: State the uncertainty
  2. Step 2: Add temporary unconditional instrumentation
  3. Step 3: Reproduce the real issue once
  4. Step 4: Read the log BEFORE fixing
  5. Step 5: Clean up — mandatory
  6. Done when
Sekcje z nagłówków SKILL.md, w oryginale · 92 linii, 581 słów
Podgląd SKILL.md
---
name: debugging-difficult-bugs
description: Runtime-instrumentation debugging for bugs that static reading can't pin down — add temporary unconditional JSONL logging to the real code path, reproduce, read the log, then fix. Use when /root-cause lands at MEDIUM/LOW confidence, when a bug involves runtime state, ordering, caching, streaming, concurrency, or manual/UI reproduction, or before a second speculative fix. Skip when a stack trace or a deterministic failing test already proves the cause.
---

# debugging-difficult-bugs — instrument, reproduce, read, then fix

Core idea: when you can't see the failure by reading code, **make the runtime
tell you**. Add temporary append-only JSONL logging along the real code path,
reproduce the real issue once, read the log chronologically, and only then fix.
Never make a second speculative fix without new runtime evidence.

**Announce at start:** "Using the debugging-difficult-bugs skill — instrumenting
the runtime path to observe the failure."

## Step 1: State the uncertainty

Write down: what you believe, what you can't verify statically, and the exact
runtime path that must be observed (route → service → query, posting, job).

## Step 2: Add temporary unconditional instrumentation

Rules:

- **Unconditional** — never gated behind an env var, debug flag, or log level.
  If reproduction requires remembering to set a flag, it will silently not fire.
- **Append-only JSONL**, one JSON object per line, to a file in the process's
  working directory.
- Log **boundaries and decisions**, not every line: function entry/exit, branch
  decisions with the data that caused them, state before/after mutation, async
  ordering markers, caught errors, return-value shapes.
- Log **shapes, not payloads**: ids, keys, counts, statuses. Never log tokens,
  auth headers, cookies, or full user content.

```ts
import { appendFileSync } from "node:fs";
import { join } from "node:path";

function debugBug(event: string, data: Record<string, unknown> = {}) {
  appendFileSync(
    join(process.cwd(), "debug-difficult-bug.jsonl"),
    `${JSON.stringify({ ts: new Date().toISOString(), event, ...data })}\n`
  );
}

debugBug("service.beforeUpdate", { id, companyId, status: row.status });
```

**Carbon multi-process note.** The ERP and MES dev servers and the Inngest
handlers run as separate processes with different working directories;
postings (the ERP modules' service files) run in the ERP process, also when the
MES calls them (over HTTP, `erpPosting`). Log `process.cwd()` + a process role once at startup, or use distinct
filenames (`debug-erp.jsonl`, `debug-jobs.jsonl`). The Docker `edge-runtime`
container only hosts the `embedding` edge function; there,
`console.error` JSON lines (visible in container logs) stand in for a file.

## Step 3: Reproduce the real issue once

- Prefer reproducing yourself: boot the stack (`crbn up` if not already
  running), authenticate with `/auth`, and drive the exact failing flow with
  `agent-browser` (the `/test` skill documents Carbon's form gotchas —
  `requestSubmit`, react-aria blur).
- If only the user can reproduce (their data, their environment), tell them
  exactly: "I added temporary logging. Reproduce the issue once, then point me
  at `<cwd>/debug-difficult-bug.jsonl`."

## Step 4: Read the log BEFORE fixing

Read chronologically and answer, in writing:

1. Did the instrumented path actually run?
2. What was the expected sequence of events?
3. What was the actual sequence?
4. What is the **first** point where state/order/branch diverges from expectation?

That first divergence is the root cause candidate. Feed it back into the
root-cause brief (or write one now) — then implement via `/fix`, whose failing
regression test must assert the *actual* divergence you observed, not your
earlier assumption.

## Step 5: Clean up — mandatory

- Remove every temporary log call, helper, and import.
- Delete generated `.jsonl` files.
- Check the final diff explicitly for leftovers:
  `git diff | grep -n "debugBug\|debug-difficult\|\.jsonl"` → expect no hits.

The final diff contains only the fix and its tests.

## Done when

- [ ] The first divergence point is identified from log evidence (quote the lines)
- [ ] The fix landed via `/fix` with a red→green regression test asserting that behavior
- [ ] Reproduction of the original flow now passes
- [ ] Zero instrumentation remnants in the diff

Wersje

W bazie nie ma innych skilli o nazwie debugging-difficult-bugs.

Migawka bazy z 13.11.2026 · wersja paczki 29dfcb17666f (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

  • 90fix-issue
    Naprawia zgłoszenie z GitHuba: odtwarza błąd, znajduje przyczynę, poprawia kod i dodaje test regresji.
  • 100fix
    Naprawia błąd metodą test-first: pisze padający test odtwarzający błąd, znajduje przyczynę źródłową, poprawia i dodaje test regresji.
  • 100root-cause-debugging
    Szuka przyczyny źródłowej przed zmianą kodu: odtwarza błąd, czyta pełny komunikat, testuje jedną hipotezę naraz i po trzech nieudanych poprawkach zatrzymuje się.
  • 100tdd-bug-fix
    Naprawia błędy w cyklu red-green-refactor: najpierw odtwarza błąd jako padający test, potem go naprawia, żeby błąd nie wrócił.
  • 90systematic-debugging
    Odtwarza błąd, stawia hipotezę i dowodzi przyczyny przed zmianą kodu, a potem robi minimalną poprawkę z testem zabezpieczającym.
  • 100tdd-fix
    Naprawia błąd test-first: pisze padający test odtwarzający błąd, szuka przyczyny źródłowej, poprawia kod i dodaje test regresji.

Uwagi i zgłoszenia

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