what-next
Report what to work on next in this repository — an active handoff waiting to be resumed, work already in flight, ready issues ranked the way the board ranks them, what needs the user, what needs shaping first, and blocks that have quietly cleared — and recommend the one command to run. Read-only. Use when the user asks what to work on next, what is ready or what to pick up, or when a phase ends with no next piece of work chosen.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- what-next
- metadata
- { "settings": "issue-tracker triage-labels handoffs dev-flow" }
- description
- Report what to work on next in this repository — an active handoff waiting to be resumed, work already in flight, ready issues ranked the way the board ranks them, what needs the user, what needs shaping first, and blocks that have quietly cleared — and recommend the one command to run. Read-only. Use when the user asks what to work on next, what is ready or what to pick up, or when a phase ends with no next piece of work chosen.
- argument-hint
- A focus: agent, human, bugs, or a label, area or field value (optional)
02 资源文件 5
- 参考文档settings/dev-flow.md5.3 KB
- 参考文档settings/handoffs.md1.5 KB
- 参考文档settings/issue-tracker.md3.9 KB
- 参考文档settings/README.md3.2 KB
- 参考文档settings/triage-labels.md1.2 KB
03 SKILL.md 正文
What next
Scan this repository's trackers and board, rank the open work, and say what to pick up next. The development flow's routing table says which command takes each kind of work; this skill finds the work, ranks it, and names the command. It recommends and stops: the human starts every phase.
Read-only. Never change a label, field, assignee, issue or PR, and never claim an issue or a
handoff: /implement, /lets-go and the other phase commands do that when the work begins.
Tracker problems the scan finds are reported, for the user or end-session to fix. The settings
files step 0 may write are the only files this skill ever changes; reading the handoff map may also
fetch a copy of the map and its document into the local Handoffs folder.
Run shell snippets in bash (Git Bash on Windows).
0. Settings
This skill reads docs/agents/issue-tracker.md, docs/agents/triage-labels.md and
docs/agents/handoffs.md. Follow .agents/skills/what-next/settings/README.md to read them and
complete any that are missing; the definitions sit beside it. It never sets up the handoffs machine
config (.agents/skills/handoff/machine-config.md): that writes a file, so a machine without one
skips the handoff check (step 1). Then read:
.agents/skills/what-next/settings/dev-flow.md## Procedure: The gate (what makes an issue ready), Routing (which command takes which work, and what "nobody has started" means) and Private work. Readdocs/agents/dev-flow.mdtoo, for what this repository adds to the flow.- The other sections of
docs/agents/issue-tracker.md(such as Blocking or Wayfinding operations): they say how this repository records blockers and maps.
From the settings, work out before collecting:
- Trackers: the
Public repository, and thePrivate issue repositoryunlessnone. Adiscover:value is followed now; the private tracker's name stays out of anything public. - Board meanings: from
Board fieldsandExtra labels, which values mean in progress, which mean parked or deferred, which mean waiting on something outside the code, which mean waiting on the owner, and which mean a spec or research must come first. A repository's own word for a state counts (Deferred,Deferred trigger,P3 - parked,deferred,blocked-by-human).
1. Collect
me="$(gh api user --jq .login)"
repository="<Public repository>" # owner/name
board_owner and board_number below are the two words of the Board setting.
The active handoff, through the script the handoff skill installs, as lets-go reads it:
node .agents/skills/handoff/handoff-map.mjs get --key <Map key>
fileis null (orinMapis false): no handoff waits for this repository.fileis set andexistsis true: a handoff waits to be resumed. Read the document's Where you are and first Next step for the report; do not act on them.fileis set andexistsis false: the document has not reached this machine yet (thenotesays why). Report it as pending.conflictsnot empty: report that the map has conflicting copies, whichlets-goresolves with the user.- An error, a missing script, or no machine config (the error names
config): the handoff check was not read. Never runconfig --writefrom here.
Open issues, once per tracker, with owner and name split from its owner/name:
gh api graphql --paginate -f owner="$owner" -f name="$name" -f query='
query($owner: String!, $name: String!, $endCursor: String) {
repository(owner: $owner, name: $name) {
issues(states: OPEN, first: 100, after: $endCursor) {
pageInfo { hasNextPage endCursor }
nodes {
number title createdAt updatedAt url
labels(first: 20) { nodes { name } }
assignees(first: 5) { nodes { login } }
issueDependenciesSummary { blockedBy totalBlockedBy blocking }
closedByPullRequestsReferences(first: 5, includeClosedPrs: false) { nodes { number isDraft } }
parent { number title }
}
}
}
}' --jq '.data.repository.issues.nodes[]'
issueDependenciesSummary.blockedBy counts open blockers only (0 means no native blocker holds it),
totalBlockedBy counts closed ones too, and blocking counts the open issues waiting on this one.
Open PRs on the Public repository:
gh pr list -R "$repository" --state open --limit 200 \
--json number,title,author,isDraft,reviewDecision,closingIssuesReferences,statusCheckRollup,headRefName,createdAt
The board, unless Board is none:
gh project item-list "$board_number" --owner "$board_owner" --format json --limit 1000
Items come back in the board's manual order, top first, which is what board order in
Priority order reads. Each item's field values are keys named by the field in lower case
(priority, blocked by); content.number and content.repository join it to an issue, and an
item whose content.type is DraftIssue is a board draft. Reading a board needs the token's
read:project scope (gh auth status). Without it, or on any other failure, rank without the
board and say so in the report; never stop over it.
Security findings, when the Security findings setting is the default (draft advisories):
gh api "repos/$repository/security-advisories?state=draft" --jq length
A count only, never a title or summary. An error prints not readable, never 0.
2. Classify
Put each open issue in exactly one bucket, taking the first that fits:
- Someone else's — assigned only to people other than
me. Count it; do not list it. - Finish first — named by an open PR (the issue's
closedByPullRequestsReferences, or a PR'sclosingIssuesReferences); or assigned tome, or in an in-progress board state, and not waiting (4). Assigned work that is waiting goes to Waiting, and the report's hygiene line names it. - Parked —
wontfix, or a label or board value that means parked or deferred. Count only. - Waiting — an open native blocker (
blockedByabove 0); theblockedlabel or an extra label meaning the same; a board field naming a blocker outside the project (a cleared value such asNothing,NoneorReady — …names none); a gate value that means waiting on something outside the code; orneeds-info. Count by reason; do not list. A stale block (below) is not waiting. - Needs you —
ready-for-human,blocked-by-humanor a like extra label, or a gate value that waits on the owner's decision or action. - Ready for an agent — ready by The gate: route a
bugto/diagnosing-bugs, and aready-for-agentissue to/implement. - Needs shaping — everything else, with its route from Routing: no triage label or
needs-triage→/triage; a gate value calling for a spec or research →/grill-with-docs, then/to-spec; awayfinder:map→/wayfinder(group its child tickets, found byparent, under it rather than listing them). WithNew work: draft item, count the board's drafts here too.
Stale blocks. An issue carrying a blocked label or gate value, with no open native blocker
(blockedBy 0, totalBlockedBy above 0) and no outside blocker in a board field, was blocked only
by issues that have since closed. Classify it as though unblocked, mark it stale block, and list
it in the report's hygiene line. It is often the best pick, and only a tracker edit stands between
it and the queue.
The gate needs the body. Labels alone cannot show it: a ready-for-agent label on a free-form
body is a raw issue, and /triage posts its brief as a comment. Check only the items the report
will list, as ranking reaches them: gh issue view <n> -R <tracker> --json body,comments. One that
fails moves to Needs shaping, routed to /triage.
PRs. Each of me's open PRs goes in Finish first, with its state: checks failing, changes
requested, approved and waiting for a merge, a draft, or waiting for review. Another author's
non-draft PR, a dependency bot's included, goes there too, as a review or merge to make, with its
checks' state.
Private work is classified and routed like the rest, and marked [private] in the report.
An active handoff heads Finish first, routed to /lets-go: another session parked its work
for this one to resume, and its document names the next step. A pending one (its document not here
yet) is listed there too, with no route. The map does not record which machine wrote a handoff, so
the report names the document and its date: a handoff this machine wrote is waiting for the other
one, and is left alone.
3. Rank
Within each bucket, order by:
Priority order, key by key. An item missing a key's value sorts after every item that has one.- The open issues it unblocks (
blocking), most first. - Age (
createdAt), oldest first.
With Priority order: none, or the board unreadable, rank by 2 and 3 alone and say so.
Finish first goes: the active handoff, then PRs with failing checks or changes requested, then
approved PRs, then PRs waiting for review, then assigned issues with no PR, then drafts.
The recommendation is, in order:
- The top of Finish first, unless it holds only drafts or a pending handoff. An active handoff
whose document is here is resumed with
/lets-go, which brings the checkout to its state before anything else starts. A green PR with nothing requested is finished by the user's review and merge, which the recommendation names; it never merges. - Otherwise the higher-ranked of the tops of Ready for an agent and Needs you, comparing by the same keys. On a tie, the Needs you item: no agent can take it, and it may unblock others.
- Otherwise the top of Needs shaping.
- Otherwise nothing: say the queue is empty, with the Waiting counts.
4. Report
An argument narrows the report: agent keeps Finish first and Ready for an agent, human
keeps Finish first and Needs you, bugs keeps bug issues, and anything else keeps the
items whose labels, board values or titles match it. The recommendation comes from what is kept.
Refer to each item by its title with its number (Add the lap filter (#212)), never by number
alone. List at most ten items per bucket and count the rest. Leave out an empty bucket.
## What next: <repository>
**Next:** <title> (#<n>) <[private]> — run `<command> <n>`. <One line: why this, above the rest.>
### Finish first
- Active handoff `<file>` (<date>) — <its first next step> — `/lets-go`, unless this machine wrote
it <or: pending, not on this machine yet>
- <title> (#<n>) — <PR state, or "assigned, no PR"> — <what finishing takes>
### Ready for an agent (<count>)
1. <title> (#<n>) — <rank values>; unblocks <k> — `/implement` or `/diagnosing-bugs`
### Needs you (<count>)
1. <title> (#<n>) — <the decision or action owed>
### Needs shaping (<count>)
1. <title> (#<n>) — <why it is not ready> — `<route>`
### Waiting
<n> blocked by open issues, <n> on outside parties, <n> needing info, <n> parked, <n> others'
work.<, <n> draft security advisories open.>
**Tracker hygiene:** <stale blocks, assigned work that is waiting, ready-for-agent labels on raw
issues, open items with no `Priority order` value, conflicting state labels — or "none found">.
**Not read:** <the handoff map, the board, the private tracker or advisories, with why — or leave
the line out>.
Then stop. Say which command the recommendation runs, and wait: the user starts the next phase. Running in a subagent or a non-interactive run, return the report to the caller instead.
04 同仓库更多 Skills
what-next
Report what to work on next in this repository — an active handoff waiting to be resumed, work already in flight, ready issues ranked the way the board ranks them, what needs the user, what needs shaping first, and blocks that have quietly cleared — and recommend the one command to run. Read-only. Use when the user asks what to work on next, what is ready or what to pick up, or when a phase ends with no next piece of work chosen.
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
wait-what
Stop. That last message did not land: re-pitch it.
triage
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.