harshanandakharshanandak/forge-legacy/skills/triage-ready/SKILL.md

triage-ready

Skill4 starsChanged 48 days agoMITView on GitHub

Surfaces, ranks, and EXPLAINS the single best next issue in a Forge project — strictly read-only. Recomputes the live ready queue and explains what is blocked via `forge issue ready`/`blocked`/`stats`/`show`, always against the live kernel, never `forge board`. Recommends ONE issue with a one-line reason, then hands off; never claims, comments, closes, or mutates. Use when the user asks "what should I work on", "what's next", "what's ready", "pick/triage my next task", "top of the ready queue", "which issue should I start", "why is this issue blocked", or "what's blocking the most work". NOT for claiming or taking ownership of the pick (use claim-safety), not for everyday issue create/update/list/search/close/comment/dep CRUD (use issue-basics), not for reporting the current workflow stage or "where am I / what's in flight" (use status), not for orienting a whole session or routing to stage skills (use kernel), not for driving an issue to a merged PR (use smith).

In this repository51 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/permissions-guidance.mdcCursor rule
- claim-safetySkill
- devSkill
- gatesSkill
- hermes-forgeSkill
- issue-basicsSkill
- kernelSkill
- memorySkill
- parallel-deep-researchSkill
- planSkill
- portabilitySkill
- researchSkill
- reviewSkill
- rollbackSkill
- setupSkill
- shepherdSkill
- shipSkill
- smithSkill
- sonarcloud-analysisSkill
- sonarcloudSkill
- statusSkill
- triage-readySkill
- using-forgeSkill
- validateSkill
- verifySkill
- worktreeSkill
- claim-safetySkill
- devSkill
- gatesSkill
- hermes-forgeSkill
- issue-basicsSkill
- kernelSkill
- memorySkill
- parallel-deep-researchSkill
- planSkill
- portabilitySkill
- researchSkill
- reviewSkill
- rollbackSkill
- setupSkill
- shepherdSkill
- shipSkill
- smithSkill
- sonarcloud-analysisSkill
- sonarcloudSkill
- statusSkill
- using-forgeSkill
- validateSkill
- verifySkill
- worktreeSkill

The file

We split this skill into the rules it gives an agent

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

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
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

Distinctive:
Do not just name it — justify it.
line 68
Very specific:
Check the envelope: Every --json reply carries ok.
line 107

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

Triage: what should I work on next

A read-only orientation skill. It answers "what is the single best thing to work on right now, and why?" and hands the pick off to claim-safety / dev — it never mutates the store itself.

Readiness in the Forge kernel is a derived read model: an issue is ready only when every dependency is satisfied, it is unclaimed (no live lease), it is a claimable type (epics and decisions never enter the queue), and no defer window holds it back. Because it is derived, always recompute it — never trust a cached "status == ready". Recompute means: run the query fresh each time.

Do NOT use `board`

forge board reads a legacy snapshot store, not the live kernel, so its readiness can be stale or wrong. This skill uses forge issue ready, forge issue blocked, and forge issue stats exclusively.

Procedure

1. Take the pulse

forge issue stats --json

Returns data.counts (open/done/cancelled — keys are present only when non-zero, and there is no in_progress bucket: claimed work stays in status open and is surfaced via active_claims), ready_count, blocked_count, and active_claims. A high blocked_count relative to ready_count is your signal that dependency repair (not new work) is the real bottleneck — hand off to dependency-planning / backlog-hygiene.

2. Rank the ready queue

forge issue ready --json

data.issues[] comes back ordered by rank (priority ascending, then id), each carrying id, title, type, priority (P0..P4), rank, blocked, claimed_by, parent_id, labels[], and dependencies[]. The top item is your default pick. Surface the top few (see Fork points for how many), not the whole list.

3. Explain WHY the top item is ready

Do not just name it — justify it. Pull its full record:

forge issue show <id> --json

State the reason in one sentence, drawn from the record:

Priority / rank — P0 at rank 0 outranks everything below it.
Dependencies satisfied — every id in dependencies[] is closed/done, so nothing gates it (blocked: false).
Unclaimed — claimed_by is null, so no other agent holds the lease.
Claimable type — it is a task/feature/bug, not an epic/decision.

4. Explain why the runners-up are NOT ready

forge issue blocked --json

For a blocked item, name the specific unmet dependency (from its dependencies[] cross-referenced against forge issue show) — e.g. "blocked by forge-x which is still open". This turns triage into an actionable map: the fastest way to unlock the most work is usually to finish the shared blocker.

5. Hand off

Recommend ONE issue with its one-line justification, then stop. The caller claims it (via claim-safety) and executes (via dev). Triage does not claim, comment, or close — it is strictly read-only.

Reliability

Recompute, never cache. Readiness is derived; re-run forge issue ready every session rather than remembering a prior "ready" verdict.
Respect non-claimable types. Epics and decisions never appear in ready (the queue surfaces only claimable types — task/bug), so do not hand them off as work. There is no claimable field in the CLI JSON; this is behavioral, not a flag you can read.
Check the envelope. Every --json reply carries ok; on ok:false read error.message and retry the query rather than guessing at state.
Read-only. This skill runs only stats/ready/blocked/show. If a fix is needed, hand off — never mutate here.

Fork points

Editable knobs — change these to carve your own triage policy. This skill is a canonical source you fork, not a fixed ladder.

Knob	Default	How to change
Readiness query / filters	`forge issue ready` (whole queue)	Narrow to a slice, e.g. `forge issue list --status open --priority P0 --json` or post-filter `ready` output by `labels[]`/`type` to focus one workstream.
How many items to surface	Top 3 by `rank`	Raise for a broad standup view, lower to 1 for a strict "next task only" hand-off.
Stale threshold	`forge issue stale --days 14`	Change `--days` to flag idle in-progress work sooner/later; surface stale claims as a caveat before recommending fresh work.
Priority ordering	Kernel `rank` (priority, then id)	Re-rank the `ready` list by your own weights — epic proximity (`parent_id`), label, or age — before picking.
Blocked-explain depth	One hop (direct unmet deps)	Trace transitively via repeated `forge issue show` when you need the full blocking chain; hand to `graph-forensics` for deep `explain`.

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.

Check your setup, free