agentleFS
gaia-researchgaia-research/gaia-skill-heaven/.agents/skills/gaia-triage/SKILL.md

gaia-triage

Skill4 starsChanged 12 days agoMITView on GitHub

Triage the Gaia issue backlog and skill-batch intake queue. Use this skill when someone asks to: "triage issues", "clean up the issue tracker", "review the backlog", "close stale issues", "process the intake queue", "review skill-batches", "evaluate draft skill proposals", "approve or reject pending skills", "is this issue still valid?", "what's clogging the backlog?", "run a triage pass", or /gaia-triage. Covers two workstreams: (1) GitHub issue lifecycle — identifying resolved, stale, or need-more-info issues and acting on them via gh CLI; (2) skill-batch intake — evaluating draft proposals in registry-for-review/skill-batches/ and routing them toward promotion or rejection. This is the gatekeeping step before new skills enter the canonical registry; and (3) a cross-repo triage sweep — sizing, P0-P4 prioritization, umbrella/epic synthesis, and assignment across every gaia-research org repo, on the one headquarters tracker.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every triaged issue gets a size and a priority.

    line 54
  2. Distinctive:

    Idempotency: If an issue already carries an appropriate priority and size, do not relabel it.

    line 97
  3. Very specific:

    Before commenting or closing, verify the claim.

    line 123
  4. Distinctive:

    After promotion, regenerate Class S artifacts:

    line 229
  5. Distinctive:

    Use this when the ask is "triage the backlog" at scale rather than "is this one issue still valid".

    line 239
  6. Distinctive:

    Run all four on every issue in scope, in order:

    line 245
  7. Distinctive:

    Assignment: Default to the original issue author unless someone is already assigned.

    line 261

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

gaia-triage

Triage has three workstreams — GitHub issue hygiene, skill-batch intake review, and the cross-repo prioritization sweep. Run them independently or together depending on what the user asks for. All three produce documented, auditable decisions rather than silent changes.

This skill absorbed favorchurch/rock-steward's rock-triage (2026-09-01): its impact sizing, priority matrix, four-step inspection, and prioritized-matrix output landed here as Workstream 3 rather than shipping as a second, competing triage skill. There is one gaia-triage. Its priority ladder is the P0-P4 ladder /gaia-meta-audit and /gaia-meta-sweep already use — one vocabulary, not two.

Triage is not cartography. Sorting a backlog of known work is this skill; planning an effort too big for one session as a map of decision tickets is /wayfinder. Taking one triaged issue end-to-end to a PR is /gaia-issue-resolver.


Headquarters

Every issue lives on gaia-research/gaia-skill-tree, regardless of which repo the fix lands in. One tracker for the whole org.

export GAIA_HQ=gaia-research/gaia-skill-tree

Tag the target repo on the issue when the work lands elsewhere — a line at the top of the body, **Target repo:** \gaia-research/gaia-skill-heaven`, matching the /wayfinderconvention. Cross-repo references use the fullgaia-research/<repo>#<n>form; a bare#<n>` always resolves to HQ.


Classification taxonomy

Every triaged issue gets a size and a priority. Both are labels; neither is invented ad hoc (see label hygiene below).

Impact size

Blast radius, structural complexity, and data footprint — not hours.

SizeMeans
XSTrivial fix, label correction, single config value, negligible blast radius
SMinor scoped adjustment, one predicate, isolated UI touch-up
MStandard scoped task — one command, one schema field, one localized workflow
LCross-component change, non-trivial data backfill, multi-surface impact
XLArchitecture-level refactor, substantial registry debt remediation
XXLHigh blast radius — core schema, authorization, or site-wide parity
EpicUmbrella spanning multiple distinct sub-issues across domains

Priority — P0-P4

The same ladder /gaia-meta-audit and /gaia-meta-sweep use. Read those for the registry-specific instances of each rung.

PriorityMeans
P0Critical integrity violation or active breakage — unsupported top-rank claim, security/authorization exposure, secrets in a diff, the site dark, main red
P1Structural correctness — dead evidence links, Star Bar gaps, broken data contracts, lockstep drift, a prerequisite blocking milestone delivery
P2Attribution, sourcing, and feature upgrades — wrong promoted pointer, stale catalog URL, enhancement to a working surface
P3Registry hygiene and nice-to-haves — over-broad mappings, duplicate clusters, backlog enhancements, exploratory design
P4Documentation cleanup — placeholder bodies, generated-output drift, comment and copy fixes

