lv-attend

Files (1)

• SKILL.md

SKILL.md (first lines)

# Attend Role

**`help` / `--help`:** if that is the whole argument, print the `## Usage` block at the end of this file verbatim and stop.

You are the **gate drainer**. The orchestrator parks work whenever it hits a decision that needs a human; your job is to walk the user through that queue and release each item.

This is the one terminal where the human actually has to be. Respect their time: batch the context, ask the question once, act on the answer.

## IMMEDIATE STARTUP

**Name the project before anything else, and keep naming it.** Ids repeat across projects (every one has a `PLN-033` and a `DEPLOY`), and a session is no longer tied to one project's terminal window, so nothing on screen says which project a bare id belongs to. Resolve the name once — the main checkout's folder name, correct from a worktree too:

```bash
basename "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"
```

Then write every artifact id in anything you show the human as `<project> <ID>` (`client-d PLN-033`, `client-b DEPLOY`): the queue heading and its rows, the gate you are working, the question you put, the "N gates remaining" line, and the closing summary. Resolution text passed to `lv-gate-close.sh` stays as it is — the ledger already lives in the project.

**Invoked with an id** (`/lv-attend PLN-123`, `BUG-45`, `BRF-6`, `RELEASE`, `DEPLOY`)? Then this session is for that one artifact — see [One artifact](#one-artifact). A UI that drilled to a plan starts a session this way: coordinator' `lv-rack` launches `claude "/lv-attend <ID>"` in the project from its `t` key (coordinator WFI-007).

Otherwise run this first and display the queue before reading further:

```bash
scripts/lv-exec.sh lv-list-gates.sh
```

Output is tab-separated: `<id>  <gate>  <opened>  <question>  <context>  <blocking>  <state>  <fit>  <qfit>`.

`<blocking>` is how many other incomplete plans cannot start until this gate is answered, and the queue is **ordered by it, costliest first** (ties break oldest-first). A gate at the root of a dependency chain holds everything behind it; one blocking nothing costs only the minute it takes to answer. Present them in the order given — do not re-sort by age.

Render it under a heading that names the project, as a numbered table:

```
**<project> — N gates waiting**

| # | Plan | Gate | Blocking | Waiting | Question |
|-|-|-|-|-|-|
| 1 | <project> PLN-033 | spec-approval | — | 2h | … |
```

Show `Blocking` as a plain count, and `—` when it is 0.

**A row whose `<fit>` is `mismatch` is not answerable as written — say so on the row and handle it first.** The gate outlived the state it was opened in: the plan has moved on, and the role this gate hands work to cannot act from where the plan now is. Mark it in the table (`⚠ stale — plan is <state>`) and treat the decision as *reconcile*, not *answer*:

1. **`mismatch` is the script's verdict, never yours.** Re-run `lv-list-gates.sh <PLN-ID>` and read column 8 immediately before acting. A state you are carrying from anywhere else — a `WORKFLOW STATE` block, a summary, something you read earlier this session — is not evidence, and it is the thing that has been wrong. client-a's WFI-099/100: a rehydration block left over from an earlier compaction said `draft` while the live registry said `testing`; the attendant treated an `ok` row as stale on the strength of it and closed a gate nobody had answered. The daemon then dispatched an unattended tester onto a plan a human was mid-test on, and it destroyed the running container (WFI-102). If the script says `ok`, the row is ordinary work — go to its section below.
2. Read the plan's `findings.md` and `## Review` to establish what actually happened since the gate was opened.
3. If the question has already been settled by that history, close the gate as answered, quoting the evidence *and naming it as prior history*: `lv-gate-close.sh <PLN-ID> "already settled: <what settled it, and where>"`. **Never pass an earlier cycle's outcome as though it were this one's.** The resolution is the record of the decision you just made; a verbatim replay of the last cycle's result records a test run, an approval or an escalation that did not happen, and the ledger has no way to tell it from a real one.
4. If it has not, the gate is on the wrong artifact state — close it and let the skill that owns the plan's current state re-open a gate that fits.

**A row whose `<qfit>` is `stale` carries a question that no longer describes its plan — say so, and do not put it to the human as written.** `<fit>` and `<qfit>` are different failures: `mismatch` means the gate outlived the *state* it was opened in, `stale` means the question outlived the *plan* it was asked about. A row can be `ok` and `stale` at once, and that row is the dangerous one — it presents as ordinary work.

A question is a claim of fact fixed at the moment the gate opened: a verdict, a round count, a test tally. The plan can move while it sits parked, because re-running `lv-gate-open.sh` on an open gate leaves it as is by design. client-b WFI-018: round 1 opened `spec-approval` carrying "Approved with notes (0 Critical)", a second review then found a **Critical** — a restore rehearsal that would have replicated a scratch database into the live production replica path — and the plan was rewritten around three new guards. The parked question still read "Approved with notes". A human answering it would have been approving a sentence, not a plan.

Mark it in the table (`⚠ question is about an earlier revision`) and repair it before asking:

1. Establish what changed — `lv-review-status.sh <PLN-ID>`, the plan's `## Review` and `## Amendments`, and `git log` on the plan folder since the gate's `<opened>`.
2. Re-state the question from the **recorded fact as it now stands** and refresh it in place:
   ```bash
   scripts/lv-exec.sh lv-gate-open.sh <PLN-ID> <gate> "<the question, with the current fact>" \
     --context plans/<PLN-ID>-<slug>/plan.md --skill lv-attend --requestion
   ```
   `--requestion` keeps the original opened-at timestamp and queue position and preserves the old wording in `GATE_QUESTION_PREV`, so the change is auditable. **It is not a licence to re-derive.** Change only the fact that moved on the record; everything else stays word for word. Re-writing a question because you would phrase it better is WFI-180/181/182, and it cost one client-a human five regenerations carrying three errors of fact.
3. Then put the refreshed question to the human, and work the row normally.

If nothing on the record changed — the fingerprint moved on bookkeeping the question never mentioned — say so on the row and ask it as written. `stale` is reported, never enforced; the script compares two hashes and cannot tell which difference matters.

Never route a `mismatch` row to its normal skill. client-a's WFI-082: a `manual-test` gate left over from a fixed bug sat on a plan that had gone back to `draft` with five unaddressed findings, the queue showed it as ordinary work, and the attendant was sent to `/lv-test` — which cannot run on a draft plan. Worse, the unattended tester that had already reached that plan overwrote a human FAIL with PASS on the way past.

**Put the gate's own question to the human. Do not rewrite it, and do not derive a better one from what you can see now.** The question in the gate file is the one the worker asked from inside the evidence; anything you compose in its place is a fresh reading of a codebase that has moved since. client-a's PLN-135 had one `prior-work` question regenerated on each of five re-openings, and the regenerations accumulated errors of fact: three consecutive ones described a `Dictionary` as a `HashSet`, and the fifth asserted a file was untouched by a commit that changes it +22/-8 (WFI-180, WFI-182, WFI-184). The human was being asked to decide on premises no worker had checked. If the question is genuinely stale, that is the `mismatch` path above — reconcile it; do not quietly answer a different one.

A gate that has been answered before carries `GATE_QUESTION` in its resolved record (`lv-gate-status.sh <PLN-ID> <gate>`) — **the text as originally asked**. Replay that rather than writing it again.

### A question you have answered before

Cycle-scoped gates — `needs-input`, `manual-test` — are allowed to re-open by design, and that is where a loop hides. When one re-opens on an artifact that already answered a gate of that name, `lv-gate-open.sh` copies the earlier answer onto the new gate file. Read it:

```bash
grep -E '^GATE_PRIOR_(QUESTION|RESOLUTION|AT)=' .claude/orchestrator/gates/<PLN-ID>.gate 2>/dev/null
```

When `GATE_PRIOR_RESOLUTION` is present, **show it to the human alongside the new question**, in as many words: *"you answered a gate like this at &lt;date&gt; with &lt;resolution&gt; — here is what is being asked now."*

Dedup cannot catch this by itself. Each cycle's wording differs in its specifics — a new worktree sha, the same test count restated — so a literal match sees three different questions where a person sees one. client-a's PLN-204 asked one human the same routing question on three consecutive cycles, each time as though it were new (WFI-203, WFI-204, WFI-205).

**If the human says it is the same question, the answer did not stick, and the fix is upstream of the gate.** Answering it a fourth time buys one more cycle. File a workflow issue with `lv-issue.sh` naming what re-asks it, then answer the gate.

Then, **if the queue has more than one gate**: "Which one? (number, or `all` to work through them in order)", and stop for the answer.

**If it has exactly one, do not ask which.** Show the table so the human sees the project, the id and the question, then go straight to [Working a gate](#working-a-gate) on that row — the `mismatch` and `stale` checks above still come first. A choice between one option is a wasted round trip (operator, 2026-09-23, on a lone `client-c DEPLOY`). The gate's own decision is still put to the human; only the "which one?" is skipped.

If the script exits non-zero, say "No gates open — nothing is waiting on you" and stop. Do not go looking for work; that's `/lv-tray`.

### One artifact

```bash
scripts/lv-exec.sh lv-list-gates.sh <ID>
```

The same row format as the whole queue, for that artifact only — an artifact holds at most one open gate, and the lookup is by number, so `BUG-45` finds the `spec-approval` its plan `PLN-45` opened (WFI-187).

- **Exit 0:** render the one-row table, apply the `mismatch` and `stale` checks above exactly as for a full queue, and go straight to working it — do not ask "which one?".
- **Exit 1:** say "`<project> <ID>` has no open gate — nothing is waiting on you there." and stop. It was answered, or the plan moved on since the caller looked. **Do not fall back to the whole queue:** the caller asked about one artifact, and showing everything else in its place is answering a question nobody asked. Point at `/lv-attend` (no id) for the queue and `/lv-tray <ID>` for where the artifact stands.
- **Exit 2:** the argument is not an id. Say so, quoting it, and stop.

When that gate is answered, the session is done. Say how many gates remain elsewhere (the `GATES: N` line `lv-list-gates.sh` prints on stderr), and do not start on them.

## Working a gate

Once the user picks one, read the gate's `<context>` file if it has one, then follow the row for that gate name.

**Closing the gate is always the last act.** An open gate is what keeps the orchestrator off the plan, so every commit, state transition and file move the decision implies lands *first*, and `lv-gate-close.sh` runs only once they have. Close it early and the dispatcher's very next sweep — up to a minute before your work is committed — reads the plan as free and still in its old state, and launches a worker into the decision you are in the middle of making. That is how client-a got an unattended tester onto a plan already routed back to its planner, which then re-gated it and blocked it entirely (WFI-079). Each row below is written in the safe order; do not reorder it.

**The one gate this reads backwards for is `spec-approval`, and it is not an exception to the rule above — it is the rule met by a different guard.** Closing that gate is a *precondition* of its transition, not a record of one, so both scripts that can perform it refuse until the gate reads answered (`lv-registry-update.sh` on `draft → ready`, WFI-012; `lv-replan-target.sh --apply` on a gating-tagged replan, WFI-021). What the ordering above actually requires is that no window exist in which the plan is unguarded *and* stale — and a claim guards that window exactly as well as an open gate does. So there, and only there, take the claim first and let it cover the gap: claim, close, transition, unclaim.

**If the answer settles a finding, tick the finding in the same breath.** Pass `--resolves "<some distinctive words from the finding>"` (or `--resolves all` when the answer clears every open item) to `lv-gate-close.sh`, and it checks the box and commits it as part of the close. This matters because `lv-findings-route.sh` routes on checkboxes and cannot read your resolution text: a consistency escalation answered here and written up in full still routed PLN-254 back to `draft` on the strength of an empty box, past a clean build and 961 passing tests, and a verify worker had to tick it by hand (WFI-233, WFI-237). When a close leaves unchecked findings behind, the script says so on stderr — read that line rather than scrolling past it.

**If the decision changes why the plan is where it is, say so with `--note`.** `lv-registry-update.sh <ID> <from> <to> --note "<why>"` records the reason in the plan's `progress.md` under `## Notes`, under the same lock and in the same commit as the transition — so a note explaining the state a plan is *leaving* can never survive into the next state contradicting it. PLN-259 reached `ready` still carrying "scope needs re-check before build", an instruction to stop on a row that says go, and the only correction available was a hand edit of REGISTRY.md, which the workflow forbids (WFI-235). The registry has no Notes column and is not where a note goes.

### `spec-approval`

From slicedBread-marc/levain, MIT.

More from slicedBread-marc/levain