build-issue
Skill2 starsChanged 19 days agoMITView on GitHub
Takes one tracker issue from its number to an open MR/PR: reads and triages it, runs the build-issue-loop workflow, and opens the MR/PR from the result. Use when the user points at an issue by number and asks to work on, take, pick up, handle, do or close it — e.g. "work on #42", "do GL-88 end to end". Not for vague feature ideas with no issue (use brainstorm), and not for reviewing an existing PR (use qa-review).
- Deletes or force-pushes
- Commits and pushes
In this repository16 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ask-teamSkill
- assemble-metaSkill
- brainstormSkill
- cut-milestonesSkill
- frictionSkill
- milestone-closeSkill
- qa-reviewSkill
- review-benchSkill
- scope-commitSkill
- scope-issueSkill
- scope-mrSkill
- scope-specSkill
- setup-dream-teamSkill
- ship-itSkill
- triage-issueSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
32 rules. About 0 are common, 17 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
Read only the checklist's unticked links to open child issues.
- Distinctive: line 43
No unticked open child → report that the Meta issue has no work left, and stop.
- Distinctive: line 44
Every one blocked → report each with its open blockers, and stop.
- Distinctive: line 66
Don't half-build around the gap.
- Distinctive: line 67
Don't end the turn yet: do the reading that makes the choice answerable — what each option costs, how many call sites it touches, what the …
- Distinctive: line 79
Never open a dialog whose options you had to invent to fill the slots.
- Distinctive: line 97
No runtime behaviour change: docs, comments, help or usage text, CI config, test fixtures, or a rename.
- Very specific: line 109
Run every gateCommands entry.
- Distinctive: line 114
Run lab work only for that rerun or a measurement the issue asks for, per step 5's lab steps.
- Very specific: line 115
Run step 5's docs drift check, unless the reviewer was dream-team:docs-reviewer.
- Very specific: line 123
Commit each item on its own.
- Distinctive: line 146
No note → close the issue.
- Very specific: line 159
Run this step from the main checkout, the first worktree path git worktree list --porcelain prints.
- Distinctive: line 162
Stop and ask whether to continue that work or start over when any holds:
- Very specific: line 180
Run cd <worktree's absolute path> as the Bash call right before the Workflow call.
- Distinctive: line 189
Never work on master/main.
- Distinctive: line 232
After them, 1-2 sentences on what the change builds, from the issue.
- Very specific: line 253
Before dispatching dream-team:lab-runner, tell the user its rough time to completion, from the run count and each run's expected length.
- Very specific: line 279
Every issue you open gets the milestone it belongs to, set at creation, and workflow::future when that milestone has an open dependency.
- Very specific: line 287
Commit anything else you changed in step 5 as fixup!
- Distinctive: line 310
After that fallback → amend the fold commit to add every other change's subject.
- Very specific: line 330
After either fold, git diff --quiet "$OLD" HEAD non-zero → stop and report: the fold changed the tree.
- Very specific: line 373
After the retry → wait until the head pipeline no longer reads failed, then restart the poll.
- Distinctive: line 406
Put nothing else under that heading.
- Distinctive: line 408
Add no line that this skill does not name.
- Very specific: line 409
Every other item is one bullet with a bold label, e.g.
- Distinctive: line 412
No blank line between bullets.
- Very specific: line 416
No MR/PR, and not a closed research issue → first post one comment on the issue: the branch, the open blocking findings, the assumptions …
- Very specific: line 422
No MR/PR and untrackedPaths non-empty → list them under one bold label.
- Distinctive: line 435
Leave out nits, applied or dropped, and reviewer verdicts with no finding.
- Very specific: line 436
Leave out gateCommands entries that passed and a summary of the change: the MR carries it.
- Very specific: line 437
Leave out a present redEvidence and lab work that did not run.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
build-issue
One issue per invocation. If the user names several, do them one at a time.
Spell <scratchpad> as your scratchpad directory's literal path.
You are the orchestrator. You read, triage, branch and ship. You do not write the change — the
workflow's implementer does. Everything between the issue branch and the MR happens in dispatched
agents. Your only edits are step 5's settled disputes, nits and small adjacent fixes, which step 6
reruns gateCommands on, a light-tier issue's edit, a research note the user asks for
(step 2a), and a step-3 decision record with the files repo-conventions.md adds with it.
Lab work is yours, not the workflow's. Workflow agents never ssh to a lab host. Anything the
issue or the repo's CLAUDE.md or AGENTS.md needs run on a lab host — a measurement the issue
asks for, a test that needs root, a perf gate — you dispatch after the workflow returns (step 5),
through dream-team:lab-runner. A light-tier issue has lab work only when it asks for a
measurement or its bug reproduces there (step 2a). No lab host named → there is no lab work. Say
so in the workflow's notes so the implementer does not try, and does not report it as an
assumption.
1. Read the issue
Fetch body, title, labels and discussion — gh issue view <n> --json title,body,labels,comments,
glab issue view <n> --comments --output json -P 100, or whatever the host's tooling skill says to
use instead.
A Meta: issue is not a work item. Pick its next child:
- Read only the checklist's unticked links to open child issues; skip plain-text lines.
- Drop each child with a
Blocked byissue still open. - Take the oldest (lowest-numbered) child left, say which, and run the rest of this skill on it.
- No unticked open child → report that the Meta issue has no work left, and stop.
- Every one blocked → report each with its open blockers, and stop.
2. Triage: is this actionable without the user?
Fail before code is written on a guess, not after.
- The issue is untriaged per
<base directory>/../triage-issue/SKILL.mdUntriaged → stop with "runtriage-issue #<n>first". - The issue has the
workflow::needs-brainstormlabel → stop with "runtriage-issue #<n>first".
Triage blocks on:
- An open decision: anything the issue leaves to a guess — which screen or endpoint, what happens on failure, whether it needs a migration, a public API or schema change, product copy or acceptance criteria.
- A credential, environment or access you don't have.
- A
Blocked by #<n>line naming an open issue.
Blocked at triage:
- Say exactly what is blocking and what you need.
- Don't half-build around the gap.
- Don't end the turn yet: do the reading that makes the choice answerable — what each option costs, how many call sites it touches, what the reference source does.
Then:
- The options are enumerable — two or three concrete paths, and the user's pick is the only thing missing: put them in an AskUserQuestion dialog, one option per path, cost in the description. Handle the answer as below, then carry straight on to step 3. Deferring the issue is an option when its tracker state says it is not due yet.
- The options are not enumerable — a missing acceptance criterion, a credential you don't have, an intent only the user knows: report what is blocking in prose and stop.
Never open a dialog whose options you had to invent to fill the slots.
The answer:
- Post it as a comment on the issue.
- Passes the test in
reference/decision-record.md→ step 3 also writes its record in its own docs MR. - Changes the work remaining → write it into the proposal and its
## Done whensection, or into a new issue that supersedes this one when the title or problem no longer holds (scope-issueUpdates).
2a. Tier
A tier the project's CLAUDE.md or AGENTS.md sets for the issue overrides the criteria below.
Research tier when the title starts Research: (below). Otherwise light tier when all hold,
for a bundle issue on each item; otherwise full (step 3 on):
- No runtime behaviour change: docs, comments, help or usage text, CI config, test fixtures, or a rename. Or a bug fix you reproduced yourself before the edit: a lab probe or a test seen failing.
- The proposal names the exact edit, or the diff changes only docs, comments or help or usage text to match the code; no design choice left.
- A bug fix's edit copies a pattern the repo already uses, in under ~50 lines in one module.
- Touches no path the project's
CLAUDE.mdorAGENTS.mdputs under a parity or perf gate, unless the change there is comments only.
Light path, no workflow:
- Branch per step 3.
- Make the edit inline.
- Run every
gateCommandsentry. - Dispatch one reviewer with the issue and the base, told to read the diff with
git diff <base>, its type picked below. - A blocking finding → fix it inline and rerun
gateCommands, or hand the branch back. - A bug fix → rerun the reproduction on the branch head and see it pass.
- Run lab work only for that rerun or a measurement the issue asks for, per step 5's lab steps.
- Run step 5's docs drift check, unless the reviewer was
dream-team:docs-reviewer. - A plain issue's diff outgrows the criteria →
git reset --hard <base>and run the full loop. - Open the MR per step 6.
- Report the tier and the criterion that allowed it.
Bundle issue (an ## Items checklist, scope-issue Bundle) on the light path:
- The bundle may span modules, and its diff may pass ~50 lines.
- Commit each item on its own; a fix to one is a
fixup!of its commit. - An item stops being light tier, or a blocking finding stops it → drop its commit and its
fixup!commits: noteHEAD,git reset --hard <base>, thengit cherry-pickevery other commit ofgit log --reverse --format=%h <base>..<noted HEAD>. - A dropped item → file it as its own issue (step 5).
- A dropped item → link its issue from its line in the bundle, box unticked.
- Ship the remaining items as one MR with one
Closes #<n>.
Light-path reviewer type:
- Docs, comments, help or usage text only →
dream-team:docs-reviewer. - Anything else →
general-purpose, told to check the diff against the reference sources and invariants the project'sCLAUDE.mdorAGENTS.mdnames, with the failing evidence for a bug fix.
Research tier: no workflow, no code. Answer the proposal's questions yourself, then:
- File the gaps per
scope-issue, light-tier ones bundled, each issue with its milestone (step 5). - The user asks for a file → write the findings as a note in the format below, commit it on the
step-3 branch, and open the MR per step 6 with
Closes #<n>. - Post every finding not in a note as one comment on the research issue, in the format below, the follow-up issues and any MR linked.
- No note → close the issue; skip step 3 and steps 6-7.
Findings format:
- A note's path:
docs/research/YYYY-MM-DD-<slug>.md. A comment has no path line. - Header: the title, then
**Date:** <date> · **Issues:** #<n>. - Context: 1-3 sentences on the setup and the versions or commits measured.
- One
##per finding, named by its claim or topic; the answer in its first sentence. - A finding left unresolved →
## Open: <claim>, naming the issue that tracks it. - Dead ends → one
## Ruled outlist.
3. Preflight and branch
Run this step from the main checkout, the first worktree path git worktree list --porcelain
prints; cd there first.
Stop and ask whether to continue that work or start over when any holds:
- A branch
issue-<n>-*ordecision-<n>-*exists locally or on the remote. - A path
.claude/worktrees/issue-<n>-*exists. - An open MR/PR references the issue.
Then git fetch and add a worktree on a new branch from the fetched tip of the MR target, the
remote's default branch unless the project's CLAUDE.md or AGENTS.md names another:
git worktree add -b issue-<n>-<slug> .claude/worktrees/issue-<n>-<slug> origin/<target>.
$(git rev-parse --git-common-dir)/info/excludehas no.claude/worktrees/line → append/.claude/worktrees/before theworktree add.- A gitignored path the issue, the Meta issue's children,
CLAUDE.mdorAGENTS.mdnames as an input → after theworktree add, symlink it from the main checkout to the same path in the worktree. $(git rev-parse --git-common-dir)/info/excludehas no line for a linked path → append the path, with no trailing slash.cdinto the worktree.- Run
cd <worktree's absolute path>as the Bash call right before the Workflow call. - A step-2 answer passed the test in
reference/decision-record.md→ name theworktree addbranchdecision-<n>-<slug>in place ofissue-<n>-<slug>. - On it, write the record at the path, naming and template
<base directory>/../../references/repo-conventions.mdresolves, commit it with the files that reference adds perscope-commit, push it and open its docs MR against<target>perscope-mr. - Comment that docs MR's link on the issue.
- Then
git checkout -b issue-<n>-<slug>: the issue branch stacks on the record commit. - Never work on
master/main. - Record
git rev-parse HEADin the worktree — it is the workflow'sbase; on a stacked branch it is the record commit, so step 6's fold leaves the record out.
4. Run the workflow
Invoke the Workflow tool with name: "dream-team:build-issue-loop" and args as a real JSON
object (never a stringified one):
{
"issue": "42",
"title": "<issue title>",
"body": "<issue description, verbatim>",
"notes": "<what the description does not carry>",
"branch": "issue-42-slug",
"base": "<sha from step 3>",
"gateCommands": ["cargo build --workspace", "cargo test --workspace", "cargo clippy --workspace"],
"externalReview": "<command, or leave out>"
}notes: decisions made in the tracker discussion, the answer the user gave at step-2 triage, and the lab work the implementer must leave alone. Optional.- Each path step 3 linked → name it in
noteswith "never commit or modify it". - The change carries a decision that passes the test in
reference/decision-record.mdand has no record yet, from step 3 or cited by the issue → name the decision innoteswith the absolute paths of that file and<base directory>/../../references/repo-conventions.md, and tell the implementer to add its record per both, in the same commit as the change. gateCommands: the build, test and lint commands the repo's CI config runs that also run in this checkout — CI config first,CLAUDE.md,AGENTS.mdand README second. The mechanical gate runs exactly these after the implementation and after every fix commit. Leave out lab work. Required.externalReview: a shell command that reads a diff on stdin and prints findings. Default unset.- A
CLAUDE.mdthe session loads — global, the project's, or itsCLAUDE.local.md— opts in to an external reviewer → setexternalReviewto the command it names. - The project's line and the global one disagree → the project's wins, including a project line that turns it off.
Then report, before the workflow returns:
- Two bullets, the label in bold: the branch, and whether
externalReviewis set. - After them, 1-2 sentences on what the change builds, from the issue.
- Nothing before the bullets or after the sentences.
Layout:
- **Branch:** `issue-42-slug`
- **External reviewer:** `yes`|`no`
<1-2 sentences: what the change builds.>5. Judge the result
The workflow returns structured, not final. Once it returns, read
reference/workflow-result.md: what each result field means and
what to do with it.
- Lab steps — once the result is
ok, run the lab work on the branch head. Treat a lab failure like a redgateCommandsrun: fix it before the MR, or hand the branch back. Put measured numbers in the MR description, or in the hand-back comment when no MR opens. - Before dispatching
dream-team:lab-runner, tell the user its rough time to completion, from the run count and each run's expected length. - Post the disputes you settle, each with which way and why, in one comment on the issue.
Docs drift, once the result is ok:
- Dispatch
dream-team:docs-reviewer, told to read the diff withgit diff <base>..HEAD, before your other step-5 edits. - Make those edits while it runs.
- A 🔴/🟡 finding you judge wrong → drop it, as a settled dispute.
- 🔴/🟡 findings left → after your edits, dispatch
dream-team:docs-editorin drift mode withgit diff <base>..HEADand only the pages they name. - 🔵 findings → treat as nits.
- The editor's edits are step-5 changes: step 6 commits and gates them.
Adjacent defects — anything found outside the diff or returned in preExisting:
- A small fix with no open decision, no lab check and no design choice (docs drift, a config
string, under ~50 lines) → commit it on the branch as its own change, never a
fixup!. - Any other research finding, review-panel survivor outside the diff or in
preExisting, bug hit running evals orgateCommands, or spec consequence nobody owns → file it perscope-issuebefore the session ends, light-tier ones bundled, and per the repo's own rules. - The finding is a nit → file nothing.
- Filed → never leave the finding in the MR description or the chat summary.
- Filing fails or yields no issue link → name the defect in the report as unfiled, with the reason.
Every issue you open gets the milestone it belongs to, set at creation, and workflow::future
when that milestone has an open dependency. Pick the milestone from the tracker's open
milestones and the planned rows of the repo's ROADMAP, found per
<base directory>/../../references/repo-conventions.md. A
planned row fits best → no milestone and workflow::future. None clearly fits → ask.
6. Open the MR/PR
Commit anything else you changed in step 5 as fixup! <subject of the commit it repairs>, one
fixup per commit an edit repairs. If you changed anything, run every gateCommands entry on the new
head yourself and carry on only when all exit 0. A red run → fix it, or hand the branch back.
Fold the branch to one commit per change. The implementer commits once per independent change;
the simplify cuts, build-fix and fix rounds add fixup! <subject> and amend! <subject>
commits, and a plain commit for a defect already on the base commit. Count the changes:
git log --format=%s <base>..HEAD | grep -Evc '^(fixup|amend)! 'More than 1 → fold each fixup! and amend! commit into the commit it names:
OLD=$(git rev-parse HEAD) && echo "$OLD" &&
git -c sequence.editor=: rebase -i --autosquash <base> &&
git diff --quiet "$OLD" HEAD &&
! git log --format=%s <base>..HEAD | grep -Eq '^(fixup|amend)! '- Rebase stops on a conflict →
git rebase --abort, fold to one commit as below, and say so in the report. - After that fallback → amend the fold commit to add every other change's subject.
- A
fixup!oramend!commit survives the rebase →git reset --hard <the sha it printed>, then stop and report its subject.
1 → fold onto the last amend! commit's body, or else the first commit's message, in one Bash
call:
OLD=$(git rev-parse HEAD) && echo "$OLD" &&
F=$(git rev-list --reverse <base>..HEAD | head -1) && [ -n "$F" ] &&
A=$(git log --format='%H %s' <base>..HEAD | awk '$2 == "amend!" { print $1; exit }') &&
{ if [ -n "$A" ]; then git log -1 --format=%b "$A"; else git log -1 --format=%B "$F"; fi; } \
> <scratchpad>/fold-msg &&
git reset --soft <base> && git commit -F <scratchpad>/fold-msg &&
git diff --quiet "$OLD" HEAD- Load
scope-commitbefore the fold commit or an amend. - Amend the message when it breaks
scope-commitor the fix rounds changed what the commit does.
After either fold, git diff --quiet "$OLD" HEAD non-zero → stop and report: the fold changed the
tree.
untrackedPathsnon-empty → list them to the user before you push.
Then push and open the MR/PR against the branch the project's CLAUDE.md or AGENTS.md names.
Link the issue so it auto-closes (Closes #<n>). Write the description review-facing; a scope-mr
skill, if present, is the source of truth for it.
- A stacked branch → the description says the MR depends on the step-3 docs MR, by its link.
7. Watch the MR/PR
Once the MR/PR is open, start a Bash run_in_background poll that exits on a final state,
merged or closed, or when the pipeline for the MR/PR head finishes — never on "not open":
GitLab reports a transient locked while it merges. Poll every 30s through the host's tooling
skill, e.g.:
h=$(git rev-parse HEAD)
until s=$(glab api "projects/<p>/merge_requests/<iid>" | jq -r .state) &&
p=$(glab api "projects/<p>/merge_requests/<iid>/pipelines" |
jq -r --arg h "$h" 'map(select(.sha == $h))[0].status')
[ "$s" = merged ] || [ "$s" = closed ] || [ "$p" = success ] || [ "$p" = failed ]; do
sleep 30
done
echo "$s $p"- GitHub → state from
gh pr view <n> --json state, pipeline fromgh run list --commit "$h" --json status,conclusion: finished once it lists runs and all arecompleted, failed when one concludesfailure.
Give the report (below) without waiting for the poll, and leave the poll out of it. When it exits:
- Pipeline passed → restart the poll on
mergedorclosedonly. - Pipeline failed → read the failing job's log with the
ci-logsskill if present, else the host's tooling skill; judge it a real failure or an infrastructure flake (runner, network or registry, not the code). - A flake → retry that job once (
glab api -X POST projects/<p>/jobs/<id>/retry,gh run rerun --job <job-id>); a retry does not count as a fix push. - After the retry → wait until the head pipeline no longer reads
failed, then restart the poll. - The retried job fails again → handle it as real.
- A real failure → dispatch one
general-purposeagent with the failing log excerpt, the worktree path, the base andgateCommands, told to make the smallest fix, run everygateCommandsentry and commit it asfixup! <subject of the commit it repairs>. - Its
fixup!committed withgateCommandsgreen → fold per step 6,git push --force-with-lease, and restart the poll. - A real failure after 2 fix pushes, or an agent that commits no green fix → stop fixing, post a
CI hand-back comment on the MR/PR with the failing job link, and restart the poll on
mergedorclosedonly. - Review comments on the MR/PR → leave them to the user.
- Merged →
cdto the main checkout (step 3), run the block below, then check the issue closed. Report one line: new<target>head, worktree and branch deleted, issue state. - The main checkout is not on
<target>, or itsgit status --porcelainprints anything → rungit fetchin place ofgit pull --ff-only, and say so in the report. - A stacked branch → also run
git branch -d decision-<n>-<slug>after the block. - The block fails → report the git error; leave the worktree and the branch.
- Closed unmerged →
cdto the main checkout,git worktree remove .claude/worktrees/issue-<n>-<slug>, report it; leave the branch.
git worktree remove .claude/worktrees/issue-<n>-<slug> &&
git pull --ff-only && git branch -d issue-<n>-<slug>Report back
The report carries only what the user must know or act on.
- Open with each
assumptionsentry that departs from the issue's text or changes behaviour a user or caller can observe, and that no written rule or instruction settles, as its own list under a**Assumptions:**heading. - Put nothing else under that heading.
- An assumption that a
questionsentry also raises → show it once, under**Questions:**. - Add no line that this skill does not name.
- Every other item is one bullet with a bold label, e.g.
**Dispute accepted:**,**Lab:**. - Three or more numbers compared across cases (variants, runs, before/after) → one table, a row per case, under its bold label; never a bullet.
- No blank line between bullets.
- Assumptions above the bullets → put a
**Notes:**line between them. - End with one plain line, after a blank line:
Work on #<n> is done: <MR/PR link>. - Research issue closed by its findings comment → end with
Work on #<n> is done: <comment link>. - No MR/PR, and not a closed research issue → first post one comment on the issue: the branch,
the open blocking findings, the assumptions and questions the report shows, the lab numbers
when lab work ran, and the
<why>. - Then end with
Work on #<n> is handed back: <branch> in .claude/worktrees/issue-<n>-<slug> — <why> (<hand-back comment link>). - Name each
degradedroster type, and each dead reviewer the hand-back<why>does not name. - No MR/PR and
untrackedPathsnon-empty → list them under one bold label. - Name each dispute you settled, which way, and why.
- List each distinct question in
questionsas one sub-bullet of one**Questions:**bullet, naming every reviewer that asked it, and its location. - Name each adjacent fix committed on the branch by its subject, one line each.
- Name each issue filed for an adjacent defect by its link, one line each, never the defect itself.
- Name each adjacent defect that could not be filed, and why, one line each.
- Say so when
redEvidenceis empty on a bug fix. - Give a lab step one line: its verdict, or its numbers when there are fewer than three.
- Give each pipeline failure step 7 acts on one
**Pipeline:**line in a follow-up message: the job, real or flake, and the fix commit. - Name each reviewer that could not check something, and the check you ran in its place.
- Stopped at triage → say what is blocking and stop there.
- Leave out nits, applied or dropped, and reviewer verdicts with no finding.
- Leave out
gateCommandsentries that passed and a summary of the change: the MR carries it. - Leave out a present
redEvidenceand lab work that did not run. - A review with no blocking finding, no question, no dispute and no fix round gets no line.
- Handed back → no line saying a reviewer found nothing or that nothing was disputed.
- The hand-back
<why>clause names only what blocks; it never adds that other reviewers, rounds or disputes came back clean.
Layout, with sections that have nothing to report left out:
**Assumptions:**
- <assumption>
**Notes:**
- **Conventions:** <path, naming> (<source>)
- **Dispute accepted:** <finding> — <why>
- **Lab:** <verdict>
- **Questions:**
- <question> — <reviewer>[, <reviewer>…][, <file>]
**Lab, master vs branch:**
| Run | master | branch |
|---|---|---|
| <case> | <number> | <number> |
Work on #<n> is done: <MR/PR link>Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