P0 interrupts. P1 schedules. P2-P4 queue.

Label hygiene

  • Preflight. Inspect the existing labels before applying any:
    gh label list --repo "$GAIA_HQ" --limit 200
  • Zero ad-hoc labels. .github/workflows/labels-sync.yml reconciles labels from .github/labels.yml on every push to main with skip-delete: false — a label that is not in that file is deleted off live issues at the next sync. If you need a new label, add it to .github/labels.yml in a PR. Never create one with gh label create and assume it survives.
  • Idempotency. If an issue already carries an appropriate priority and size, do not relabel it. Post the status update and move on.
  • The five triage roles (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix) map to this repo's label strings in docs/agents/triage-labels.md. Extend that table rather than inventing labels.

Workstream 1: GitHub Issue Triage

The goal is a clean, signal-rich backlog — not a closed one. Closing issues prematurely hides real work; leaving stale issues open buries actionable items. For each issue, make an explicit call: close (resolved), update (needs narrowing), or keep (valid, still open).

Step 1 — Pull the open issue list

gh issue list --repo gaia-research/gaia-skill-tree --state open --limit 100

Group by theme (CLI bug, registry data, docs drift, enhancement). This shapes the decision pattern — CLI bugs and registry issues require code evidence; enhancement requests require a current-relevance check against the roadmap.

Step 2 — Audit each issue against the codebase

Before commenting or closing, verify the claim. Check the evidence paths in references/evidence-check.md for common file locations:

Issue typeWhere to look
CLI command request or bugsrc/gaia_cli/commands/
Registry data or duplicate skillsregistry/gaia.json, registry/nodes/
Documentation driftRun python scripts/build_docs.py --check
Packaging / dependencypyproject.toml, uv.lock
Test coveragetests/

Step 3 — Act via gh CLI

Post a triage comment (findings without closing — use when the issue needs narrowing or a reproduction, or when you want to flag it for a human maintainer):

gh issue comment <issue-number> --repo gaia-research/gaia-skill-tree \
  --body "Triage update: <findings and recommendation>"

Close a resolved issue (only when codebase evidence confirms it is implemented):

gh issue close <issue-number> --repo gaia-research/gaia-skill-tree \
  --reason completed \
  --comment "Closing as implemented. Evidence: <specific file + line or command output>"

Dry-run first: the scripts/triage_batch.sh script supports --apply and --close-resolved flags. Run without flags to preview all comments before posting:

bash .claude/skills/gaia-triage/scripts/triage_batch.sh
# Then, when ready:
bash .claude/skills/gaia-triage/scripts/triage_batch.sh --apply --close-resolved

Decision guide

FindingAction
Issue is implemented and tests passClose as completed with evidence pointer
Issue is valid but under-specifiedComment with narrowing questions; keep open
Issue references a stale command nameComment updating the correct current command; keep open unless fully superseded
Issue is a duplicateClose with a link to the canonical issue
Issue is an enhancement blocked on designComment with current blocker; keep open

Workstream 2: Skill-Batch Intake Review

Draft skill proposals land in registry-for-review/skill-batches/ after a contributor runs gaia push. This workstream gates them before they enter registry/nodes/.

Rejecting bad batches here is cheaper than demoting skills after promotion — every skill that enters the canonical registry acquires timeline history, evidence links, and downstream references that make later removal messy.

Step 1 — List pending batches

ls registry-for-review/skill-batches/

Each batch is a JSON file. Read its metadata to understand the contributor and scope before evaluating individual skills.

Step 2 — Evaluate each skill proposal

