agentleFS
anthony-chaudharyanthony-chaudhary/fak/.agents/skills/issue-triage/SKILL.md

issue-triage

Skill49 starsChanged 13 days agoApache-2.0View on GitHub

One repeatable pass over the open GitHub issue backlog — classify every open issue (needs-priority / needs-kind / needs-area, orphaned P0-P1, stale, dormant question), rank them into a deterministic "do next" order, propose the mechanical gardening moves (mark stale, close dormant questions), and apply them only on operator approval. The helper is read-only; writing labels, comments, or closes is gated. Use when the operator says "triage the issues", "what should I work on next", "garden the backlog", "the issue labels.

63 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use meeting-notes-and-actions, pr-review-ci-fix and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ComposioHQSkill

    meeting-notes-and-actions

    Turn meeting transcripts or rough notes into crisp summaries with decisions, risks, and owner-tagged action items; use for Zoom/Meet/Teams transcripts, call notes, or long meeting chats to generate share-ready outputs.

    Also in 4 projects that use this

  • ComposioHQSkill

    pr-review-ci-fix

    Automated PR review and CI auto-fix for GitHub and GitLab using the Composio CLI. Pulls diffs, fetches failing job logs, posts review comments, and loops fix commits until checks go green.

    Also in 4 projects that use this

  • FlorianBruniauxSkill

    tdd-rust

    Also in 3 projects that use this

  • GitHubSkill

    phoenix-cli

    Debug LLM applications using the Phoenix CLI. Fetch traces, analyze errors, structure trace review with open coding and axial coding, inspect datasets, review experiments, query annotation configs, and use the GraphQL API. Use whenever the user is analyzing traces or spans, investigating LLM/agent failures, deciding what to do after instrumenting an app, building failure taxonomies, choosing what evals to write, or asking "what's going wrong", "what kinds of mistakes", or "where do I focus" — even without naming a technique.

    Also in 3 projects that use this

  • petestewartSkill

    datadog-logs

    Query Datadog logs via the Logs Search API v2. Use when the user asks to "check the logs", "search logs", "find errors in Datadog", "look up logs for", "show me production logs", "check for errors", "search Datadog", or any request involving log search, error investigation, or production debugging that requires Datadog log data.

    Also in 3 projects that use this

  • +7 more from ComposioHQ

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 5 are distinctive, and 9 are very specific to this project.

  • 0

    Common

    Most of the 51 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 9

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If helpers.issue_triage is absent, print one line pointing at the missing helper and stop.

    line 41
  2. Very specific:

    Use today's date in UTC. Use --out (not a shell > redirect) — PowerShell redirects re-encode to UTF-16 and mangle the · / — glyphs in the …

    line 58
  3. Very specific:

    Read the markdown report back (the helper prints wrote <path>, not the body).

    line 70
  4. Very specific:

    Do not page through gh issue list by hand — the helper already folded the whole open backlog into the ranked model.

    line 71
  5. Very specific:

    Run the scout with OpenCode's permission-constrained plan agent.

    line 83
  6. Distinctive:

    Treat model prose as an allegation until an independent pass reruns every witness.

    line 92
  7. Distinctive:

    Before proposing dispatch for a selected issue, validate and price it through the first-class Go surfaces:

    line 116
  8. Very specific:

    Use tools/issue_contract.py or tools/issue_lane_router.py only to debug a discrepancy with those commands.

    line 125
  9. Very specific:

    Check that the measurement actually supports the claim's scope and causal language (for example, filesystem residue outside go list ./...

    line 131
  10. Distinctive:

    Read back every named parent/duplicate issue's current state.

    line 134
  11. Distinctive:

    Create only passing candidates, with priority, generation, class, and milestone set at creation.

    line 148
  12. Distinctive:

    Do not paste the whole report into chat — link the file.

    line 153
  13. Very specific:

    Never fabricate a cmd for a review-only action.

    line 168
  14. Very specific:

    Before running anything, print the exact commands you will run, grouped by kind.

    line 174

“Common” is measured: kept by at least 6 in 10 of the 51 edited versions of this file we could read. “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

/issue-triage — classify, rank, and garden the open issue backlog

Lead with current first-class fak console issues, fak-dev issue, and fak dispatch surfaces. The Python triage helper remains a read-only legacy/debug fallback for report fields not yet exposed by those commands. Mutations stay a separate, operator-approved step.

A backlog rots the same way an index drifts: labels go missing, priorities never get set, questions hang open forever, duplicates accrete. This skill is the gardening pass for GitHub issues — the issue analogue of curate-cluster. One pass: gather → rank → propose → (approve) → apply → verify.

