debug-issue

name

debug-issue

description

Drive one PrairieLearn GitHub issue or PR end-to-end through the harness — PRE-FLIGHT → GATHER → SCAN → CLASSIFY → BUILD. Spawns an isolated worktree + Docker journey, reproduces the bug with Playwright, injects the trace spine closest to the suspect code, classifies root cause from the merged timeline, then verifies a fix with before/after evidence. Runs inline. Use when the user says "debug issue N", "repro this PR", "investigate

debug-issue

Orchestrates a full debugging journey for one PrairieLearn issue/PR. One journey at a time — finish and tear down before the next.

Invoke: /debug-issue 12345 · /debug-issue --pr 67890

The five phases (gate between each — no skipping)

1. PRE-FLIGHT — understand before running anything

• ./scripts/spawn-journey.sh --issue N (or --pr N) — creates the journey + worktree + templates. In a self-contained workspace — a PL tree checked out beside the harness plus a local issue.md, with no GitHub number (a clone, or an isolated eval) — run it with no arguments: it auto-detects local mode and drives the in-workspace PL tree from issue.md, with no PL-main or GitHub dependency. run-journey.sh (no args) then targets that same tree. Reach for the network/PL-main path only when the workspace doesn't carry its own source.
• Read the issue and journeys/<id>/reproduction.md. Fill it in: problem, reproduce steps, expected vs actual, root-cause hypothesis, and the ring-0 suspect file(s) — the code closest to the bug. That file is where tracing starts.
• Map the symptom to a PL pattern with reference/architecture-patterns.md (request / question / grading / sync lifecycles — what the code does and its seams), then to an injection layer with reference/control-surfaces.md (where to trace).
• GATE: don't run anything until reproduction.md names a hypothesis and a suspect file.

2. GATHER — make the environment reproduce the bug

• Edit setup.sh to seed the exact broken state (course, users, assessment). Keep it idempotent.
• Confirm the worktree is on the right branch: git -C <worktree> status.

3. SCAN — reproduce empirically at the smallest sufficient layer

• Run it; don't just read it. Fast inner loop: slice isolation (the slice skill) — pull the suspect function/module out and exercise it with instrumented inputs/intermediates/outputs. Outer loop for anything that needs the real system: the booted stack. Either way inject tracing closest to the issue first (the trace skill): ./scripts/inject-trace.sh --worktree <wt> then ring-0 trace() calls in the suspect file. Run, and read the timeline.
• Pick the smallest layer that exhibits the bug: a unit test/snippet with trace calls for a pure function; the rendered page for a UI bug. For a browser case write scenario.ts (journey-run skill: persona, render-gate, screenshots) and ./scripts/run-journey.sh --issue N (containers, seed, before screenshot + merged trace).
• GATE: the run produced evidence — a trace line and/or a broken-state screenshot — that shows the reported failure. If it doesn't reproduce, it may be already fixed on current master (verify at a pre-fix commit) — not necessarily a wrong repro. Reasoning without a run does not pass; if it can't run, fix the harness so it can.

4. CLASSIFY — root cause from the timeline

• Read /tmp/prairielearn-debug/<id>/: screenshots, logs/trace.log (sorted), db-before/after.sql diff.
• tsx packages/dev-tools/src/trace-reader.ts <trace.log> --corr <id> to see one request across Node/SQL/Python and find the stall or the swallowed error.
• If ring-0 didn't reveal it, widen the field (trace skill: --wide / higher ring), re-run. Concentric, not all-at-once.
• GATE: state the root cause in one sentence with evidence (a trace line, a screenshot, a DB diff) before editing code.

5. BUILD — smallest fix in the worktree, verify before/after

• Edit only in the worktree (/tmp/prairielearn-debug-worktrees/<id>/prairielearn/). The write-guard hook blocks edits to PL main.
• Make the smallest change that removes the symptom — often deleting code, not adding around it. Read the neighboring tests first for invariants you must not break. Smallest ≠ partial: retire code the fix makes redundant and keep one source of truth (trace the consumers of any value you change).
• Verify at the layer you reproduced on (re-run the unit test/snippet, or run-journey.sh --variant after-fix for a browser case). Confirm the failure is gone and neighbors still pass. If the fix touches a rendered surface in any way — even for a bug that didn't first look visual — capture before/after screenshots as part of this verification (decide by what the fix changes, not the bug's appearance).
• Red-team your own diff against sibling inputs in the same class before trusting it — and confirm it didn't silently drop a side-effect the old code provided: if your fix removes a broad refresh (a full reload, a redirect, a refetch, a global re-render), every surface that mechanism used to update must still update in its place. Enumerate those surfaces; reason about the ones a narrow repro can't exhibit. If the fix changes a DB query, perf-audit it (plan/cost vs base — no new full scan / lost index / N+1) before trusting it.

Output

A short report: hypothesis → repro → root cause (with evidence) → fix → before/after. Always produce a human-readable fix summary alongside the fix — write fix-summary.md into the artifacts dir: plain-language problem, root cause, what changed and why, and the evidence (trace line / screenshot / test), so a maintainer understands it at a glance. By default, stop here — don't create or post a PR/issue. Publishing the fix is a separate, opt-in step: the contribute skill does it fork-only (never upstream) and only on the user's explicit go-ahead; fix-summary.md is its seed.

Cleanup

./scripts/cleanup.sh --issue N (add --keep-artifacts to retain evidence). Then git -C <PL_MAIN> worktree list to confirm it's gone. Remove trace injection from the worktree with inject-trace.sh --revert if you'll keep the branch.

Reflect (always, last)

Close out with the self-improvement reflex (→ rules/generalize.md): what generalized instruction change would help a future blind agent on an unrelated issue? Apply only what generalizes, adds no contradiction, and leaves the set leaner — otherwise change nothing.