agentleFS
kdoddy36615kdoddy36615/bug-reviewer/.claude/skills/bug-triage-session/SKILL.md

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

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
  1. Distinctive:

    Never commit fixes or open the PR before the reviewer has approved every bug.

    line 21
  2. Very specific:

    Resume check: read /tmp/bug-session-state.json if it exists.

    line 27
  3. Distinctive:

    Do not batch all fixes before capturing.

    line 74
  4. Very specific:

    After the reviewer exits, read results.json.

    line 82
  5. Distinctive:

    Reviewer before commit: Always.

    line 124
  6. Distinctive:

    Never guess on uncertain fixes: Ask.

    line 126

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 PR

Never commit fixes or open the PR before the reviewer has approved every bug. No exceptions.


Session startup — always do this first

  1. Resume check: read /tmp/bug-session-state.json if it exists. If there are activeBugs, finish or roll them back (via ado-bug-lifecycle) before starting anything new.
  2. Verify dev server: curl -sk $PREVIEW_BASE_URL | head -5. If it fails, tell the user to run $DEV_COMMAND in the target repo and stop.
  3. Source env: confirm $AZURE_ASSIGNEE_EMAIL, $STORYBLOK_MANAGEMENT_TOKEN, $DRAFT_SECRET_TOKEN, $TARGET_REPO_PATH are set. If missing, tell the user to run set -a && source .env && set +a.
  4. Cut a clean branch in the target repo:
    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 repo
    Branch name should hint at the batch (e.g. cms/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:

DifficultyCriteria
EasyPure CSS/Tailwind fix, well-understood component, high confidence, single file
MediumLogic change, multiple files, or moderate uncertainty
HardArchitecture 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:

  1. Pick up — invoke ado-bug-lifecycle to store PREV_ASSIGNEE, set state to Active, assign to self, and write the session state file.
  2. Create the CMS story (if your stack uses one) — invoke storyblok-bugfix-story to create and publish an isolated preview story.
  3. Capture the CURRENT (broken) screenshot — invoke bug-capture with code still unfixed.
  4. Implement the code fix in the target repo.
  5. Run the type-checker for the target repo (e.g. pnpm type-check); ignore pre-existing errors.
  6. Capture the FIXED screenshot — invoke bug-capture again.
  7. Append the merged payload to bugs.json (see bug-capture for 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.tsx or equivalent)
  • Storybook stories updated where applicable (.stories.tsx or 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:

  1. PR link
  2. Table of bugs fixed (use the format from ado-pr-create)
  3. 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 Active ends in either a PR or a rollback — see ado-bug-lifecycle. No bug stays orphaned.
  • The dev server must be running at $PREVIEW_BASE_URL before any screenshots.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.