/afk-debrief

The run is over. This skill reads what it left behind, says why each ticket is not green, and proposes what to fix before relaunching.

A red is not a verdict on the ticket: the gate may have been wrong, the worktree badly seeded, the model unavailable. Sorting that out is the whole job.

1 — The summary

cat .afk/summary.md

No file → no run made it to the end; go to .afk/<n>.out. The file's own legend explains its columns.

2 — Read the run before the tickets

Four things are read on the whole, and a single one of them can explain every red at once:

And one warning: a 100% green rate means nothing if the gate verifies nothing. The tickets marked ⚠ had a local gate replaced by their Verify: line — on a repo that has CI, only CI ran the repo's complete gate; without CI, nobody ran it.

3 — Sort each non-green

For each ticket that is not green, the worker left the cause in .afk/<n>.status (reason=), and the detail is in a specific file:

cat .afk/<n>.status          # result, reason, session, model, cost
cat .afk/<n>.out             # the orchestrator's trace for this ticket

4 — Read the journal, then ask the session

Each session keeps a decision journal, appended as it goes, at .afk/<n>-work.tsv: six tab-separated columns — ts, phase, decision, why, evidence, result. afk.sh asks every ticket for it, and build_prompt holds the contract.

column -t -s $'\t' .afk/<n>-work.tsv          # one red
grep -H . .afk/*-work.tsv | head -40          # the whole run at a glance

Read it before judging a red: it holds what no trace contains and what the diff cannot show — the hypothesis taken because nobody was there to decide, the option ruled out and what ruled it out, the red gate and what the session concluded from it, the premise that turned out false, anything done outside the ticket's scope. A result of ko or abandoned on a line whose evidence says none is the signature of a session that guessed.

No file → the session never wrote one. Note it as an afk defect (step 7) if it happens across a whole run: the instruction is in the prompt, so it is the prompt that failed.

Only then, and only if the journal is silent on the point you need, get back into the session that produced the red — the summary gives what it takes:

(cd .afk/wt/<n> && claude --resume <id>)

Useful when the failure is a design choice, useless when the environment was broken — in that case the answer is in .afk.env.

5 — Wrong gate or real failure

A ko / verify does not yet say whose fault it is. The red ticket's worktree is kept, dependencies installed:

cd .afk/wt/<n>
git log --oneline origin/<base>..HEAD      # what the agent produced
<the ticket's gate>                         # rerun it by hand
git stash list; git status                  # what it left hanging

Then compare what the gate complains about with what the agent touched:

git -C .afk/wt/<n> diff --name-only origin/<base>..HEAD

The gate complains about files absent from that list → it is the environment or the gate, not the ticket: the worktree does not have what it needs, or the gate is wider than the scope. It complains about files from the list → real failure, and <n>-fail.txt says which one.

Decide in the worktree as it is: resetting it onto the base destroys the state of the failure, which is exactly what you came to read.

6 — Decide, then propose

A table, one ticket per line: relaunch as-is / fix the gate then relaunch / re-slice / take it by hand, each with the reason in one line.

Then the actions, ready to paste — the exact label names are in docs/agents/triage-labels.md:

gh issue edit <n> --add-label <ready-for-agent> --remove-label <ready-for-human>

A ticket to re-slice gets named as such; /afk-preflight step 5 cuts it.

Propose, wait for approval, relabel nothing unprompted. A ticket put back to ready-for-agent starts again the next night: it is a run decision.

7 — Record what is an afk defect

afk's repo is mounted in every project: it is the only place that spans the runs and the projects. RUNS.md already receives each run's facts, appended by afk.sh. What needs judgement goes into docs/defects.md, and you are the one who puts it there.

The path is the script's, not the project's:

d=$(dirname "$(readlink -f "$(command -v afk.sh || echo ./afk.sh)")")
tail -40 "$d/docs/defects.md"      # the format of an entry
grep -h '^## ' "$d"/docs/defects*.md | tail -3   # the last number taken (the archive carries it)

The sorting is the whole job. Only write in what would have broken the same way on any repo: the orchestrator, the worktrees, the gate, the prompt, the parent/child protocol. A flaky test, a badly tuned .afk.env, a badly sliced ticket are project problems — they get fixed over there and have no business in this register.

An afk defect is recognised by one thing: the trace blames the wrong culprit. A healthy ticket marked red, a freeze with no real blocker, a green that compiled nothing, a ticket burning its attempts for a reason that is not its own.

Next number — the highest in docs/defects.md and docs/defects-fixed.md, plus one; a defect already there gets an "Again" paragraph, not a new number. Verdict in the title (fixed if you already have the fix, open otherwise), and three paragraphs: what was seen, the cause, what was done about it. An entry is written in docs/defects.md, which only keeps the live defects; a fixed defect goes into docs/defects-fixed.md, and one that a later fix closes moves there as-is, keeping its number. Then show the entry you wrote. Unlike tickets and PRs, you do not wait for approval on this one: a defect that is not recorded comes back, and gets re-diagnosed from scratch.

Nothing to record is the normal case.

8 — Cleanup

Red worktrees are kept on purpose. Once the ticket is understood:

git worktree remove --force .afk/wt/<n>

Until then they hold the exact state of the failure, node_modules included.