For each skill in the batch, work through these checks in order:

  1. Schema validity — does the node satisfy the canonical JSON schema?
    gaia dev validate --intake
  2. Nomenclature — does the skill name and description match CONTEXT.md vocabulary? Flag banned synonyms; the rarity field is deprecated and should not appear in new proposals.
  3. Evidence quality — each above-1★ claim needs graded evidence with a valid Evidence Type (arxiv|repo|github-stars) and a derived Evidence Grade; weak/ungraded-only evidence is grounds for needs-info. Ranking up gates on Trust Magnitude, not an evidence-class floor.
  4. Prerequisite existence — all prerequisites[] IDs must resolve in the current registry.
    gaia dev list --generic | grep <prerequisite-id>
  5. Duplication check — does a substantially equivalent skill already exist?
    gaia dev list --generic | grep -i "<skill-name>"

Step 3 — Label and route

Apply one of three dispositions per skill:

LabelMeaningNext action
approveSchema valid, evidence solid, no duplicatePromote via gaia dev add
needs-infoFixable gap (weak evidence, missing prereq, naming issue)Comment on the batch file with specifics; do not promote yet
rejectDuplicate, out of scope, or unfixable schema violationDocument reason; discard batch entry

For approved skills, promote via CLI (never hand-edit registry nodes directly):

gaia dev add "<Skill Name>" --type basic --description "<description>"
gaia dev evidence <skill-id> "<url>" --type repo --trust <value>

After promotion, regenerate Class S artifacts:

gaia dev docs

Workstream 3: Cross-repo triage sweep

Use this when the ask is "triage the backlog" at scale rather than "is this one issue still valid". It sizes, prioritizes, links, and assigns — and it ends in a matrix a human can act on without reopening every thread.

Four-step inspection

Run all four on every issue in scope, in order:

  1. State & relevance. Is it still live, or already resolved/superseded? Verify against the codebase, merged PRs, or a read-only probe — never against the issue's own claim. The read-only probes are the ones in /gaia-issue-resolver Phase 2 (gaia dev audit, scripts/verify_evidence.py, python scripts/build_docs.py --check). If resolved, close with the evidence.
  2. Status update & timeline. One concise technical comment: what is true now, and whether the work is starting soon, blocked on a prerequisite, or in backlog.
  3. Linkage & umbrella synthesis. Find the shared cause across issues. Where several related sub-issues have no parent, create an umbrella and label it epic, then nest the children as GitHub sub-issues (gh api repos/$GAIA_HQ/issues/<parent>/sub_issues -f sub_issue_id=<child-id> — the child's id, not its number). An umbrella that turns out to be a fog-bound effort rather than a known set of tasks is a /wayfinder map, not an epic. The test: if the children are decisions you cannot yet state precisely, stop triaging and chart a map.
  4. Assignment. Default to the original issue author unless someone is already assigned. Assign a synthesized umbrella to the owner of its constituent issues.

Fan-out

Delegate parallel reads — pulling issue payloads, checking whether a claim still holds in the tree, counting occurrences — to cheap subagents. Keep with yourself: deciding priority, deciding size, judging whether two issues share a cause, and writing the umbrella. Give each subagent the exact command and the exact thing to report back; a subagent asked to "investigate" returns prose, one asked to "run X and report the integer after Total:" returns data.

Output — the prioritized matrix

# Gaia Triage Summary — <date>

## P0 - Critical
- **#<n>** - <Title> | `<Size>` | repo: `<target repo>` | assignee: `@<who>` | <Active/Blocked/Ongoing>
  - *Umbrella*: <link>
  - *Verification*: <what was actually probed, and the result>
  - *Next action*: <the immediate step>

## P1 - Structural correctness
## P2 - Attribution & upgrades
## P3 - Hygiene & backlog
## P4 - Documentation

## Umbrellas & epics
- **Epic: <Title> (#<n>)** [assignee: `@<who>`] - sub-issues: #A, #B, #C

Refer to issues by title, not by bare number — a wall of #42, #43, #44 is illegible.


Output

At the end of a triage pass, report:

  • How many issues were reviewed, closed, and left open with comments
  • How many batch skills were evaluated, approved, flagged needs-info, and rejected
  • The prioritized matrix, if Workstream 3 ran
  • Any recurring patterns worth tracking (e.g. a common prereq that's missing from the registry) - a pattern seen a fourth time is a Class A detector in /gaia-issue-resolver, not another issue

This summary helps the next maintainer understand what happened without re-reading every issue thread.

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.