Troubleshooting: Symptom → Meaning → Remedy All Tiers

"A run summary's numbers don't add up"

Symptom: A run reports something like "5 done, 3 failed, 0 hook-failed, 1 blocked" over 8 tasks — but you know one of those "failed" tasks was actually a deliberate block, and the totals don't reconcile cleanly against what you expected.

Meaning: This was a real historical bug class: a blocked task travelling the same code path as a genuine failure got double-counted — appended to the failed bucket and the blocked bucket. Under the current run-exit contract, the four terminal statuses (done, failed, blocked, hook_failed) are a strict partition — every task is in exactly one bucket, and the counts are guaranteed to sum to the total. See Understanding Run Exits for the full taxonomy.

Remedy: If you see counts that don't sum to your total task count, that's worth reporting as a bug rather than working around — it means a task landed outside the intended partition. Don't manually "fix" the arithmetic in your head; the guarantee is supposed to hold.

"My completion record / state.md update didn't land"

Symptom: A task shows as done in the run output, but state.md or the task's completion commit is missing for it — especially in a repo where part of .paircoder/ is gitignored.

Meaning: A single git add over multiple paths fails entirely if any one of those paths is gitignored — so a lifecycle commit that bundles a gitignored file with your task's real changes can silently skip the whole commit, not just the ignored path. This has been a real, repeatedly-hit failure mode.

Remedy: Check whether .paircoder/data or another lifecycle path is gitignored in your project. If your completion records aren't landing, that's the first thing to check before assuming the task itself failed — the code often did land, just not the bookkeeping commit alongside it.

"A task I thought was independent got swept into another task's commit"

Symptom: After a blocked task leaves work uncommitted, a later task's commit unexpectedly includes files from the blocked task too.

Meaning: Committing "everything changed since the task started" by time is fragile — if a prior task's residue is still sitting in the working tree when the next task's commit fires, a naive time-scoped commit can sweep it up. The fix direction is a diff-scoped commit: snapshot the tree at task start and commit only the paths that changed since, plus moving any blocked/failed task's residue to its own labeled side-ref before the next task starts.

Remedy: If you see this, check whether a prior task in the same run ended blocked or failed without its residue being isolated first. Preserved-but-isolated work lives on a side-ref (engage/<task>-blocked or -failed) — that's where to look for it, and it should never require reconstructing it from another task's commit.

"The run says a task 'completed' but something is obviously broken"

Symptom: A task is marked done, but a feature it touched is visibly missing or broken, and test suites related to it are red.

Meaning: Landing code and passing your own acceptance criteria isn't the same as leaving the artifact healthy. A task that commits code but leaves red freshness tests or a red suite it was responsible for should be classified hook_failed, not done — "committed" and "correct" are different questions, and a bare hook_failed count without naming which hook and which task failed makes this class of bug much harder to spot.

Remedy: Look for a named hook + task in the summary before trusting a done status at face value on a task that touched shared infrastructure. If a hook_failed demotion doesn't name the specific failure, that's itself worth flagging.

"Telemetry-based recommendations feel wrong (e.g. every task suggests the same model)"

Symptom: calibration recommend-model or a token estimate seems to converge on one answer regardless of task type.

Meaning: Calibration is only as good as the records feeding it. If most historical records have zero real tokens, an unknown model, or all collapse into one task-type bucket, the "learned" recommendation is really just reflecting that noise back at you. See Trusting Your Telemetry for the full explanation of source provenance.

Remedy: Check the source field on your estimates (bpsai-pair plan estimate --json). If it's mostly default, calibration hasn't kicked in yet — that's expected on a young project, not a malfunction. If it's calibrated but still feels off, the underlying records are worth auditing rather than the formula.