bug-triage-session
Skill0 starsChanged 6 months agoMITView on GitHub
Run an end-to-end bug triage session against the configured ADO board — query new bugs, rank, fix Easy ones in a batch, run the local reviewer UI, and open a draft PR. Use when the user says "bug triage session", "fix new bugs", "start a bug session", "process new bugs", or similar. This is the orchestrator skill — it invokes the domain skills in sequence.
- Reads credentials
- Installs packages
- Commits and pushes
In this repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ado-bug-lifecycleSkill
- ado-bug-querySkill
- ado-pr-createSkill
- bug-captureSkill
- bug-reviewer-runSkill
- storyblok-bugfix-storySkill
- storyblok-component-pushSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Never commit fixes or open the PR before the reviewer has approved every bug.
- Very specific: line 27
Resume check: read /tmp/bug-session-state.json if it exists.
- Distinctive: line 74
Do not batch all fixes before capturing.
- Very specific: line 82
After the reviewer exits, read results.json.
- Distinctive: line 124
Reviewer before commit: Always.
- Distinctive: line 126
Never guess on uncertain fixes: Ask.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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
Bug Triage Session — Orchestrator
You are running an end-to-end bug fix session against the configured target codebase. This skill owns sequencing. Domain work delegates to other skills.
Critical sequence
The reviewer is the gate, not an afterthought. The correct order is:
story → current screenshot → fix → fixed screenshot → repeat for all bugs
→ reviewer (BEFORE commit) → commit → draft PRNever commit fixes or open the PR before the reviewer has approved every bug. No exceptions.
Session startup — always do this first
- Resume check: read
/tmp/bug-session-state.jsonif it exists. If there areactiveBugs, finish or roll them back (viaado-bug-lifecycle) before starting anything new. - Verify dev server:
curl -sk $PREVIEW_BASE_URL | head -5. If it fails, tell the user to run$DEV_COMMANDin the target repo and stop. - Source env: confirm
$AZURE_ASSIGNEE_EMAIL,$STORYBLOK_MANAGEMENT_TOKEN,$DRAFT_SECRET_TOKEN,$TARGET_REPO_PATHare set. If missing, tell the user to runset -a && source .env && set +a. - Cut a clean branch in the target repo:
Branch name should hint at the batch (e.g.cd $TARGET_REPO_PATH git checkout dev && git pull origin dev git checkout -b cms/bugfix/<short-descriptive-name> pnpm install # or npm/yarn equivalent for the target repocms/bugfix/triage-2026-05-09).
Step 1 — Query and rank bugs
Invoke ado-bug-query to get the list of New bugs with full details and screenshots downloaded.
Rank each bug Easy / Medium / Hard:
| Difficulty | Criteria |
| Easy | Pure CSS/Tailwind fix, well-understood component, high confidence, single file |
| Medium | Logic change, multiple files, or moderate uncertainty |
| Hard | Architecture change, unclear root cause, CMS schema change needed, or cross-package impact |
Only fix Easy bugs in this session. List Medium/Hard for the user at the end.
Stop conditions — ask the user, do not guess
- Uncertain about the correct fix (e.g. which gradient is expected, which design variant) — stop and ask before implementing.
- Bug cannot be reproduced in an isolated CMS story (e.g. it requires referencing another story, or a page configuration that can't be recreated) — stop and tell the user. Do not proceed without a way to capture before/after screenshots.
Step 2 — Fix each bug, one at a time
For each Easy bug, in sequence:
- Pick up — invoke
ado-bug-lifecycleto storePREV_ASSIGNEE, set state toActive, assign to self, and write the session state file. - Create the CMS story (if your stack uses one) — invoke
storyblok-bugfix-storyto create and publish an isolated preview story. - Capture the CURRENT (broken) screenshot — invoke
bug-capturewith code still unfixed. - Implement the code fix in the target repo.
- Run the type-checker for the target repo (e.g.
pnpm type-check); ignore pre-existing errors. - Capture the FIXED screenshot — invoke
bug-captureagain. - Append the merged payload to
bugs.json(seebug-capturefor schema).
Do not batch all fixes before capturing. The current screenshot must be taken before the fix is applied — once the code changes, you can't recover the broken state.
Step 3 — Run the reviewer (BEFORE commit)
Invoke bug-reviewer-run with the populated bugs.json. Wait for the user to finish reviewing.
After the reviewer exits, read results.json. For any bug with "status": "feedback" — address the feedback before proceeding. Do not move on to commit/PR until every bug is approved.
Step 4 — Pre-PR completion checklist
Before committing, verify:
- Unit tests updated where applicable (
.test.tsxor equivalent) - Storybook stories updated where applicable (
.stories.tsxor equivalent) - Docs updated where applicable
- Type-checking passes (ignore pre-existing errors)
- Build artifacts stashed or
.gitignored - No AI tool references in committed files or commit messages
Step 5 — Commit and open draft PR
git add <specific files>
git commit -m "Bug fixes: <short description>"
git push -u origin <branch-name>No git add -A — stage specific files only. No AI references in commit messages.
Then invoke ado-pr-create with the list of work item IDs.
Step 6 — Report to user
Give the user:
- PR link
- Table of bugs fixed (use the format from
ado-pr-create) - Medium/Hard bugs with one-line difficulty reasoning — ask whether to continue with a Medium/Hard pass
Hard rules
- Reviewer before commit. Always.
- Easy only in a triage session. Medium/Hard go to the user for explicit approval.
- Never guess on uncertain fixes. Ask.
- Every bug set to
Activeends in either a PR or a rollback — seeado-bug-lifecycle. No bug stays orphaned. - The dev server must be running at
$PREVIEW_BASE_URLbefore any screenshots.
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.

