coral-debug

name

coral-debug

description

Verify and debug changes to CORAL itself — smallest reproduce loop per area (grader / daemon / CLI / hooks / manager / workspace / hub / template / config / web), where to look when something breaks (hung graders, agent restart loops, stalled agents, missing heartbeat actions, corrupted shared state, broken worktree symlinks, grader import errors, wrong-task resume), how to inspect a live or finished run under `.coral/public/`, and the canonical lint/test commands. Use when editing code under `coral/` or chasing a CORAL bug, NOT when adding a new task or extending the framework.

CORAL debug & change-verification workflows

This skill is for people (and Claude Code) hacking on the CORAL package itself, not for users authoring a task. For authoring guides see the siblings:

• coral-new-task — creating a new examples/<task>/ (seed + task.yaml + grader)
• coral-extend — extending CORAL itself (new runtime, new CLI command, new bundled skill, ...)

Reproduce loops

Pick the smallest one that exercises your change.

Editing...	Fastest reproduce
coral/grader/{task_grader,loader,subprocess_grader}.py or a builtin grader	uv run coral validate examples/circle_packing (or any example with a packaged grader)
coral/grader/daemon.py (parallel grading, queueing, worktree isolation)	uv run pytest tests/test_grader_daemon.py -v
coral/grader/{base,protocol}.py	uv run pytest tests/test_grader.py tests/test_subprocess_grader.py -v
coral/cli/*.py (argparse, dispatch, output formatting)