loopx

# Task: Drain a `.pm` workstream item by item `/loopx <wN>` — repeatedly pick the next **open item** in workstream `<wN>` — a pending milestone `wN/mN/` **or** an open inbox note `wN/NNN.md` (a sub-hour task) — **triage** it, then give it one of four outcomes: **work it and move it to `done/`**, **close it as already met**, **move it to `blocked/`**, or **delete it as invalid**. Continue until the workstream has no open items left. This is a long-running autonomous loop over the `.pm` board; it composes `/pm` (board reads/writes), your own implementation work, and `/ship`. Parse the target workstream from `$ARGUMENTS` (e.g. `w1`). If `$ARGUMENTS` is empty, **STOP** and ask which workstream to drain — never guess. ## Preconditions (verify once, up front) 1. `git branch --show-current` is `main`. If not, STOP and ask (same rule as `/ship`). 2. `git status` — note pre-existing uncommitted changes, then keep going. Do not sweep unrelated changes into an item's ship: stage files by name, never `git add -A`. - **Uncommitted `.pm` board work is never a reason to stop.** Teammate sessions file milestones and notes into the same workstream continuously, often mid-run; that is a queue refresh, not a dirty tree. Pick the new items up in the next queue refresh and drain them like any other. If a teammate's filing is still uncommitted when you land your own outcome, commit it as its own `docs(pm): file <items>` commit first — separate from yours, so authorship stays legible — then ship your work. Never edit the content of an item you did not file except to record your own verdict on it. - **You share one working tree with those sessions.** Before each board write, re-read the file you are about to edit (it may have changed since you last read it) and apply the smallest edit that lands your verdict. That is the whole mitigation — it does not require coordination, a pause, or a question. - Only genuinely foreign **source** changes — uncommitted edits under `lego/`, `dashboard/`, `infra/`, `scripts/` that no one in this session made and no `.pm` item explains — are worth surfacing. Say what they are, leave them unstaged, and drain around them; stop only if they make the tree unshippable (see **Exit**). 3. The workstream `.pm/<wN>/README.md` exists. If not, STOP and report. 4. Read `.pm/DO_NOT_DO.md` once — it governs every triage verdict below. ## Build the queue (once, then refresh each iteration) Open items in `<wN>` are everything **not** already under `done/` or `blocked/`: - **Milestones** — `- [ ] **mN**` in `.pm/<wN>/README.md` with a live directory `.pm/<wN>/mN/`. - **Inbox notes** — `.pm/<wN>/NNN.md` (plain markdown, no frontmatter). These are the sub-hour tasks; they are part of the backlog, not background noise. Cross-check checkboxes against on-disk state (`ls .pm/<wN>/m*/ .pm/<wN>/*.md .pm/<wN>/done/ .pm/<wN>/blocked/`). If they disagree, trust the files and flag the drift. **Order:** pending milestones by ascending number first, then open inbox notes by ascending number — unless a stated dependency forces otherwise, in which case say so. **Urgency may reorder, and never stops the loop.** You may pull a security or data-loss item ahead of the prescribed order — name the reason in one line and take it. What you must not do is stop to ask which to work first: an item further down the queue looking more important than the one in front of you is a reordering decision you are equipped to make, not a question for the user. They can always reorder by interrupting. **Empty queue → sync before concluding.** If the queue has no pending milestones and no open inbox notes, other sessions may have filed work that only exists on the remote. Before going to **Exit**, get the latest remote main: `git fetch origin main`, then `git pull --rebase --autostash origin main` (never discard local or teammate changes; if the rebase conflicts, treat it as a run-level block). Then rebuild the queue once. If it is still empty, go to **Exit**; if the sync brought in open items, drain them like any other. Do this at most once per empty refresh, so a genuinely drained workstream still exits. ## The loop For each item, announce which one you picked and a one-line plan before doing work. **Every item gets its verdict without a user round-trip.** An unusual shape — a record-only note, one you withdrew earlier in this session, a duplicate, an empty stub, a note whose premise a teammate already fixed — maps to a row in the tables below: land that verdict on disk and move to the next item in the same turn. The run pauses only for the **Exit** conditions, which are about the repository being unshippable, not about an item being unusual. ### 1. Triage Read the item in full — for a milestone, `.pm/<wN>/mN/README.md` plus every task file `tNNN.md` not already in `done/`; for an inbox note, the note itself. Then check its premise against the current codebase (the note may be weeks old and the bug already fixed). Pick exactly one verdict: Items restored by [`/unblock`](../unblock/SKILL.md) carry dated decisions and next actions in the board. Read and apply those decisions during triage; verify their factual prerequisites without asking the user to decide the same thing again. A genuinely new blocker still gets its own precise gate. | Verdict | When | Action | | --- | --- | --- | | **Work** | The premise holds and nothing external gates it. | step 2 → 3 → **done** | | **Already met** | The described end state is **already true in the code** — verify it, don't assume. | **done** + evidence | | **Blocked** | A gate you cannot clear: physical hardware, a credential/console only the user has, an upstream item elsewhere, or a decision only the user can make. | **blocked** | | **Invalid** | The premise is false, the work is a duplicate of a shipped/live item, or it conflicts with `.pm/DO_NOT_DO.md`. | **delete** | Rules for triage: - **Evidence, not vibes.** "Already met" and "invalid" both require a concrete pointer — `file.go:123`, a passing test, the surviving duplicate's id, the `DO_NOT_DO` line. - **Render parity work is never blocked on an optional decision** ([ADR008 § Render parity first](../../../docs/ADR008-vision.md#render-parity-first)). - If a pending user decision is not required to reach Render's behavior in every workspace, it is not a gate. Ship the parity-sufficient option, and file the open variant as its own item. - Example: m149's seccomp choice did not block `render-v1` under RuntimeDefault. - An older ADR that conflicts with parity is likewise not a gate. Amend it as part of the work. - **Cloud coding-agent work matches Devin the same way** (user preference 2026-10-30; [ADR047](../../../docs/ADR047-cloud-coding-agent-sessions.md)). For agent sessions, `/agents`, sandboxes and PR delivery, Devin's observable behavior is the reference, and the same rules apply: ship the Devin-consistent option instead of waiting on an optional decision, and file variants separately. Whenever an item leaves a design choice open, pick the option that matches the reference product (render.com for hosting, Devin for coding agents). Verify how that product actually behaves before picking, and cite it in the item. - **When torn between blocked and invalid, choose blocked.** Deleting is the only outcome that destroys information. - **Size check on inbox notes.** If a note turns out to be > ~1h across more than one task, run `/pm promote <wN/NNN>` to materialize it as a milestone, then work that milestone in this same iteration. - **Non-implementation notes have preset verdicts — apply them without asking.** Many inbox notes are not "build this"; they are records, withdrawals, or debris. Route them by shape, in this order (first match wins): | Shape | Verdict | Landing | | --- | --- | --- | | **Blank or stub** — no `Why:` line and no substantive body, or a placeholder never filled in | **invalid** | `git rm`, drop its README line | | **Duplicate with no unique content** — the surviving item covers it entirely and this note adds no findings of its own | **invalid** | `git rm`, cite the survivor's id | | **Duplicate or withdrawal that carries its own findings/history** — including a note you withdrew earlier in this run | **done** | `done/`, append the survivor's id + date; never `git rm` history | | **Record-only** — a coverage record, sweep log, or audit trail documenting work already performed, with nothing left to implement | **done** | `done/`, append one line dating the closure | | **Already fixed by someone else** — the premise held when filed but a commit since resolved it | **done** | `done/`, append the fixing commit SHA | These are the common cases a drain hits; none of them is a reason to pause. If a note matches none of the shapes and none of the four verdicts, prefer **blocked** with the ambiguity named — parking is always available and never destroys information. - **Never split a milestone's verdict.** If some tasks are implementable and one is gated, the milestone is **blocked** — finish every implementable task first, then park it (this is the `w11` pattern: implemented tasks done, the gated task named). ### 2. Implement it (Work verdict only) Do the actual engineering, task by task, in the order the item implies: - Follow all `AGENTS.md` rules (id minting, boilerplate headers, `.env.example` sync, prettier on markdown, skill layout, etc.). - Milestones ship features **end to end** — include the frontend tasks alongside the backend ones; do not stop at the API. - Run the relevant test suites and make them pass before considering a task done — `make test` (from `lego/operator/`), `cd lego/backend && go test ./...`, dashboard `yarn test`, whichever the change touches. Never mark a task complete on unverified code. - When a DoD needs a signed-in check on production (`dashboard.bex.co` / `api.bex.co`), sign in as the QA user with `bash scripts/qa-login.sh` — it reads `QA_EMAIL`/`QA_PASSWORD` from `.env` or `muse.env` itself, so never read those files or type the password; follow the login and logout steps in `.claude/skills/qa-find-bugs/SKILL.md`. Only exit 2 (credentials missing in both files) is a blocked gate. - You may delegate independent sub-tasks to subagents (Agent tool) to parallelize, but you own correctness. - Keep `.pm` status in sync as you finish tasks (task frontmatter, milestone README `**Status:**` + the `— DONE` row, workstream checkbox). These are `/pm`-governed writes — follow `.claude/skills/pm/SKILL.md` exactly. ### 3. Land the outcome Every item ends in exactly one of these on-disk states, applied **automatically as soon as the verdict is reached** — no confirmation, no "should I move this?". Leave **no tombstone, stub, or redirect** at an item's old path. **done** — the work is real and verified. - Task: `status: done`, row `— **DONE**`, file → `wN/mN/done/tNNN.md`. - Milestone with no open tasks: `mv` the whole directory → `wN/done/mN/`, `rmdir` the original, flip the workstream checkbox to `- [x]`. - Inbox note: `mv` → `wN/done/NNN.md`. - For an **already met** item, append one line to the moved item recording the evidence and the date, so the record says why it closed without a code change. **blocked** — implementable work finished, a named gate remains. - `mv` the milestone directory → `wN/blocked/mN/` (or the note → `wN/blocked/NNN.md`). - Leave the workstream README line unchecked (`- [ ]`) and rewrite it as `**BLOCKED (<exactly what you need from whom>)**` with the path updated to `blocked/…`, plus which tasks are already done. See `.pm/w11/README.md` for the shape. - Surface every blocker again in the final report — a gate the user never reads is a gate that never clears. - Point to `/unblock <wN>` for a Chinese explanation and decision workflow; keep draining the open queue while those items remain parked. **delete** — the item is invalid. - `git rm` the file or directory and remove its line from the workstream `README.md`. - Record in the run report: the item, the verdict, and the evidence. Never delete an item that contains completed task records — move it to `done/` instead so the history survives. Then run `npx prettier@3.4.2 --write "**/*.md"` (repo rule). ### 4. Ship it Invoke **`/ship`**. Because you made the changes this session, `/ship` runs session-aware: it stages exactly what you touched and writes the commit message from your knowledge. - **Code-bearing items ship alone** — one milestone (or one worked note) per commit, so history and rollback stay clean. - **Board-only outcomes** (blocked, deleted, already-met) need no commit of their own; batch them into a single `docs(pm):` ship. They must be shipped before the run ends — don't leave board mutations uncommitted. `/ship` ends at a successful push — it does not watch CI or the deploy. Do not start the next item until `/ship` reports the shipped HEAD. If `/ship` surfaces a failure it cannot fix (a rebase conflict it can't resolve, a rejected push), treat it as a **run-level block** and stop. #### 4a. Main is red: fix CI first, then resume — never wait, never stop A red main is never a reason to stop or to hold commits locally (user decision 2026-10-21; `AGENTS.md` Rules). `/ship`'s gate only warns about it. Unpushed commits in a checkout other sessions share look like unexplained divergence, and a teammate's `git reset` can discard them, so the paused item ships in the same turn either way: 1. **Pause the item and diagnose the red run.** Commit the item locally. Read the failing job's log (`gh run view <id> --log-failed`) and compare it with the last green run (`gh run list --workflow deploy.yml`), including what changed between the two SHAs. Also check whether main already contains a fix: a red verdict can be stale when every later run was cancelled. 2. **Fix it if you can, whatever the cause.** Fixing main is in scope for every workstream; the **Stay in `<wN>`** rule does not apply. - **Code or test failure** (yours or anyone's): make the smallest correct fix, with a regression test where one fits. Ship it alone as `fix(ci): …`, saying in the commit that it fixes red main, with `--fixes-red-main`. - **Flake or infra fault** (runner crash, emulation SIGSEGV, network, setup failure): rerun only the failed jobs (`gh run rerun <id> --failed`) in the background, and **do not wait for it**. If the same failure has repeated, land a repo-side root-cause fix: a retry, a pinned toolchain or runner setting, or splitting or caching the failing step. Ship that as `fix(ci): …` with `--fixes-red-main`. Never fix it by weakening a gate, deleting a test, skipping a job or reverting runners to GitHub-hosted (`DO_NOT_DO.md` #CI-RUNNERS). 3. **Resume immediately.** Ship the paused item's commits through `/ship` right after the fix is pushed. Do not wait for the fix's own CI run. 4. **If it cannot be fixed now, ship anyway.** That covers a fix that needs credentials, runner or host access, or a decision only the user has; a stale red that has nothing left to fix; or a flake still in flight. Ship the paused item's commits through `/ship` without waiting. Record the red run, its cause and what you tried in the next checkpoint (and file a board item if a fix is still owed), then continue the loop. What still stops a ship is the push's **own** defect: `/ship`'s real-DB backend suite failing on your change. Fix that properly before pushing; it is never waived. ### 5. Continue Refresh the queue (the board changed) and loop back to triage the next item. The refresh reads the board as it is **now**, so items a teammate filed since you started are simply part of the queue — triage them in the normal order alongside the ones you began with. ## Exit **Before you write a final summary, refresh the queue.** If it returns open items, the user has not interrupted, and you can still do work — discard the summary and take the next item. Writing a summary is not a decision to stop; finishing the queue is. Stop and give a final summary when any of these holds: - **Drained:** a queue refresh returns **zero** open items in `<wN>`. Report every item and its outcome, grouped: shipped, closed as already met, parked in `blocked/` (with each gate), deleted (with each reason). "Drained" is measured against the queue as it stands at that refresh, never against the queue as it stood at invocation — items others filed while you worked are part of it, and a workstream under active filing may legitimately keep you working for a long time. That is the requested behavior. - **Run-level block:** a ship failure you can't resolve (a rebase conflict that needs the user, or your own change failing its tests in a way this session cannot fix), or the tree is in a state you shouldn't push. A red main is **never** a run-level block; see step 4a. Per-item blocks do **not** stop the run — they get parked and the loop continues. - **Interrupt:** the user sends a new message, or the context budget is genuinely exhausted — you cannot fit another item's work. **Running for a long time is not an exit**, and neither is a queue that keeps growing; both are checkpoints. See below. **Not exit conditions**, and never a reason to pause mid-drain: an item that is a record rather than a task; an item you yourself withdrew or filed earlier; a duplicate; an empty note; an item already fixed upstream; a verdict that feels unusual. Each of those has a row in the triage tables — apply it and keep going. Also **never** a reason to pause: **a red main or a slow CI** (step 4a: fix it if you can, ship either way, never wait). And **new work arriving while you drain.** A teammate session filing fresh milestones or notes into `<wN>` — uncommitted, half-written, or landing seconds ago — is the queue doing its job, not a hazard. A peer session showing `busy` against the same workstream changes nothing either. Refresh the queue, take the new items in order, and drain them. A backlog that grows during the run means the run continues; it does not mean the run stops to ask about it. ## Checkpoints — these do NOT end the run There is a real need to tell the user things mid-drain: a blocker parked, a premise disproved, a milestone that turned out three times its estimate, a queue that doubled. Serve it with a **checkpoint**: a few lines of progress, then **immediately take the next item in the same turn**. A checkpoint is a report, not a stop. The distinction matters because the pull to stop arrives disguised as a duty to report — you finish an item, notice something the user should know, write it up, and the write-up reads like an ending. It is not. If workable items remain, the summary you just wrote is a checkpoint; post it and keep going. Two specific traps, both of which have actually happened: - **Re-surfacing parked blockers is a reminder, never a justification.** The final report is required to list every gate again, because a gate the user never reads is a gate that never clears. Listing them next to a decision to stop makes already-parked items look like live obstacles holding up the loop. They are not — they are parked precisely so the loop can continue past them. - **"This is unbounded" is not a finding.** A queue refilled by a concurrent worker, a backlog that outpaces you, a workstream that will not reach zero today — none of these is an exit condition. Note it in a checkpoint and take the next item. ## Guardrails - **Never ship red.** A failing test suite is a per-item block, not a footnote. `/ship`'s own gate backs this up — don't route around it. - **Never ship half-work.** If an item can't be finished, it becomes **blocked** with the implementable part complete — not a partial "done". - **Stay in `<wN>`.** Only touch items from the requested workstream. Workers are general-purpose, but this run is scoped to the queue the user named. - **Deletion is a claim, not a shortcut.** Every deleted item costs you a sentence of evidence in the report. If you can't write that sentence, it isn't invalid. - **Report honestly.** If you skipped a task, mocked something, or a suite was flaky, say so in that item's summary — don't present partial work as complete. - **Never stop with workable items in the queue.** If a refresh returns open items, the user has not interrupted, and you can still do work, the run continues — whatever else is true about how long it has taken, how the backlog is trending, or how much you have to report. Ending a drain early with a full queue is the one failure this skill cannot recover from on its own, because the user has to notice and restart it.