# Respond / pending detail

Detail for SKILL.md Workflow **step 1 (Respond)** and **step 1b (Update
pending)**. The spine in SKILL.md keeps the reconcile-oldest-first rule, the
`### Re:` header + model-attribution format, and the pending granular-flags-only
rule. This runbook carries the rest.

## Step 1 — Respond

- Address the user's changes naturally in the console; that response is the
  document response.
- Reconcile the changed exchange tail oldest-first. Do not stop at the newest
  question; answer or group each unresolved prompt in that tail and each
  unresolved `prompt_target`; treat `content_edit` items as user corrections.
- **Realtime steering (`#realtime-steering-verbatim`):** a document is realtime —
  the operator may add a prompt WHILE your turn is running. Every item the
  operator adds must be addressed and worked on, never committed-and-ignored. If
  `session-check` reports a committed cycle plus a fresh operator prompt, that is
  realtime steering, **not** a failed closeout: your prior response is already in
  HEAD. Address the surfaced prompt (the binary hands it to you **verbatim**) in
  your current turn — continue with `agent-doc <FILE>`. Do NOT re-run respond/finalize on
  the prior response, do NOT `--force-disk` (it clobbers the operator's live
  edits), and do NOT re-answer a prompt already committed in HEAD.
- If session-accretion supplies bounded context, use the included `### Re:`
  blocks as prompt-position anchors, not proof that older turns are absent.
- Execute from the planning record. If `execution_scope=plan_backlog_only`, stay
  in plan/backlog capture mode. Otherwise complete the requested repo work before
  persistence or stop on a blocker. Do not keep appending "starting/continuing"
  status prose while the requested work remains undone.

**Draining a free-text queue head — quote it (`#qdeferstrike`).** When you answer a
free-text queue prompt (a queue head with **no** `#id`), quote it verbatim as a
`> **Queue prompt:**` blockquote at the top of your response. The position-
independent strike (`#ftstrike` / `strike_answered_free_text_queue_heads`) matches
the head's prose against your response's **blockquote** region — a `### Re:` heading
alone is normally not enough, so a heading-only answer leaves the head queued and
the loop churns re-answering it forever. The narrow historical-recovery exception
is a heading that repeats the head's same long underscore-delimited code identifier;
ordinary prose topics, filenames, and short symbols do not qualify. This matters
most when the free-text head sits
*behind* a deferred `[operator-verify]`/`[focused-cycle]` id-head: the leading
consume stops at that deferred id-head, so the **only** path that can strike the
free-text item is the blockquote-matched `#ftstrike`. `do [#id]` heads are
different — they strike by id via `--done <id>` regardless of position and need no
quote.

An in-progress marker on a free-text head records selection, not completion
(`#bugautostruck`). It never replaces the exact `> **Queue prompt:**` evidence.
If the response does not actually quote and answer that head, closeout must leave
it active even when the marker was added earlier in the cycle.

**Already-complete or backlog-tracked free-text heads auto-strike (`#qftbklgstrike`).**
Separately from the exchange-answer strike above, preflight queue maintenance
auto-strikes a live free-text head when a deterministic scorer proves the work is
already captured elsewhere — either it is already complete (a matching `agent:done`
item) or a backlog item already addresses it (a matching active `agent:backlog`
item) — even with no exchange answer for it. The head is struck in place and
annotated `— auto-struck: completed by #<id>` or `— auto-struck: tracked by backlog
#<id>`; it is never deleted. The match must clear a conservative threshold (a near
restatement of the tracked item), so an unrelated operator prompt is never struck:
you do not need to do anything to trigger or avoid this — a genuinely unanswered,
unrelated head always survives. id-backed heads are unaffected (they strike by id).

The `#ftstrike` pass is **conservative about in-flight edits (`#qstrikeexplain`)**: it
strikes a free-text head only when that head was present in the stable pre-turn
baseline (the preflight baseline). A head that first appeared in the live buffer
*this* turn — a line the operator is still typing — is **never** same-cycle struck,
even if it happens to fuzzy-match a quoted prompt; it defers to the cycle that
actually answers it (editor-wins, consistent with `#queue-user-edit-overwrite`). So
quoting a queue head you did not intend to drain cannot strike a line the operator
is mid-authoring.

