run-bug
Fix one or more bugs (or follow-up tasks) from the tracker by driving the user's repo sessions over cross-session messages, the way run-slice drives a story. Triages each bug first, assigns it to the user and starts it, sends it to the session that owns the code, and tells that s
Install
npx skills add https://github.com/Beakpoint-Insights/roost/tree/main/skills/run-bug
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install beakpoint-insights-roost@llmmart
git clone https://github.com/Beakpoint-Insights/roost.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole beakpoint-insights/roost collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Run Bug
You coordinate a bug fix the way run-slice coordinates a story. You never edit, build or run tests in any repo yourself. One session per repo in the config's repos does the work, through SendMessage. Find them, talk to them and wait for them exactly as run-slice describes ("Find the sessions" and "How to talk to the sessions").
First, load the team config with roost-config.
Being asked to fix the bug is the go-ahead. Don't ask for another one. Tell the user what you started, and stop only for their decisions and real blockers. While a session works, give the user run-slice's 5-minute progress updates, without being asked: its three formats and its update prompt, with {STORY} the bug being worked on and {LOG} the first bug's key (<team.state_dir>/<first bug>-updates.md).
Inputs
- BUGS: one or more ticket keys. A follow-up Task is handled the same way as a Bug.
- The session for each repo the fixes touch must be open. If one isn't, that's a blocker: ask the user to open it, and stop.
1. Triage
For each ticket, judge it the triage-ticket way, by reading the ticket and the code, without changing anything:
- Real, and the ticket is right: go on.
- Wrong, already fixed, or not worth fixing: don't start it. Put it in one message to the user with what you found and a recommendation (close it, change it, or fix something else), and wait for their decision on those tickets only. Carry on with the others.
2. Decide where each fix goes
Read each ticket's parent:
| Bug | Where the fix goes | What it waits for |
|---|---|---|
| Part of an epic that isn't released yet | On top of the epic's stack in the repo that owns the code, as its own branch named for the ticket | Ships with the epic. Add its PR to the epic's Release order comment, and keep the epic's Carry-over comment current. |
| Standalone (no parent, or its epic is already released) | A branch from main and its own PR |
Released on its own once merged |
Released means the epic's code is in production, not that the epic ticket is closed: an epic can stay open after release for its person-owned tasks. It's released when its Close-out comment says what's in production (close-out-epic step 6), or its stories carry a fix version that's released. If neither says so, treat it as unreleased.
Several bugs of one epic stack on each other in the order the user gave.
Which repo: the one whose code is wrong, from the ticket's Components, each repo's owns, and the code. A bug that needs more than one repo follows step 4.
3. Start each bug
- Assign it to the person running this session (see "Who am I" in the tracker adapter) and move it to
tracker.statuses.in_progress. - Send it to the owning session: "Use the
bug-bashskill for PROJ-X." Then give the branch and base from step 2, for example: "BranchPROJ-Xstacked onPROJ-2790-backend" or "BranchPROJ-Xfrommain, its own PR". Add:- a PR title that follows
vcs.pr_title, for examplefix(PROJ-X): …; - a test that fails first, then the fix;
- if the bug has a test, automate its scenario (
automate-tests); if it has none and the behaviour could regress, add or update one first (the tests adapter's "Create a test" or "Update a test's scenarios"); - for a repo others depend on: after the fix,
stack.restart_after_api_changeand check the fix on the running stack; - judge CI by each check's newest completed result, and don't re-run cancelled runs;
- send the report as the last thing it does, with no promise of a later report.
- a PR title that follows
- End the message with the report request: Status, Branch and PR, Commit, Tests run (pass/fail counts), Live check (what was checked on the running stack), CI, Concerns (everything noticed), and Needs from the user. Every claim about the code or data cites its
file:line, or the query and its result; anything not checked says "unknown", never a guess.
Send one session several bugs in one message only when they're in the same repo and the same epic; otherwise one message per bug.
4. A bug that needs more than one repo
- Write each repo's part with
cross-repo-handoff. - Send them in
reposorder, each to its session, on its branch from step 2. Wait for each report before the next. - Before sending a part to a repo with
depends_on, askstack.owner_repo's session tostack.restart_after_api_changeon the new build, and check yourself that the stack serves the change. - A dependent repo's part follows its
contract(for example regenerating a client against the running API, never checking out the other repo).
5. Verify and close
A bug is done when all of these are true:
- the fix's test failed before the fix and passes after;
- its test scenario, if any, is automated and passing, and the test is marked automated (the tests adapter's "Mark a test automated");
- its PR is where step 2 says, and every check's newest completed result passes;
- for an epic bug, its PR is in the epic's Release order comment;
- if it added a database migration and
deploy.migrations_run_on_deployis false, a deploy note covers it: the Migrations to apply comment and the staging and production pre-deploy sub-tasks, on the epic's deploy ticket or, for a standalone bug, on the bug itself (seestacked-prs). Add or update them if they're missing. - the owning session ran
/code-reviewon the fix's own diff (its branch against the branch below it, ormainfor a standalone bug), and each finding is fixed, or decided by the user like any other finding.
Then move the ticket to tracker.statuses.ready_for_release (without stacking, once the user has merged its PRs; "Without stacking" in roost-config) (a session that already did is fine; read it back). New problems a session found along the way become tickets for later only with the user's decision: list them in the report with a recommendation.
Report to the user
Anything the user must do first, in a 🙋 Your turn block (leave it out when there's nothing). Then one line: "PROJ-2822 fixed on the PROJ-2306 stack (#580), Ready for Release." Then one row per bug:
| Bug | Where | PR | Test | Status |
|---|---|---|---|---|
| PROJ-2822 | PROJ-2306 stack | #580 | ProcessRequest_SpanWithoutAttributes_… failed first, passes |
Ready for Release |
Files (roost)
-
SKILL.md 7.2 KB
--- name: run-bug description: Fix one or more bugs (or follow-up tasks) from the tracker by driving the user's repo sessions over cross-session messages, the way run-slice drives a story. Triages each bug first, assigns it to the user and starts it, sends it to the session that owns the code, and tells that session where the fix goes, on the epic's stack when the bug belongs to an unreleased epic or from main as its own PR when it's standalone. For a fix that needs more than one repo it builds each repo's part in order, restarting the stack between them. Then verifies the fix with a test that failed first, the ticket's test scenario if it has one, and CI green. Starts without asking and stops only for the user's decisions and real blockers. Never edits any repo itself. Use when the user says "fix PROJ-X", "run bug PROJ-X", "have the API agent fix this", or "tackle these bugs". Run it from a separate orchestrator session, not from inside any of the repos. --- # Run Bug You coordinate a bug fix the way `run-slice` coordinates a story. You never edit, build or run tests in any repo yourself. One session per repo in the config's `repos` does the work, through `SendMessage`. Find them, talk to them and wait for them exactly as `run-slice` describes ("Find the sessions" and "How to talk to the sessions"). **First, load the team config with `roost-config`.** Being asked to fix the bug is the go-ahead. Don't ask for another one. Tell the user what you started, and stop only for their decisions and real blockers. While a session works, give the user `run-slice`'s 5-minute progress updates, without being asked: its three formats and its update prompt, with `{STORY}` the bug being worked on and `{LOG}` the first bug's key (`<team.state_dir>/<first bug>-updates.md`). ## Inputs - **BUGS:** one or more ticket keys. A follow-up Task is handled the same way as a Bug. - The session for each repo the fixes touch must be open. If one isn't, that's a blocker: ask the user to open it, and stop. ## 1. Triage For each ticket, judge it the `triage-ticket` way, by reading the ticket and the code, without changing anything: - **Real, and the ticket is right:** go on. - **Wrong, already fixed, or not worth fixing:** don't start it. Put it in one message to the user with what you found and a recommendation (close it, change it, or fix something else), and wait for their decision on those tickets only. Carry on with the others. ## 2. Decide where each fix goes Read each ticket's parent: | Bug | Where the fix goes | What it waits for | |---|---|---| | **Part of an epic that isn't released yet** | On top of the epic's stack in the repo that owns the code, as its own branch named for the ticket | Ships with the epic. Add its PR to the epic's **Release order** comment, and keep the epic's **Carry-over** comment current. | | **Standalone** (no parent, or its epic is already released) | A branch from `main` and its own PR | Released on its own once merged | **Released** means the epic's code is in production, not that the epic ticket is closed: an epic can stay open after release for its person-owned tasks. It's released when its **Close-out** comment says what's in production (`close-out-epic` step 6), or its stories carry a fix version that's released. If neither says so, treat it as unreleased. Several bugs of one epic stack on each other in the order the user gave. **Which repo:** the one whose code is wrong, from the ticket's Components, each repo's `owns`, and the code. A bug that needs more than one repo follows step 4. ## 3. Start each bug 1. Assign it to the person running this session (see "Who am I" in the tracker adapter) and move it to `tracker.statuses.in_progress`. 2. Send it to the owning session: "Use the `bug-bash` skill for PROJ-X." Then give the branch and base from step 2, for example: "Branch `PROJ-X` stacked on `PROJ-2790-backend`" or "Branch `PROJ-X` from `main`, its own PR". Add: - a PR title that follows `vcs.pr_title`, for example `fix(PROJ-X): …`; - a test that fails first, then the fix; - if the bug has a test, automate its scenario (`automate-tests`); if it has none and the behaviour could regress, add or update one first (the tests adapter's "Create a test" or "Update a test's scenarios"); - for a repo others depend on: after the fix, `stack.restart_after_api_change` and check the fix on the running stack; - judge CI by each check's newest completed result, and don't re-run cancelled runs; - send the report as the last thing it does, with no promise of a later report. 3. End the message with the report request: **Status**, **Branch and PR**, **Commit**, **Tests run** (pass/fail counts), **Live check** (what was checked on the running stack), **CI**, **Concerns** (everything noticed), and **Needs from the user**. Every claim about the code or data cites its `file:line`, or the query and its result; anything not checked says "unknown", never a guess. Send one session several bugs in one message only when they're in the same repo and the same epic; otherwise one message per bug. ## 4. A bug that needs more than one repo 1. Write each repo's part with `cross-repo-handoff`. 2. Send them in `repos` order, each to its session, on its branch from step 2. Wait for each report before the next. 3. Before sending a part to a repo with `depends_on`, ask `stack.owner_repo`'s session to `stack.restart_after_api_change` on the new build, and check yourself that the stack serves the change. 4. A dependent repo's part follows its `contract` (for example regenerating a client against the running API, never checking out the other repo). ## 5. Verify and close A bug is done when all of these are true: - the fix's test failed before the fix and passes after; - its test scenario, if any, is automated and passing, and the test is marked automated (the tests adapter's "Mark a test automated"); - its PR is where step 2 says, and every check's newest completed result passes; - for an epic bug, its PR is in the epic's Release order comment; - if it added a database migration and `deploy.migrations_run_on_deploy` is false, a deploy note covers it: the **Migrations to apply** comment and the staging and production pre-deploy sub-tasks, on the epic's deploy ticket or, for a standalone bug, on the bug itself (see `stacked-prs`). Add or update them if they're missing. - the owning session ran `/code-review` on the fix's own diff (its branch against the branch below it, or `main` for a standalone bug), and each finding is fixed, or decided by the user like any other finding. Then move the ticket to `tracker.statuses.ready_for_release` (without stacking, once the user has merged its PRs; "Without stacking" in `roost-config`) (a session that already did is fine; read it back). New problems a session found along the way become tickets for later only with the user's decision: list them in the report with a recommendation. ## Report to the user Anything the user must do first, in a 🙋 **Your turn** block (leave it out when there's nothing). Then one line: "PROJ-2822 fixed on the PROJ-2306 stack (#580), Ready for Release." Then one row per bug: | Bug | Where | PR | Test | Status | |---|---|---|---|---| | PROJ-2822 | PROJ-2306 stack | #580 | `ProcessRequest_SpanWithoutAttributes_…` failed first, passes | Ready for Release |
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.