bug-drill

name	bug-drill
description	Structured PSCAL/Rea/Aether compiler-bug workflow - reproduce, fix on the current (AST) path, run affected suites against baselines, then ship. Use when given a compiler bug report, a failing repro program, a diagnostic regression, or a chip about a frontend/VM defect.

/bug-drill — compiler-bug work order

The user's proven format, automated. Input: a repro (inline program, file, or chip description). CLAUDE.md carries the environment; do not re-derive it.

1. Reproduce first

• Write the repro to the scratchpad, run it against the CURRENT binary: ./build/bin/<frontend> --no-cache <file> (frontends: aether, rea, pascal, clike, exsh; binaries in build/bin/).
• Capture exact stdout/stderr/exit code. If it does NOT reproduce, check recent commits — chips are often already fixed — and report instead of "fixing".
• Useful probes: --dump-ast-json, --dump-bytecode.

2. Locate on the live path

• Aether: the AST parser (ast_parser.c in components/aether) is the default frontend; grep the diagnostic string there. The translate.c rewriter is gone/legacy — never fix there.
• Rea/Pascal/CLike: shared engine lives in components/pscal-core and components/rea. Respect the dependency chain aether → rea → pscal-core; a pscal-core fix may need coordinated bumps (the /ship skill handles pins).
• Honor any no-touch fences in the work order verbatim.

3. Fix minimally

• Edit in components/<name>/, never build/_deps/.
• VM builtin registry IDs are append-only. NEVER renumber or insert mid-table.

4. Verify against baselines

• Re-run the repro (expect fixed) and a couple of adjacent shapes (the "fixing two-liner broke one-liner" regression class).
• Rebuild: cmake --build build --target <frontend>.
• Run the affected frontend suite(s); compare against the known baselines (memory: pscal-test-baseline lists expected failures). New failures = not done. python3 Tests/run_all_suites.py for wide changes.
• If compiler output-shape changed, check corpus/fixture drift: python3 tools/recapture_expected.py --check (see its --help).

5. Ship

Invoke the /ship flow (component commit → pins → gitlink bump → push → claw deploy verify). If the Aether language surface changed, bump VERSION + CHANGELOG and update the guide docs (aether_for_llms_and_others.md and the concise variant) in the same pass.

6. Report

Root cause in one or two sentences, the fix location (file:line), suite results vs baseline, and what shipped where.