The triage ranking is a transparent integer score, not a model judgment (see the helper's module docstring for the exact formula). The score is surfaced in the report so the ordering is auditable.

Project contract

Reads .claude/project.yaml. Required keys:

  • python — interpreter path (default: python).
  • helpers.issue_triage — the read-only fetch/classify/rank/actions script.
  • audits_dir — where reports + the actions manifest are written (default: docs/_audits/, shared with plan-audit — these are process residue, kept out of the root index scan).

If helpers.issue_triage is absent, print one line pointing at the missing helper and stop. Do not improvise a substitute.

The label taxonomy is the project's, baked into the helper (priority/P0|P1|P2, kind, area, workflow). Override thresholds or label sets via the helper's --config <json> if the taxonomy changes; the skill itself is taxonomy-agnostic.

Step 1 — Gather and rank (read-only)

fak console issues --state open --json > issues-ranked.json

# Legacy/debug comparison for extra historical report fields:
<p> <h.issue_triage> --markdown --out <audits_dir>/issue-triage-<YYYY-MM-DD>.md
<p> <h.issue_triage> --actions  --out <audits_dir>/issue-actions-<YYYY-MM-DD>.json

Use today's date in UTC. Use --out (not a shell > redirect) — PowerShell redirects re-encode to UTF-16 and mangle the · / — glyphs in the report. One report per day; overwrite if it exists.

Optional scoping:

  • --since-days N — only issues touched in the last N days (use after a burst of filing, to triage just the new wave).
  • --scope <tag> — filter the rows to one bucket: priority | kind | area | orphans | stale | dup | question. Drops the other sections so the report is focused.

Read the markdown report back (the helper prints wrote <path>, not the body). Do not page through gh issue list by hand — the helper already folded the whole open backlog into the ranked model.

Default medium-scale scout: OpenCode Go Ox Alpha

For a broad repository review or a medium-scale gardening batch (25 or more issues/candidates), use opencode-go/ox-alpha-free as a read-only proposal stage when that route is available. This is the default model-assisted path, not authority to mutate GitHub or the tree. If the route is unavailable, keep the deterministic report and continue without a model; do not silently substitute a paid model.

Run the scout with OpenCode's permission-constrained plan agent. Never pass --auto, and tell the model that shell commands are read-only too:

opencode run --agent plan --model opencode-go/ox-alpha-free --format json \
  "Read-only review. Inspect the ranked issue report and repository evidence. Do not edit files, create/comment/close issues, or run any mutating command. Return candidate findings only, each with: claim; exact witness command; observed output/count; affected paths or issue numbers; dedupe query and results; current parent issue state; proposed labels/milestone; confidence; and disconfirming evidence."

Save the session ID and the candidate packet beside the dated audit report. Treat model prose as an allegation until an independent pass reruns every witness. The measured rationale and failure examples are indexed in docs/notes/OX-ALPHA-DOGFOOD-2026-08-22.md.

Ox Alpha's audited failure mode is confident conflation: one true global smell can be combined with stale parent state, non-versioned residue, incomplete inventories, or incorrect attribution. Therefore the scout and gardener must not be the same self-certifying pass.

Step 2 — Read the report, lead with the load-bearing finding

The report's counts line is the headline. Lead the operator summary with the single largest gap, in this priority order:

  1. Orphan P0/P1 (orphan count) — high-priority work with no claimant. This is the most expensive backlog rot. Name the top 3 by score.
  2. needs-priority — the canonical "labels were never set" gap. A pass that cuts that number is a real win; quote the project's own current baseline from the report rather than a fixed number.
  3. stale / dormant-question — these carry mechanical proposed actions (mark stale, close). They are the gardening moves the operator can approve in one batch.
  4. duplicate clusters — run fak-dev issue dedup (the body-aware census; the triage helper no longer detects dups). Confirm-and-close candidates.

Before proposing dispatch for a selected issue, validate and price it through the first-class Go surfaces:

gh issue view N --repo owner/name --json number,title,body,labels > issue.json
fak-dev issue contract --from-issues issue.json --json
fak issue-queue --from-issues issue.json --json

Use tools/issue_contract.py or tools/issue_lane_router.py only to debug a discrepancy with those commands; do not teach them as the default operator path.

For every model-proposed candidate, the independent reconciliation pass must:

  1. Rerun the exact witness command and preserve its output.
  2. Check that the measurement actually supports the claim's scope and causal language (for example, filesystem residue outside go list ./... cannot explain a Go package build failure).
  3. Read back every named parent/duplicate issue's current state.
  4. Preserve the complete inventory behind any count; samples cannot support a “full list” acceptance condition.
  5. Reject candidates that combine different leaves, non-versioned cleanup, or comment bookkeeping into one issue.
  6. Materialize each survivor as a candidate JSON packet, then run:
fak-dev issue contract --file candidate.json --dedupe-checked \
  --strict-witness --strict-scale --strict-project-work \
  --strict-born-routed --strict-model-tier --json

A held verdict stays needs-triage / triage-only; it is not worker-ready. Create only passing candidates, with priority, generation, class, and milestone set at creation. After creation, read the issue back from GitHub and compare its title, body, labels, milestone, and parent against the accepted packet. A separate reconciliation pass may retain, rewrite, or close model-filed candidates; never use the filing trajectory's own summary as proof. Do not paste the whole report into chat — link the file. Surface only the 0–3 findings that matter and the one batch the operator can act on now.

Step 3 — Distinguish mechanical from judgment-call actions

The --actions JSON carries two kinds of entries:

  • mechanical (cmd is set) — close-dormant-question and mark-stale. These are defensible from the issue's own signals (a question idle ≥ 30 d, or any non-P0/P1 idle ≥ 60 d). The operator can approve these as a batch.
  • review-only (cmd: null, kind: "review") — needs-priority, needs-kind, needs-area, orphan. The helper cannot decide these algorithmically (what priority is the work?). They are surfaced for the operator to decide per-issue.

Never fabricate a cmd for a review-only action. If the operator sets a priority by hand, you build that single gh issue edit <n> --add-label priority/Px command on the spot — you do not promote the row to "mechanical".

Step 4 — Apply mechanical actions only on approval (dry-run first)

Before running anything, print the exact commands you will run, grouped by kind. The manifest's cmd strings are PowerShell-shell-ready (single-quoted --comment, double-quoted --reason); run them verbatim.

# Dry-run review — show, don't run. Confirm the counts match the manifest.
# Then, per batch, on explicit operator "yes":
gh issue close <n> --reason "not planned" --comment "..."   # dormant-question
gh issue edit <n> --add-label "stale" --add-comment '...'   # mark-stale

Rules:

  • Batch by kind, and confirm each batch separately ("3 dormant-question closes — ok?"). Do not run a single blanket "apply everything".
  • One issue at a time for any review-only action the operator resolves live. If they say "#98 is P0, already claimed" → gh issue edit 98 --add-label in-progress, nothing else.
  • Re-fetch after applying — re-run Step 1's --actions and confirm the applied rows dropped out (their tags changed). The pass is done when the mechanical-action count is zero AND the operator has either resolved or explicitly deferred each review-only row.

Step 5 — Verify (witness, don't assume)

fak console issues --state open --json > issues-ranked-after.json
gh issue view <n> --json labels,state,comments   # spot-check 2–3 applied rows
<p> <h.issue_triage> --actions --out <audits_dir>/verify-actions.json

The first-class before/after issue models are the truth source; the fallback action manifest is an additional mutation witness when that helper was used.

The second run is the witness: the applied issues should no longer carry the tag the action addressed (a closed dormant-question is no longer open; a marked-stale issue now has the stale label). If a row's tag survived, the gh write failed silently — re-check and re-run that one.

The pass is done when: the report's mechanical-action count is zero, the operator has resolved or deferred every review-only row they chose to handle this pass, and the spot-checks confirm the GitHub state matches the manifest.

Running it on a cadence

This is a single pass. The backlog re-rots, so drive it with /loop (e.g. /loop issue-triage --since-days 30, weekly) — each pass only touches issues that aged into a bucket since the last one. The helper is idempotent: an issue already correctly labeled and claimed contributes nothing to the action manifest, and a pass with nothing to propose commits nothing and exits.

Where this misleads / honest limits

  • The score is a heuristic, not a priority oracle. A P2 bug can matter more than a P1 enhancement; the formula can't see that. Treat the ranking as "where to look first", not "what to build first".
  • Stale/dormant thresholds are calendar-based, not signal-based. A quiet issue that is actively blocked (waiting on a dependency) is not stale — the operator must read the close candidates before approving. The manifest's comment text says "reply to keep open" for exactly this reason.
  • Duplicate detection lives in fak issue dedup, not this helper. The body-aware census (title + title+body simhash) catches semantic dups the old title-token Jaccard pass missed. It is advisory: it ranks merge proposals with per-pair evidence and suppresses oversized shared-template families (epic siblings are not duplicates of each other). Always confirm before closing as dup; it never writes to GitHub.
  • It only sees labels + timestamps. It cannot read the issue body for severity, dependencies, or whether the reporter still cares. The operator's judgment is the last rung; this skill gets the queue into shape so that judgment is spent on the right rows.
  • Closed issues are out of scope. This triages the open backlog. Auditing closed-issue quality (wrong reason codes, premature closes) is a different skill.

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.