wjgoarxiv/antigravity-swarm/debugging

debugging

A bug is fixed when the surface that showed it behaves correctly and a test fails without the fix in place. This skill walks from symptom to that state through a hypothesis loop, and every step leaves a file in the evidence folder.

Two disciplines hold for every language, every runtime, and whether or not you have source:

1. Runtime truth beats code reading. Every claim about why the bug happens rests on an observed value, read from the running system. A plausible story built by reading code is a hypothesis, and a hypothesis is not a cause.
2. Leave only the fix behind. Debugging creates artifacts: log lines, breakpoints, scratch scripts, env overrides, proxies, patched files. Write each one into a journal before you create it, and remove it before you call the task done.

This file is the map. The procedure, the per-runtime recipes and the specialist tools live in references/, and those files are part of the skill. Read the one that matches the phase or runtime you are entering, in this session, before you run a command from its domain.

When this applies

• A test fails, a command exits non-zero, a page renders wrong, a process hangs, output is silently empty, a request returns 200 with an empty body, or timing differs between runs.
• The user says "debug", "why does X fail", "this broke after Y", "trace this", "attach a debugger", "set a breakpoint", "reverse engineer this binary", "inspect the bundle", or "reproduce and fix".
• A lit route (lit-loop, litwork, start-work) hits an unexplained failure mid-task. Read ../debugging/SKILL.md with read_file from the calling skill's folder, finish the loop, then return to the route that called you.
• The target is a binary without trustworthy source (a closed library, a vendored artifact, a CTF challenge, firmware, a packaged app), where static plus dynamic analysis stands in for reading source.

For a known one-line typo with an obvious fix, a full loop is overhead. Fix it, run the failing command, record the output, stop.

Inputs and state

• The symptom in the user's words plus the exact failing command, URL, or input. When either is missing, derive it from the repo (the test script, the README) before you ask.
• A slug for this bug, such as null-config-crash. Evidence goes to .litgravity/evidence/<slug>/; the journal is .debug-journal.md at the repo root, or inside the evidence folder when the repo must stay clean, and it is listed for removal at cleanup.
• A goal record in .litgravity/goals/<slug>.json, when one exists: attach the fix as evidence on the matching criterion.
• The active ledger .litgravity/ledger/<conversation-id>.jsonl: recent tool events show the last edits before the break, which are the first suspects. The activation note names the active route and the ledger path.
• AGENTS.md and the package scripts name the test runner, the lint gate and the type gate. Run those commands, not guesses.
• The runtime. Identify it before anything else (see the runtime table below); the matching reference is required reading before you attach or launch anything.
• Diagnostics come from the command line, not from a language-server tool. Run tsc --noEmit, pyright --outputjson, ruff check, go vet, or cargo check --message-format=json through run_command. The lsp skill (read_file on ../lsp/SKILL.md) owns the language-server surface; read it when type or lint output is the main evidence.
• Supporting files sit in this SKILL.md's folder (the activation note gives its absolute path) and are read on demand with read_file: the phase procedures under references/methodology/ (named in the phase table below), one runtime recipe per language under references/runtimes/, and one specialist-tool recipe each under references/tools/. references/methodology/partial-runtime-evidence.md covers the case where the real operation cannot run, plus a late skeptical review for extraction and audit work.

The reference gate

Most of what you need lives in references/. Skim this file and start working, and you will attach a debugger the wrong way, miss a silent-failure pattern you have not seen, lose an hour to a source-map gotcha, or reinvent a worse version of a tool that already solves the problem.

Gate rule: before you run a command from a reference's domain, read that reference in this session (read_file on <skill-dir>/references/..., where <skill-dir> is the folder of the SKILL.md path the activation note gave you). Re-reading across sessions is cheap; guessing is expensive. "I know this language" is no exemption, because every runtime and every specialist tool has at least one gotcha that quietly costs hours.

Runtime setup: read before attaching

Native versus bundled, in thirty seconds: file ./target calls both Mach-O or ELF. Run du -h ./target (50 MB or more is suspect) and strings -n 12 ./target | rg -iE 'bun|node_modules|webpack|esbuild|deno|pkg/lib|electron|pyinstaller|nexe|NODE_SEA_FUSE|tauri'. Hits mean bundled; a clean result means native.

Specialist tools: use them in their domain

Skipping a tool in its domain is a process failure. A browser bug "verified" without a browser, or a stripped binary read through xxd, does not count. When the tool is missing and run_command can install it into the engine cache or the project allows an install, install it and say so; otherwise record BLOCKED: <tool> missing, give the user the install command, and continue with the nearest installed substitute, labelled as weaker evidence.

Procedure

The phase loop

Each phase has one reference. Read it as you enter the phase, from the file, not from memory.

Cross-cutting references, read when the situation calls for them:

The loop, step by step: