Agent Skills: Skill: Diagnose a Red Run

Skill: Diagnose a Red Run

Capture the branch failure

• Record the exact command, commit SHA, exit code, and passed/failed/skipped counts. Quote the first actionable failure; do not summarize it away.
• Classify the check: testkit spec, typecheck, build, lint, or CI job.

Run a clean control

Never call a failure pre-existing from memory or from a modified checkout.

git fetch origin dev
git worktree add /tmp/openwork-dev-control --detach origin/dev
# In that clean worktree, prepare the same prerequisites and run the exact command.
git worktree remove /tmp/openwork-dev-control

• Keep tool versions, environment, services, flags, and secrets equivalent.
• Quote the control command, origin/dev SHA, exit code, counts, and matching failure text.
• Classify as pre-existing only when the clean control demonstrates the same failure. Otherwise classify it as introduced, environment-specific, or unresolved. A non-reproducing control is not proof of flakiness; repeat both sides before using that label.

Classify by signature

• Unit/type/CI-only failure: inspect the first failing job and run its exact command locally before broadening scope.
• Vision disagreement on identical pixels: claim wording or product ambiguity. Make the product unambiguous or make the claim factual.
• Timeout with an On-screen dump: read it. It names the state; for example, /session can expose a steer-back race.
• Auth 403 INVALID_ORIGIN: inspect Den trusted origins.
• Authorize URL points at the real provider: Den booted without mock env.
• Teardown 403 fresh_auth_required: the session aged; a freshSession retry exists.

Red core journey (pr-proof.yml "Core journey")

• Open the job summary's "Freestyle world" table first: it names the path (reused, fast, full build) and its reason.
• World preparation failed: read the "builder log" group in the job log; it is the VM's own build or boot output. A fast path that fails falls back to a full build by itself, so a red here is a real build or boot failure.
• Journey failed: the timeout prints the on-screen state. Reproduce with the run-tests core journey command on the same pushed commit.

Environment forensics

• Kill by port, not process name. tsx watch can orphan its Node child, which keeps the port while /health lies.
• EADDRINUSE in logs while health returns 200 means a zombie survived.
• Electron zombies can respawn from a root process; kill the process group.
• Leaked state pollutes organizations; delete leftover connectors between runs.

For a testkit failure, read the test run's last unvalidated artifacts before touching code. Name the verdict as CI posted it: Passed only when every claim has an observable assertion; a skip or a pending looks() judgment is Incomplete, never Passed. Red evidence is useful evidence; never soften or omit it.