toado-triage skill

toado-triage is the canonical Toado skill. It packages a four-mode triage flow so you can fix one ticket or a whole column with one line. The skill is opinionated about two things: load the smallest context that lets you act, and keep the kanban honest in real-time so a ticket sitting in To Do really is unstarted.

Current skill version: 2026-05-22.

The four modes

The skill infers the mode from how you phrase the ask. You do not pick a mode explicitly.

Mode	How you trigger it	What it does
Single ticket	fix t-XXX, fix /tickets/t-XXX, or a https://app.toado.dev/tickets/t-XXX URL	Load, move to In Progress, fix, commit, comment, move to In Review. Stop.
Sweep To Do	fix everything in <project>, work the toado queue for <project>, process To Do for <project>	Walk the To Do column oldest first, fix each one, move to In Review. Re-lists the column on every iteration so newly-filed tickets get picked up.
Verify In Review	review the In Review queue for <project>, sweep In Review, make sure In Review is good	For each ticket in In Review, use the commit SHA in its fix comment to confirm the diff still lands. Passing tickets move to Done; failures bounce back to To Do with a reason.
Build tests	build tests for <project>, cover the needs-tests column	Walk a tests / needs tests / tests needed column, write a test that would have caught each original bug, run it, move to Done.

If the phrasing is ambiguous, the skill defaults to single-ticket mode when a ticket id or URL is present, otherwise it asks.

The column workflow it expects

The skill resolves your project’s column names case-insensitively at the start of each run. It looks for:

Column the skill needs	Matches against
In Progress	in progress
Response Required	response required, responded, blocked, waiting, needs input
In Review	in review
Done	done
Tests / Needs tests	tests, needs tests, needs tests built, tests needed (build-tests mode only)

Every column the skill moves a ticket into needs to exist. If your target column for the mode is missing (e.g. you have no In Review), the skill asks where to move things before starting; it will not silently pick a wrong column.

Response Required is the newer column

New projects ship with a Response Required column between In Progress and In Review for tickets the agent is blocked on. Older projects that do not have it get the legacy fallback: the ticket stays in In Progress and the comment starts with [BLOCKED]. Either way, blocked work is visibly distinct from unstarted work.

What each ticket actually goes through

For each ticket the skill works, in order:

1. Already-fixed check. git log --all --oneline --grep="t-XXX" plus a scan of existing comments for the Fix in <sha>: ... template. If the ticket has already been fixed and the diff still lands on the branch, the skill skips straight to “move to In Review” with an Already fixed in <sha> comment.
2. Move to In Progress. Visibility step. The kanban now shows what is actively in flight, especially useful during a sweep where 5+ tickets are running.
3. Load context cheaply. Start with a bare get_ticket (~5-10 KB: title, description, source URL, column, comments count). Extract acceptance criteria from the description (one ticket can describe two distinct bugs; both have to be addressed). Map the source URL back to a file in your codebase. Try to fix from this alone. Only escalate to comments, screenshots, structured annotations, or DevTools when the description genuinely is not enough.
4. Fix the code. Anchor the search on the most specific thing in the ticket (a user-visible string, the route in the source URL, a function name from a console error). Keep the edit minimal and scoped; no opportunistic refactors of neighboring code.
5. Verify. Typecheck the affected app; for build-tests mode the test passing is the verification.
6. Commit, comment, move. Commit with the ticket id in the message, grab the SHA, post a structured fix comment, move the ticket forward.

The comment template the skill posts

Fix in <commit-sha-short>: <files>

Acceptance criteria:
✓ <criterion 1, restated>
✓ <criterion 2, restated>
(or ✗ <criterion>: <why it was not addressed, ticket becomes BLOCKED>)

[VISUAL] Reviewer: <what to look at, only when a human eye is genuinely required>

The [VISUAL] tag is used sparingly. Behavioral fixes that typecheck or pass tests do not get it; only CSS, layout, contrast, color, and copy-placement fixes do. Tagging everything trains reviewers to ignore the tag.

For deduped tickets (see below), the comment collapses to a single line: Addressed by fix for t-PRIMARY (commit <sha>): same root cause.

Where it moves tickets

Mode	From	To
Single fix (success)	In Progress	In Review
Single fix (blocked)	In Progress	Response Required
Sweep To Do (success)	In Progress	In Review
Sweep To Do (blocked)	In Progress	Response Required
Verify In Review (passes)	In Review	Done
Verify In Review (fails)	In Review	To Do
Build tests	Needs tests	Done

When the target column is Done, the skill also calls update_ticket(resolved: true). Moves to In Review, In Progress, To Do, and Response Required leave resolved alone. Resolved is the verify-pass signal, not a triage-pass signal.

Duplicate detection (sweep To Do mode)

Before the per-ticket loop, the skill scans the To Do column for likely duplicates. Two tickets are grouped as a dup pair when they share the same source URL AND have either heavy description token overlap (≥60% of the shorter description’s tokens appear in the longer one) or reference the same user-visible string (a button label, an error message).

The oldest ticket in a group is the primary. The skill fixes the code under the primary, then on each non-primary it posts a one-line dedup comment pointing at the primary’s SHA and moves the non-primary to In Review. You get one commit and clear cross-links instead of four redundant fixes.

