Background Failure Triage

Background Failure Triage

A background failure is information to triage, not a stop signal for unrelated foreground work. Aborting the foreground lane on a background failure wastes the progress you're making on something that doesn't depend on the failed op.

The rule

When a backgrounded op fails OR completes, acknowledge it explicitly:

• On completion (exit 0): note it and reap the result — "Background 'Size of build outputs' completed (exit 0)". A completed background op is information (reclaim done, gate passed); acknowledging it keeps the background state legible and lets you use the result.
• On failure (non-zero exit): note it explicitly — don't let it scroll past unacknowledged — name the failed command and its exit code so the user sees it was noticed.

Then for a failure:

1. Assess independence — foreground depends on background output? No → keep moving; yes → stop and surface blocker.
2. Queue for triage — board note; don't fix mid-foreground-task.
3. Triage at next boundary — read output, diagnose, fix.
4. Surface cumulative failures in the next status report.

Extended: failure-state completeness, deploy batching vs running jobs — reference.md

When to STOP immediately

• The failure is in a destructive op that may have left state damaged (a half-applied migration, a partial deploy). Stop and assess damage before continuing.
• The failure is in shared infrastructure the foreground will soon touch (Postgres down → foreground that's about to hit the DB).
• The failure pattern indicates a fundamental assumption is wrong (a test for code you just edited is failing — your edit likely caused it; the lanes aren't actually independent).

What "queue it" looks like

• On the board: a ◼ (backgrounded) task that failed stays ◼ with a ⚠ note, or moves to a "triage" lane.
• In your response: one line — Background "Run RLS tests in isolation" failed (exit 1) — queued for triage at next boundary.
• In a triage file if the repo keeps one: append the failing command + exit code + a pointer to the output file.

Anti-patterns

• Panic-stop the foreground. Wastes the in-progress work for no reason when lanes are independent.
• Ignore the failure entirely. It scrolls past, you forget, the user finds it red at the end and loses trust.
• Try to fix it immediately mid-foreground. Context-switches you out of the foreground lane and often leaves both half-done.
• Re-run the failed op blindly. A failure deserves a hypothesis before a retry; see shell-confirm-hygiene for repeated-risk commands.

Pair with

• progress-board — the board is where a backgrounded ◼ with a ⚠ lives until triage.
• cost-transparency — a failed background op that already cost 7m should not be blindly retried 5×.
• auto-mode — in auto mode, this skill is what prevents either a panic-stop or a silent ignore.