# Background Failure Triage

> When a backgrounded command fails while the foreground lane is making progress, do not abort the foreground lane — log the failure, queue it for triage, and continue. Triage the failure at the next natural boundary. Use whenever a background shell task, background subagent, or parallel lane fails while you're mid-task on something independent.

- Skill: `jcdavis131/background-failure-triage` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jcdavis131/background-failure-triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jcdavis131/background-failure-triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: jcdavis131 (https://skillmd.com/u/jcdavis131)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/jcdavis131/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](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.