follow-up-handling

name

follow-up-handling

description

Use at the END of any task that generated deferred work — the "next steps", "you could also", "want me to…", unfixed-nit, or parked-for-later items. Instead of reciting them at the user (which overloads them — their stated correction), capture each via `harness followup add` and end with a single count line. Also use when the user says follow-ups overwhelm them, or asks to defer/park something. Surfacing the list is always a PULL (/followups), never a push.

Follow-up handling

Follow-ups are real — don't lose them. But reciting them at task-end overloads the user (their explicit correction). Resolve the tension by decoupling capture from surfacing: capture silently, surface only on pull.

The rule

When you finish and notice deferred items — "next steps", "you could also", "want me to…", an unfixed nit, anything parked for later — DO NOT list them in chat. For each, instead:

harness followup add "specific, self-contained, actionable one-liner"

Then end your message with at most ONE line, only if count > 0:

Logged 3 follow-ups (`/followups` to review).

That is the entire surfacing. No "Next steps" section, no "let me know if you want me to…", no re-pitching the deferred work. Zero follow-ups → say nothing.

What is / isn't a follow-up

• Yes: deferrable work the user did not ask for now — cleanups, hardening, a related fix, a verification to run later, an optional enhancement.
• No — ask directly instead: a blocking question you need answered to finish the CURRENT task. That is not a follow-up; surface it now.
• No — just do it: work the user actually requested.

Write them to survive

Each entry must stand alone weeks later: name the file/symbol, the concrete change, the why. "Fix the thing" is useless. "Add templates to the guard BLOCKED-message parenthetical in hooks/guard_enforcement_layer.py" is actionable.

Decay is the point, not a bug

Open follow-ups older than 30 days drop out of the active count automatically (harness followup, TTL). The ledger is a holding pen, not a debt you owe. The user closes items freely (harness followup done <id>) — doing them is optional. Never nag about open follow-ups; the count line and /followups are the only surfacing.

Surfacing is pull-only

The user runs /followups when THEY want the list. You never push it. (A quiet SessionStart count — a number, never the items — may be added later as opt-in.)

provenance: session 56295237, 2026-06-13 — user reported every AI session ends with follow-ups that overload them; routed to capture-silently / surface-on-pull.