Run any Skill in Manus with one click

debug-issue

Stars0

Forks0

UpdatedJune 7, 2026 at 15:01

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

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

adam-s

adam-s/prairielearn-debug

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software Quality Assurance Analysts and TestersComputer and Mathematical Occupations·SOC 15-1253

SKILL.md

readonly

name

debug-issue

description

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.

More from this repository

same repository

contribute

adam-s/prairielearn-debug

Find a real upstream PrairieLearn bug with no open PR, reproduce + fix it in the harness, and publish it as an issue + pull request ON THE USER'S OWN FORK (never upstream) — packaged as a human-readable proposal a maintainer could copy over. Wraps debug-issue with a discovery front-end, a dual-test proof (PL's own tests + harness evidence), and a fork-only SHARE phase. Runs inline. Use when the user says "contribute a fix", "open a PR on my fork", "propose a fix to PrairieLearn", "find an issue to fix and PR it", or "/contribute".

2026-06-080

journey-run

adam-s/prairielearn-debug

Drive a PrairieLearn Playwright journey — persona switching (student/instructor/admin), render-gating (never screenshot a blank/500 and call it fine), numbered before/after screenshots, socket-safe waits, and cold-vs-warm diffing. Spins the journey's containers, runs scenario.ts, captures evidence. Runs inline. Use when the user says "run the journey", "run the scenario", "screenshot this flow", "drive it as instructor/student", "check for regressions across personas", or after editing a fix to re-verify.

2026-06-070

slice

adam-s/prairielearn-debug

Isolate one file/function/module and exercise it in isolation with full observability — instrument its inputs, intermediate values, and return with timestamped trace logs (Python or TS/JS), drive it with crafted cases, and assert expected results. The fastest empirical layer: between forbidden static reasoning and a full Docker/Playwright boot. Drives a tight Observe→Orient→Decide→Act loop. Runs inline. Use when the bug lives in a specific function/module, the user says "isolate", "exercise the slice", "test it in isolation", "instrument inputs/outputs", or when the full stack is overkill or won't boot.

2026-06-070

trace

adam-s/prairielearn-debug

Add precise timestamped debug logging across PrairieLearn using the concentric/adaptive model — start at the code CLOSEST to the issue (ring 0), read the merged cross-process timeline, widen the field only if the narrow ring didn't reveal it. Covers the TS⇄Python boundary, SQL, sockets, and the zygote via @pldebug/trace. Runs inline. Use when the user says "add logging", "trace this", "instrument", "where is time going", "why is this swallowed", or when debug-issue reaches CLASSIFY and the cause isn't obvious.

2026-06-060

tune

adam-s/prairielearn-debug

Run one eval-driven instruction-tuning iteration on the harness itself. A blind sub-agent solves a CLOSED PrairieLearn issue (no access to the merged fix or this conversation), a blind judge compares its answer to the accepted PR, and you diagnose where the harness/.claude failed it and apply GENERALIZED improvements. The product is the instructions, not the PL fix — the code is thrown away. Runs inline (parent-orchestrated). Use when the user says "tune", "improve the harness", "run an eval iteration", "look back how can we improve .claude", or after picking a closed-issue case.

2026-06-030

red-team

adam-s/prairielearn-debug

Adversarial bug-hunting review of a PrairieLearn diff, PR, or worktree change — hunts REAL bugs (not style) in the seams where PL breaks: the TS⇄Python code-caller boundary, zygote serialization, SQL/Drizzle edge cases, assessment/grading state, socket event isolation, auth/CSRF, and migrations. Severity-grouped findings with file:line, each with a concrete trigger. Read-only, runs inline. Use when the user says "red team", "bug hunt", "adversarial review", "what could break", or before posting a fix to a PR.

2026-06-020

name

debug-issue

description

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.