fix-tickets — Claude Code command: what it does, how to install
fix-tickets takes GitHub issues through an automated fix, review, PR, merge, and reporting cycle. Use it for sequential ticket work.
MIT ★ 110 updated 2026-11-10
.claude/commands/fix-tickets.mdWhat fix-tickets does
fix-tickets updates main before each ticket, refreshes the installed companion commands when apps/speckit-extension/ changed, then runs /speckit-companion-auto. That flow confirms the issue, performs the fix and review, opens a PR, and squash-merges it after CI passes.
The command records review findings in the Review Ledger and writes one vault note per ticket with test steps, Storybook screenshots, and generated files. Once the batch is done, it runs /install-local and creates a markdown report under Projects/speckit companion/; the report points to /release-qa. Tickets run one after another, while 🔒 Gated tickets are skipped.
Use --light for mechanical changes with a settled cause and fix, such as a regex, documentation, or manifest edit. This mode drops the issue, spec pipeline, and sequencing requirements, but keeps code review, tests, and CI.
What it helps with
- process several GitHub issues in sequence
- run
/speckit-companion-autoafter checking a ticket - open and squash-merge a PR after CI
- log review findings in the Review Ledger
- write ticket notes and a batch report
Example prompts for the agent
- Run
/fix-tickets 237 238 241and process these issues in order. - Run
/fix-tickets open, then ask me to confirm the issue list before starting. - Use
/fix-tickets --lightfor this mechanical documentation fix.
How to install fix-tickets
Manually: put the files in place
.claude/commands/fix-tickets.mdCall it with /fix-tickets. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/fix-tickets.mdCall it with /prompts:fix-tickets. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/fix-tickets.prompt.mdManually: put the files in place
.gemini/commands/fix-tickets.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about fix-tickets
How do I install fix-tickets in Claude Code?
Copy the command file to .claude/commands/fix-tickets.md. Then run it with /fix-tickets.
What does fix-tickets do?
It moves GitHub issues through a sequential workflow: refreshes main, runs the automated fix with review and PR creation, merges after CI, records lessons, and writes a final report.
When should I use --light?
Use it only when the cause and change are already settled, such as for a regex, documentation, or manifest edit. Reviews, tests, and CI still run.
Source text
fix-tickets.md · MIT
---
allowed-tools: Bash(git:*), Bash(gh:*), Bash(npm:*), Bash(node:*), Bash(python3:*), Bash(code:*), Bash(specify:*), Bash(date:*), Bash(sleep:*), Bash(jq:*), Bash(tooling/scripts/merge-pr.sh:*), Bash(tooling/scripts/new-worktree.sh:*), Agent, AskUserQuestion, Read, Write, Edit, Skill, TaskCreate, TaskUpdate
description: Autonomously fix one or more speckit-companion GitHub issues with /speckit-companion-auto — fresh main, auto (fix + reviews + PR), merge, learnings — then one install-local and a run report. Self-hosting build loop.
argument-hint: "<issue numbers e.g. '237 238 241'> | 'open' (all open issues) | <path to backlog .md> | --light [free-text tasks]"
---
## What this does
A **self-hosting build loop** for `speckit-companion`, and step 2 of `/release-loop`.
> **Every ticket runs the full loop by default:** one issue, one `/speckit-companion-auto` run, one ticket at a time. **`--light`** ([Light mode](#light-mode---light)) is only for mechanical fixes whose cause and change are already known: a regex, a doc, a manifest. Never pick it to go faster; if you are unsure, it is a full-loop ticket.
For each ticket, in strict sequence:
1. **Fresh `main`** — pull, and if the pull changed `apps/speckit-extension/`, refresh the installed companion commands so this ticket runs on the previous ticket's merge.
2. **Auto** — confirm the bug still reproduces, then run `/speckit-companion-auto`. Its project hooks (`.specify/companion.yml`, after implement's `handoff`) do the self-review, one `/code-review` pass (`/codex:review` beside it only for the webview renderer, the run-record writer or a publish command), the commit, and the PR.
3. **Merge** — squash-merge once every CI check has finished and passed.
4. **Learnings** — log the review findings to the Review Ledger, route each kept lesson to where it fires, tick the ticket in the live queue.
5. **Verify note** — one vault note per ticket with the steps to test it, Storybook screenshots of what changed on screen, and the files the run made.
6. **Next ticket.**
A **grouped issue** (a checklist of items in its body) runs steps 1 to 5 once per slice of that checklist, not once per issue. See [Grouped issues](#grouped-issues).
After all tickets: one closing `/install-local`, then one **run report** (markdown, via the vault `obsidian` skill, flat in `Projects/speckit companion/` under a descriptive name; the vault has no `reports/` folder) of everything fixed, in plain language, the **new lessons** captured, and any **architecture/skill flags** worth promoting. It ends by pointing at `/release-qa`, which tests the whole batch once; this loop never desktop-tests a ticket. Use `/html-page` only to *export* it if it needs to leave the vault — HTML in the vault is unsearchable.
## Locked defaults
- **Merge:** auto-merge, no per-ticket stop. You review via the final report; `/release-qa` covers the batch afterwards.
- **Auto runs in the main loop, not a subagent.** Its review hook dispatches the reviewers as subagents; inside a subagent that nesting fails and the hook falls back to `/code-review` inline. Keep the main context lean another way: after each ticket, re-derive state from `git`/`gh` and the ticket's result line, not from the transcript.
- **The auto hooks are the review gate.** Don't add a second `/code-review` pass on top — that's what the old loop did, and it reviewed every ticket twice.
- **One review pass, two at most.** `/code-review` runs once. `/codex:review` joins it only where a second reviewer has paid for itself: the webview renderer, the writer of the run record, or a publish command. A second round happens only when a fix itself changed real logic, and then it reviews only that fix.
- **Sequential only.** Never parallelize — each ticket must run on the previous ticket's merged commands. (`--light` lifts this. See [Light mode](#light-mode---light).)
- **The loop compounds.** Every ticket reads `.claude/review-checklist.md` (+ the `CLAUDE.md` conventions it points to) before fixing, and routes any new high-signal learning to where it fires (review check → checklist; authoring convention → `CLAUDE.md`; loop-mechanics → this file; gap → an issue). Convention/architecture promotions are *proposed* in the report, never auto-applied.
- **Queue gating honored.** `🔒 Gated` tickets are skipped; `⏸️ Review-gated` tickets pause before merge.
## Inputs
`$ARGUMENTS` is one of:
- A space-separated list of issue numbers: `237 238 241`
- `open` — process all currently-open issues (`gh issue list`), confirm the list first via AskUserQuestion before starting.
- A path to a backlog markdown file or folder — treat each item as a ticket (still requires a GitHub issue; create one with `/create-github-issue` if missing, confirm first).
- `--light` — run **light mode** (below). Takes issue numbers *or* free-text task descriptions, since light mode files no issues.
If `$ARGUMENTS` is empty, list open issues and ask which to run.
## Grouped issues
Some issues fold several drafts into one ticket: the body has an `## Items` checklist (each line a draft id and one sentence), an optional `## Later` list, and the ticket's acceptance. They come from a plan map in the vault (`Projects/speckit companion/plans/`), which the issue links.
- **Slice the checklist.** A slice is one item, or a few items that touch the same files and ship as one change. Name the slices before the first one starts and list them in the ticket's task. `## Later` items are not sliced; they stay in the issue.
- **One auto run per slice.** Each slice is a ticket for steps 1 to 5. Its PR body says `Part of #N` and names its item ids; the slice that ticks the last unchecked item says `Closes #N` instead, but only when no unchecked item is left in `## Later` either; otherwise it says `Part of #N`, moves the Later items into one follow-up issue that links back, and names that issue in the run report. After each merge, tick the slice's items in the issue body.
- **Ask a slice's open decision at its start.** An item marked `decision:` in the issue waits on a choice the plan left open. Ask it before the slice runs (Factory's Plan page when the chat has one, otherwise AskUserQuestion, recommended option first), record the pick in the issue, and never guess it to keep moving.
- **Screen changes need a mock first.** An issue labelled `ui` needs an approved `/design` mock linked in its body before its first slice. Without one, the ticket is review-gated: post what needs designing and move to the next ticket.
- **Blocked issues wait.** An issue whose body says `Blocked by #M` while #M is open is skipped, and the report says so.
---
# Light mode (`--light`)
Only for **mechanical** changes whose cause and fix are already settled: a wrong regex, a stale doc, a missing emission, a manifest tweak. The code review, the tests, and CI all stay; the issue, the spec pipeline, and the sequencing go.
## What light mode changes
| Step | Full loop | Light |
|---|---|---|
| GitHub issue | required (`Closes #N`) | **none** — the PR body carries the why |
| Fix | `/speckit-companion-auto`, writes `specs/NNN-*/` | **direct fix**, no spec folder |
| Execution | strictly sequential | **parallel worktree subagents** |
| `install-local` | **once, at the end** (commands refreshed per ticket) | **once, at the end** |
| Code review | auto's hooks: one `/code-review` pass, `/codex:review` only for the three places that earn it, findings logged to the Review Ledger | `/code-review` high per branch (L2), same three-place rule for Codex |
| Learnings | distill per ticket | **one distill** for the batch |
| Report | markdown run report in the vault | **chat summary** |
## What light mode COSTS — read before choosing it
**The spec pipeline is the dogfooding.** Running the Companion workflow on itself is the entire reason this loop exists — it's how the broken `adopt` command, the no-op reconciler, and the packaging gap were found. Light mode trades that signal away.
So light mode is a **named exception for mechanical changes, never the default and never a shortcut for speed.** If a task turns out to be bigger than it looked — it needs a design decision, or it touches derived state / lifecycle / capture — **stop and escalate it to the full loop**. Don't push a large change through light mode because it was already started there.
**Growing past your named file set is NOT by itself an escalation trigger.** Chasing one root cause into more files is the job: #442 started as "a wrong path constant" and ended up also fixing the skills list the sidebar renders — because it was one bug (the registry lied, and a consumer ignored it anyway), and stopping at the named files would have shipped half of it. The test is *"is this still one coherent defect?"*, not *"is this still three files?"* Escalate when the **decision** grows (a new design call, a behavior the user has to choose), not when the **blast radius** does. If the file set widens, say so in the PR body and re-check disjointness against the other in-flight branches.
## Choosing light vs full
**Light is allowed only when** the fix is mechanical and the *what* is settled: a parsing bug with a known cause, a doc that contradicts the code, a missing file emission, a manifest/menu change, deleting dead code. Everything else is a full-loop ticket.
**It is always the full loop when** any of these is true:
- The fix needs a design decision (the issue asks "should we…?").
- It touches **derived state**, lifecycle/status writing, or capture (`.spec-context.json`) — this repo's worst bug class lives there.
- It's user-facing UI/UX with a visual judgment to make.
- You can't name the files it will touch before starting.
> When a mechanical fix is also a user-visible **bug**, light mode still gives it the full `/code-review` treatment, including the re-review pass on logic-changing fixes. Skipping paperwork is not the same as skipping scrutiny.
## Parallel worktrees — the four collisions
Light mode runs one subagent per task, **each with `isolation: "worktree"`**. This is mandatory, not an optimization: background agents otherwise share one working tree and branch, and they *will* clobber each other's git state.
Four things collide if you're not careful. Note that the first two are precisely why parallelism is safe **only** in light mode:
1. **Spec numbering race.** Specify picks the next `NNN-` by scanning `specs/`. Two agents starting together both choose the same number. — *Cannot happen in light mode: no spec pipeline.*
2. **A fresh worktree has no companion commands.** `.specify/extensions/companion/` is **gitignored** (it's the `--dev` install), so a new worktree checks out tracked files only and `/speckit.companion.*` does not exist there. An agent running the pipeline in a worktree fails — or silently falls back, which is worse. — *Cannot happen in light mode: no pipeline. If you ever need it, the worktree must run `specify extension add ./apps/speckit-extension --dev --force` first.*
3. **`install-local` is a global singleton.** One VS Code extension host, one `~/.vscode/extensions`. It cannot be parallelized — run it **once, after all merges**.
4. **A fresh worktree has no `node_modules` — make it with `tooling/scripts/new-worktree.sh <name> <branch>`, which links them, or run `npm ci` FIRST, or every test run lies.** `node_modules/` is gitignored, so a new worktree checks out source only. Worse than an obvious "command not found": jest's `moduleNameMapper` is pinned to `rootDir`, so ~10 suites fail on *module resolution* and read like real regressions. Two of four agents hit this on the first light run and one nearly reported it as a broken build. **`npm ci` in the worktree before you trust any `npm test` / `npm run compile` output** — and if a test suite fails on `Cannot find module`, that is this, not your change.
**Disjointness gate.** Before fanning out, name the files each task will touch. **If two tasks touch the same file, do not run them in parallel** — run those two sequentially (or fold them into one PR). Parallel PRs on the same file just move the conflict to merge time.
## Light procedure
### L0. Setup — main loop
- Assert a clean tree on `main`, `git fetch && git pull --ff-only`. **Refuse to start dirty.**
- Resolve the task list from `$ARGUMENTS` (issue numbers and/or free-text). `TaskCreate` one task each.
- **Name the file set for each task** and check disjointness (above). Group any overlapping tasks to run sequentially.
- **Do NOT run `install-local` here** — light mode installs once at the end.
### L1. Fan out — parallel subagents, one per task, `isolation: "worktree"`
Dispatch all disjoint tasks **in a single message** so they run concurrently. Each subagent:
- Reads `.claude/review-checklist.md` (+ the `CLAUDE.md` conventions it points to) **first**.
- **Runs `npm ci` in the worktree before anything else** (collision 4 above) — otherwise its test run is meaningless.
- **Verifies the defect still reproduces on current `main`** before building. Stale tasks are common; if it's already fixed, STOP and report that with evidence instead of inventing a change.
- Fixes it **directly** — no `/speckit-companion-*` chain, no `specs/NNN-*/` folder.
- Updates the docs the change requires (`CLAUDE.md`'s doc-map is not optional in light mode).
- Writes the changelog entry with `/changelog-entry` when a user will meet the change. Workers write its link as `([#PR](…/pull/PR))`; the main loop replaces `PR` with the real number right after `gh pr create`, in one commit, then rebases. Never hand a worker a guessed number.
- Runs `npm run compile && npm test` (+ `npm run package` if the manifest/webview changed). **Does not return green if red.**
- Commits on a branch named `light/<slug>` and **pushes**.
- Returns `{ branch, filesChanged[], testsPassed, summary, escalate? }`.
If a subagent returns `escalate` — the task was bigger than it looked — **do not merge it**. Leave the branch, report it, and re-run it through the full loop.
### L2. Review — one subagent per branch
`/code-review` at **high** effort on each branch's diff vs `main` — **one pass**. Run `/codex:review --base main --scope branch` beside it only when that branch's diff touches the webview renderer, the writer of the run record, or a publish command; elsewhere one reviewer is the gate. Apply findings, commit, re-run the suite only if the fixes changed code, and log each finding to the Review Ledger. A second round happens only for a fix that changed real logic, and reviews only that fix; this step is not lightened, it is just not repeated for its own sake.
### L3. PR — main loop
Open a PR per branch (`/create-pr` conventions). Since there's no issue, **the PR body must carry the why** — what was broken, how you know, how to verify. No `Closes #N`. (The review already happened in L2; if an L2 fix changed real logic, re-run `/code-review` on it before opening the PR.)
### L4. Merge — main loop, sequential
Merge **one at a time**, only after every CI check on it has finished and passed (`gh pr checks`; a pending check is not a pass). After each merge, the next PR is behind `main` — if GitHub reports a conflict or the branch is stale, rebase it before merging. (This is the tax for parallel branches; it's cheap when the file sets are disjoint, which is why L0 gates on that.)
### L5. Close out — main loop
- **One** `install-local`, then `git restore package.json package-lock.json .specify/`.
- **One** learnings distill for the whole batch (same routing rules as the full loop: checklist / `CLAUDE.md` proposal / this file / issue candidate). An empty distill is the norm.
- **Chat summary**, not an HTML brief: what shipped, anything escalated, and `/release-qa` as the next step.
---
# Full loop (default)
> Run from the repo root: `~/dev/GitHub/speckit-companion`. Confirm with `git rev-parse --show-toplevel`.
### 0. Setup
- Resolve the ticket queue from `$ARGUMENTS` (see Inputs). Create a task list (`TaskCreate`) with one task per ticket so progress is visible.
- Read `gh issue view <N>` for each to confirm scope and capture the title/body.
- **Honor the queue groups in the live queue** (`Projects/command-center/tickets/migrate-live-queue.md`; `Current.md` is archived): tickets under `🔒 Gated / not ready` are **skipped**; tickets under `⏸️ Review-gated` are run but **paused before merge** (step 3). The `--review-merge` arg forces review-gate for the whole batch.
- Confirm the queue with the user **once** (AskUserQuestion) only when the queue was derived (`open` / backlog), not when explicit numbers were passed.
### For each ticket `N` (sequential):
#### 1. Fresh `main` — main loop
```bash
git rev-parse --show-toplevel # must be the speckit-companion repo
git status --porcelain # MUST be empty — if not, STOP and report
git checkout main && git fetch origin
BEFORE=$(git rev-parse HEAD) && git pull --ff-only
git diff --quiet "$BEFORE" HEAD -- apps/speckit-extension/ || specify extension add ./apps/speckit-extension --dev --force
git restore .specify/ && git status --porcelain # MUST be empty again
```
If the tree is dirty, **do not** stash or discard. Stop the whole loop and report — a dirty tree means an earlier ticket left work uncommitted.
The installed companion commands (`.specify/extensions/companion/`, `.claude/skills/speckit-companion-*`) are **gitignored copies**, so `git pull` alone leaves them stale. The `specify extension add` refresh is what makes this ticket run on the commands the previous ticket just merged — the dogfooding crux. The `.vsix` is not needed per ticket: the pipeline runs in the CLI, not the VS Code extension.
#### 2. Reproduce, then auto — main loop
- **Read `.claude/review-checklist.md` first** (and the `CLAUDE.md` conventions it points to).
- **Verify the bug reproduces on current `main`.** Backlog tickets go stale — they're frequently already fixed, duplicates, or already-correct paths (~3 of 8 in one batch). If it's already fixed, STOP this ticket, close the issue as resolved/dup with the evidence, and move on. Deliver only the genuinely-missing part.
- Run `/speckit-companion-auto` with the issue as the feature description. Include `Issue #N: <title>` and the body, and say the PR body must carry `Closes #N`. For a slice of a [grouped issue](#grouped-issues), pass only the slice's items plus the issue's acceptance, and the PR body carries `Part of #N` (or `Closes #N` on the last slice).
- Auto runs specify → plan → tasks → implement → converge unattended (repeating implement and converge until a pass adds nothing, three passes at most) and ends at `completed` through a clean converge. Implement's hooks in `.specify/companion.yml` then self-review, run `/code-review` once (with `/codex:review` beside it only for the webview renderer, the run-record writer or a publish command; anything still open goes into the PR body as a gap), commit, and open the PR via `/create-pr`. It does not merge.
- **Keep the review findings.** As auto's reviews return, note each finding: what it was, who found it (`code-review` / `codex` / `both`), severity, and whether it changed code. Steps 4a and 4b need them; the transcript won't be re-read.
- **Check what auto left behind before merging:**
- `specs/<NNN>-<slug>/` is `completed`, all tasks checked, `specName` is the real name (not `[FEATURE NAME]`). **NEVER revert a Companion-built spec from `completed` back to `implemented`.** `completed` must follow a converge entry in `.spec-context.json` that added no tasks; a spec that reached `completed` without one is a finding for the report.
- The PR does not carry regenerated `.specify/` artifacts (`feature.json`, registry files). **One exception:** if the PR adds or renames a command in `extension.yml`, `.specify/extensions/.registry` MUST stay in the diff — CI's `check-command-emissions.py` gate requires it.
- The suites are green — **read that, don't re-run it.** Implement records every check it ran with `--verify-run`, so the answer is already in `specs/<NNN>-<slug>/.spec-context.json` under `verified`: find the compile and test entries and look at `exitCode`. Re-run `npm run compile && npm test` yourself only when there is no such entry, when one exited non-zero, or when a source file was written after the record was — compare the newest changed file against the modified time of `.spec-context.json`. If `apps/speckit-extension/**` changed, also `python3 apps/speckit-extension/scripts/check_shape_parity.py`. If capture/timing changed, run the capture eval.
- Push any fixes to the PR branch.
- **Log the subagents — observe, never force.** Run `python3 .claude/scripts/subagent-tally.py specs/<NNN>-<slug>`. It reads this session's transcript and prints, per step, the subagents auto actually dispatched next to what that step's rule expects (plan: one reader per recorded `area:`, at most 4, plus 2 design-doc writers, nothing on a simple run; implement: one per story phase with 5+ files, up to 4 per Foundational wave of 4+ tasks, plus 2 reviewers per round). Copy the output into the ticket's result line as is. Do not re-run a step to get the expected number, and do not dispatch workers auto skipped: a gap between expected and actual is a finding for the report, not something to fix mid-ticket.
- If auto can't produce a passing fix, or ends without a PR, record the ticket as "needs attention," get back to a clean `main`, and continue.
Then write one result line for the ticket (PR, spec dir, summary, findings, subagent tally) and work from that, not the transcript, for the rest of the run.
#### 3. Merge + cleanup — main loop
**Review-gate check.** If this ticket is **review-gated** (the `⏸️ Review-gated` group, or `--review-merge`), do **not** merge. Post the PR link and a one-line summary, record it as "merged: NO — awaiting your review," and move to the next ticket.
Otherwise:
```bash
tooling/scripts/merge-pr.sh <PR> # waits here and merges once every check has passed (auto-merge would skip the test job, which is not required)
```
When it queues the merge it returns at once: move to the next ticket and read the outcome with `gh pr view <PR> --json state` before the final report. Exit 3 means the pull request changes what a person sees and the owner has not looked: record "merged: NO — awaiting your review" and re-run with `--seen` only after they approve. Never merge around the script with `gh pr merge`. Run it unpiped (`merge-pr.sh <PR>; echo "exit $?"`): piped into `tail`, the exit code is `tail`'s, so a refused merge reads as merged.
If checks fail and can't be fixed on the branch, leave the PR open, record "merged: NO — checks failing," continue.
#### 4. Learnings + tick the box — main loop
**a) Review Ledger.** Append one row per finding to `~/dev/GitHub/obsidian-vault/Projects/speckit companion/Review Ledger.md`: date, PR, the finding in a line, found by `code-review` / `codex` / `both`, severity, changed code or not. Write it on every run, including when Codex found nothing — it's the only record of whether the second reviewer earns its place.
**b) Distill — route by shape, don't dump.** A learning earns capture only if it's **checkable, recurring or high-cost, and phrased as a rule/scan**; prefer editing an existing line over a near-duplicate; **an empty distill is the norm.** Route each kept learning:
- a **codebase-specific review check** → `.claude/review-checklist.md`
- a **universal authoring convention** → the matching `CLAUDE.md` section — *proposed* in the report, not auto-applied
- a **loop-mechanics** improvement → this command file
- an **architecture / coverage gap** → a GitHub issue candidate (accumulate across the run, surface in the report)
- If it can become a test or hook, propose that instead of prose.
**c) Tick the ticket in the live queue.** `Current.md` is archived; the queue now lives in the command-center ticket `Projects/command-center/tickets/migrate-live-queue.md`. Tick the ticket there if it is listed; if the queue has no line for it, say so in the report rather than creating one. For a slice, tick its items in the issue body instead (`gh issue edit <N> --body-file`).
#### 5. Verify note — main loop
Write one note per ticket (per slice, for a grouped issue) via the vault `obsidian` skill, beside the run report in `~/dev/GitHub/obsidian-vault/Projects/speckit companion/`, named `Verify <ticket title>.md`, `lifespan: ephemeral`. It is what the owner reads to check the work by hand, so it carries:
- **How to test**, numbered: what to open or run (a command, a sandbox from `/sandbox`, a viewer page and a click) and what they should see.
- **Screenshots** of every changed component from its Storybook stories, saved next to the note. Take them before asking the owner to look: start Storybook with `factory_app_start` on the branch, screenshot each changed story with playwright-core (`channel: 'chrome'`, `waitUntil: 'load'`, a 3 s wait, `fullPage: true`; never `networkidle`, the dev server's websocket never idles), read every image, and fix what contradicts itself first. Never launch a real VS Code window per ticket; the real window is `/release-qa`'s job.
- **The files the run made**, inline when they explain the change: the spec's `spec.md` summary, `tasks.md`, and the last entries of `.spec-context.json`. Link the full files rather than pasting long ones.
- The PR link and what is not covered.
Link each verify note from the ticket's result line, and from the issue in a comment.
Mark the ticket task `completed` and loop to the next ticket.
---
### Closing install-local — after the last ticket
```bash
git checkout main && git fetch origin && git pull --ff-only
```
Run `/install-local`, then `git restore package.json package-lock.json .specify/` to drop the throwaway bump + regenerated registry artifacts. Optionally `code --command workbench.action.reloadWindow`. Record the installed version for the report.
### Final report
Write **one markdown run report** (via the vault `obsidian` skill) flat in `~/dev/GitHub/obsidian-vault/Projects/speckit companion/`, named for what the run did (no date prefix, no `reports/` folder: the date is a frontmatter field). **Never overwrite a prior report.** Concise and plain-language:
- **Per ticket:** issue # + title, one-sentence "what was fixed," PR link, its verify note, merged / in-review / skipped / needs attention. A grouped issue lists its slices and which items are still open.
- **🤖 Subagents** — one row per ticket and step from the tally: dispatched vs expected. Call out every gap in plain words (e.g. "plan expected 3 area workers, ran 0"), and any step that never dispatches in an auto run at all. This is how we know users actually get the fan-out the commands promise.
- **🧠 Lessons captured this run** — review checks added to `.claude/review-checklist.md` and loop tweaks to this file, with where each landed.
- **🏗️ Architecture / skill flags** — the promotion candidates from step 4b, each with a one-line "promote to `CLAUDE.md` / ADR / which skill?" suggestion.
- **Needs attention** — skipped tickets and why, PRs left in review, CI gaps.
- The final installed version.
- **Next:** run `/release-qa` for the batch. When the batch finishes a plan whose map has a verify ticket, point at that ticket instead: `/release-qa` on a fresh sandbox, then the stock against Companion bench (`/bench-experiment`).
End the chat response with a tight summary: tickets processed, merged vs in-review vs skipped, subagents dispatched vs expected, the installed version, lessons-captured count, a pointer to the report, and `/release-qa` as the next step.
## Guardrails
- **Never start a ticket on a dirty tree.** Stop and report instead.
- **Never parallelize tickets in the full loop** — each ticket must run on the previous one's merged commands. (`--light` parallelizes *because* it has no such gate; it must still use `isolation: "worktree"` and the disjoint-file check.)
- **Never force-merge red checks, and never merge while a check is pending.** Leave the PR open and report it.
- **Auto-merge is on by default** (per this loop's design). If the user passed `--review-merge` in `$ARGUMENTS`, pause for a thumbs-up before each `gh pr merge` instead.
- **Never run auto in a subagent** — its review hook can't nest subagents and silently drops Codex.
- **Two review rounds is the ceiling** (auto's hook enforces it); anything still open goes into the PR body or a follow-up issue.
- **Light mode never silently absorbs a big change.** If a `--light` task needs a design decision, or touches derived state / lifecycle / capture, the subagent returns `escalate` and it goes through the full loop instead. A widening *file set* alone is not an escalation — one coherent root cause may legitimately span more files than you named (see [What light mode COSTS](#what-light-mode-costs--read-before-choosing-it)); report the widened set and re-check disjointness. Skipping paperwork is not skipping scrutiny.
- **Never trust a test run in a fresh worktree until `npm ci` has run there.** Module-resolution failures masquerade as regressions.
- **Never run `install-local` inside a worktree.** It installs a global VS Code extension and regenerates `.specify/` — it belongs to the main loop, once, at the end.
© alfredoperez · MIT · alfredoperez/speckit-companion