When in doubt, the skill does not dedup. Fixing twice is cheap; missing a real bug is not.

Verify mode in detail

For each ticket in In Review, the skill:

1. Loads the ticket and its comments.
2. Finds the most recent Fix in <sha>: ... comment.
3. With a SHA: git log --oneline <sha>..HEAD -- <files-from-comment> to detect later changes that may have reverted the fix. git show <sha> to see the original diff.
4. Without a SHA (older comments before this template): falls back to grepping current code for the described change. Less reliable; the run summary notes the lower confidence.
5. Re-checks each acceptance criterion from the original description against the current code.
6. Passes → move to Done with a brief verified comment; resolved: true.
7. Fails → move to To Do with [REOPENED] <reason>. Verify mode does not try to re-fix; that conflates two intents.

Cost discipline

The single biggest mistake on this skill is over-fetching. A full get_ticket with every include can be ~1.8 MB. Empirically, around 60% of tickets are fixable from the description plus the source URL plus a code grep. The skill is built to:

• Start with a bare get_ticket, no include.
• Escalate to comments only when commentCount > 0.
• Pull the annotated screenshot only when the description references something visual (“the circled X”, “where I drew”, “this layout”).
• Pull DevTools (include: ["devtools"]) only when the description names a runtime error or you genuinely need network or console evidence.
• For very large DevTools payloads, delegate the read to a subagent so it stays out of the main context.

The skill drops downloaded screenshots into .tmp/toado/ (gitignored) during a run and sweeps the directory at the end. Interrupted runs leave files behind; the next clean completion cleans them up.

Sweep preamble

Before processing a column ticket-by-ticket, the skill announces:

Sweep starting: <project name> — <mode>
Tickets to process: <N> in <column>

If N > 5, it pauses for confirmation so you can interrupt if it’s more than you expected (e.g. “this will fix all 12 To Do items, go ahead?”). For small sweeps (≤ 5), it announces and proceeds.

What the skill will not do

The skill stops, comments with [BLOCKED], and moves to Response Required (or stays in In Progress with the legacy fallback) when it hits any of these:

• Ambiguous description: cannot determine what to change.
• Cannot locate the code: anchor search returns nothing after the cheap-context pass.
• Scope too large: fix touches more than 3 files or needs architectural decisions.
• Needs a product or design decision: not the agent’s call to make.
• Schema, migrations, or auth changes: flagged for human review even when obvious.
• Cross-project: the bug references a different project’s code.

Resume semantics

Sweeps are idempotent. If you Ctrl-C halfway through a batch (or Claude Code crashes):

• Already-fixed tickets are out of To Do; they were moved to In Review per ticket.
• In-flight tickets are visible in In Progress.
• The commit history has each completed fix.
• Re-running the same command (fix everything in <project>) picks up where the column currently is. The step-0 already-fixed check skips anything whose fix landed but whose ticket move did not happen.

Final report

After a run, the skill prints a tight summary using these glyphs:

Toado triage — <project name> (<mode>)
✓ t-aaaaaa — Fixed Add-button contrast (ProjectViewsPage.tsx) → SHA abc1234
✓ t-bbbbbb — Renamed mislabeled column header → SHA def5678
↳ t-cccccc — Deduped under t-aaaaaa (same root cause)
⊘ t-ddddd0 — Already fixed in abc1234; moved to In Review
⚠ t-eeeee1 — Blocked: needs design call on empty-state copy → moved to Response Required
↩ t-fffff2 — Bounced from In Review back to To Do (description not addressed)

No diffs in the summary; the user can read those in the commits and ticket comments.

Pre-run checklist

Before running for the first time on a project:

• The Toado MCP is connected (mcp__toado__* tools available). See Quickstart.
• The token scopes include read, comments, tickets:write. The skill uses tickets:assign only when you explicitly ask it to assign.
• The project’s columns include the ones the skill needs for the mode you intend to use (see the column table above).
• You are inside the codebase the tickets are about. The skill edits files locally; it cannot reach into other repos.

Install

The fastest path is to download the packaged skill from your Toado account. It bundles SKILL.md plus any helper files; unzip into ~/.claude/skills/.

Download toado-triage from your account →

After download:

unzip toado-triage.zip -d ~/.claude/skills/

Restart Claude Code. The skill is available as soon as you reference a ticket or use one of the trigger phrases. There is no slash command to invoke; the skill activates automatically when Claude Code sees a Toado ticket id, URL, or one of the mode trigger phrases above.

After install

In any Claude Code session:

fix t-abc123

or

fix everything in acme-web

First runs: watch the announcement

For sweeps with more than 5 tickets the skill pauses for confirmation. Use that pause the first time you run it on a project to sanity-check that the count matches what you expected. Once you have built confidence, the pause is just a heartbeat.

Where to next

• Recipes for variants on the triage pattern (older, simpler reference; the modes above absorb most of those use cases).
• Authoring your own when you want a project-specific variant.
• Triage workflow for the underlying pattern in plain prose, without the skill scaffolding.
• Tools reference for every MCP tool the skill calls.