**Response header format (template mode):** use `### Re: topic` markdown headers —
**not** bold (`**Re:**`). The `(HEAD)` boundary marker requires real headings. Use
h4–h6 for sub-sections within a response.

**Model attribution:** always append the resolved model short name with a spaced
em dash: `### Re: topic — gpt-5` or `### Re: topic — opus-4-6`. Use
`preflight.agent_model` if non-null (from frontmatter); otherwise use your own
model identity. Never use the harness label (`codex`, `claude`) as the suffix, and
never omit it.

**Response checkpoints and sealing:** stream incomplete progress only to the
harness console. A standalone conclusion that remains useful before closeout may
be written with `agent-doc salient-checkpoint <FILE>`. The binary structurally
validates the complete Markdown body and upserts one cycle-scoped
`Live response (not final)` node. It is not answer evidence and does not consume
queue/backlog work or commit. After each complete `### Re:` section (balanced
fences and component markers), the harness may persist the cumulative response
with `agent-doc response-checkpoint <FILE>`. The binary replaces the
uncommitted response tail in Lazily; it does not consume queue/backlog work or
commit. A final response removes any live-response node for the cycle.
Turn-end `agent-doc respond` asks the binary to resolve those closeout mutations
and commit exactly once (`finalize` remains an alias). See
[streaming-checkpoints.md](streaming-checkpoints.md).

**`#agent-doc-bug` plan proof:** if the prompt contract requires a plan, create
the plan file before closeout and cite every plan path. If
`execution_scope=plan_backlog_only`, create plan/backlog items and explain the
deferred implementation boundary instead of editing code.

## Step 1b — Update backlog (template mode)

Mutate `<!-- agent:backlog -->` (or legacy `agent:pending`) only through granular
`agent-doc write` flags: `--backlog-add`, `--done <id>`, `--backlog-edit
"id=text"`, `--backlog-reorder`, `--backlog-gate`, `--backlog-ungate`,
`--review-add`, `--review-edit`. Full-replace via `<!-- patch:backlog -->` /
`<!-- patch:review -->` is rejected; see [pending-ops.md](pending-ops.md). For
`<!-- agent:icebox -->`, use granular `--icebox-add*` flags.

Completed/reaped items live under canonical `<!-- agent:done -->`; legacy
`agent:backlog-done` and `agent:pending-done` tags require `agent-doc migrate`.

**Backlog capture rule:** if the response creates concrete follow-up work, add it
to `agent:backlog` in the same cycle. Put new items at the beginning of
`agent:backlog`; if you are extending an ordered batch already in backlog, insert
the new item adjacent to its predecessor. If the item is only a recommendation,
include `[recommended]`.

**Cross-document backlog rule:** if a prompt preset or user instruction names
another backlog file, add the item to that target with `--backlog-add-to
<target-file> "<item>"` on the final `agent-doc respond` command. Do not satisfy
an explicit target by running `--backlog-add` against the current session
document. If the target is missing or lacks a backlog component, stop on the
binary error and report the blocker.

**Plan-backed backlog items:** create the plan file first and include that exact
plan file path in the backlog text. For multi-phase implementation work, prefer
one backlog ID per actionable phase (for example `#crdtrespfx1`, `#crdtrespfx2`)
instead of one parent ID that gets repeatedly `--backlog-gate`d after partial
progress; keep the parent plan file as context, but queue and close out concrete
phase IDs.

**`do #id` closeout rule:** when the user directs `do #id ...`, record the backlog
outcome before persistence: `--done <id>` if completed, `--backlog-gate <id>` if
code-complete but awaiting review/external validation, or explain concretely why
it stays open. `session-check` enforces the `pending_done_guard`; projects may opt
into `review_done_guard` when review must precede done.

**Complete over gate.** Default to `--done` — finish the work this cycle. Gating
to `agent:review` is exceptional, only for work genuinely blocked on something the
turn cannot do (live editor/pane verify, external approval, CI outage), and the
item must name what unblocks it. Unblocked follow-up goes to `agent:backlog` as an
actionable item, not `agent:review`. Keep `agent:review` small (target < 10);
convert stale/satisfied gated items to `--done` or actionable backlog items rather
than letting them accumulate. See [pending-ops.md](pending-ops.md) for the full
review-discipline rule.
