issue-queue
One repeatable, evidence-backed pass that prioritizes and resolves a bounded batch of backlog issues worst-first using specialized subagents. Inspects the queue via `fak issue-orchestrator` and `fak dispatch order`, partitions into ready-leaves, triage, and subdivide cohorts, arbitrates lane leases via `dos arbitrate`, dispatches isolated workers, independently witnesses reproduction tests, re-measures burndown with `--compare`, and commits with `(fak <leaf>)`. Use when managing the issue queue, picking the next bounded batch of issues, or advancing issue burndown.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 48
- Forks
- 16
01 前言 Front Matter
- name
- issue-queue
- metadata
- { "canonical": "../../../.claude/skills/issue-queue/SKILL.md", "generated-by": "fak project-assets sync" }
- description
- One repeatable, evidence-backed pass that prioritizes and resolves a bounded batch of backlog issues worst-first using specialized subagents. Inspects the queue via `fak issue-orchestrator` and `fak dispatch order`, partitions into ready-leaves, triage, and subdivide cohorts, arbitrates lane leases via `dos arbitrate`, dispatches isolated workers, independently witnesses reproduction tests, re-measures burndown with `--compare`, and commits with `(fak <leaf>)`. Use when managing the issue queue, picking the next bounded batch of issues, or advancing issue burndown.
- allowed-tools
- Read, Bash, Write, Edit, Grep, Glob, Task
- argument-hint
- [--lane <name>] [--top N] [--subdivide] [--triage] [--from-issues <path>] (no args = baseline + resolve top 1-3 ready issues)
- user-invocable
- true
- disable-model-invocation
- false
03 SKILL.md 正文
/issue-queue — manage, queue, and resolve backlog issues in bounded batches
What this does. Every open issue in the repository represents a pending deliverable, bug, or feature. When left unmanaged, the issue backlog rots into sprawling, un-prioritized, collision-prone work.
While
/issue-orchestratorcoordinates large-scale multi-wave campaigns across many workers,/issue-queueexecutes the atomic, bounded issue management and resolution pass: baseline and inspect the issue queue, partition issues into actionable cohorts (ready dispatchable leaves, epics needing decomposition, and scope triage), pick a bounded batch of 1–3 high-priority units, arbitrate lane leases (dos arbitrate), delegate implementation to a coordinated team of specialized subagents (researcher,worker,cross-validator,issue-auditor), independently witness the reproduction test and fix, prove burndown with--compare, and commit by explicit path.
The shape: baseline issue queue (fak issue-queue --json / fak dispatch order) → partition into ready/subdivide/triage cohorts → research & explore candidates (parallel researcher / explore subagents) → arbitrate leases (dos arbitrate) → parallel implementation wave (worker subagents via task) → adversarial verification & gap audit (cross-validator & issue-auditor subagents) → prove queue burndown (--compare) → commit cleanly by explicit path with (#N) and (fak <lane>) → release lease.
The Rule of Bounded Batches
Never attempt a repository-wide sweep in one pass. Enforce strict scoping:
- Batch Scaling (4–8 issues): Scale the batch to 4–8 issues whenever candidate issues map to pairwise tree-disjoint lanes (
dos.toml). Focus on atomic leaves with verified independent packages. - Shift-left proof by default: Every bug fix must ship with a reproduction unit test that fails before the fix and passes after. Features must ship with concrete unit/contract tests. Never accept mocks or self-report claims.
- Queue taxonomy discipline:
- Ready Leaves: Atomic S0/S1 tasks with a single witness and bounded package tree (
internal/<lane>/). - Subdivide Queue: Epics or multi-subsystem issues (>15 expected steps or touching 3+ packages) routed to decomposition before dispatch.
- Triage Queue: Issues with missing acceptance criteria, ambiguous scope, or missing likely files routed to repair before dispatch.
- Cooling / Held Queue: Issues under backoff cooldown or held by active lane leases in
.dos/lane-journal.jsonl.
- Ready Leaves: Atomic S0/S1 tasks with a single witness and bounded package tree (
- Collision safety: Pre-dispatch lane arbitration via
dos arbitrateis mandatory before touching files. - Coordinator stays clean via specialized subagents: Substantive investigation, code edits, and verification are delegated to isolated subagents via the
tasktool (Gemini 3.8 Flash highvariant: high). The coordinator verifies, witnesses, and commits. - Non-forgeable witness: Issues are closed only by git ancestry on trunk (
Fixes #Nwith(fak <lane>)), verified bydos commit-auditanddos verify.
Step 1 — Measure Baseline & Inventory Queue
Capture the open backlog baseline and inspect queue cohorts using allocated scratch storage (fak tree-doctor --scratch-dir issue-queue):
# Allocate scratch directory for queue artifacts:
fak tree-doctor --scratch-dir issue-queue
# Snapshot current issue queue state:
fak issue-queue --json > _scratch/issue-queue/baseline.json
# View top prioritized issues across lanes:
fak issue-queue --top 5
If querying live GitHub issues:
gh issue list --state open --json number,title,body,labels > _scratch/issue-queue/live-issues.json
fak issue-queue --from-issues _scratch/issue-queue/live-issues.json --json > _scratch/issue-queue/baseline.json
fak issue-queue --from-issues _scratch/issue-queue/live-issues.json --top 5
Note the headline queue metrics:
- Total Issues Evaluated: total backlog size.
- Dispatchable Ready Leaves: atomic S0/S1 issues ready for immediate dispatch.
- Subdivide Epics: oversized issues requiring decomposition.
- Triage Issues: issues requiring scope or acceptance criteria repair.
- Held Excluded: issues currently held by active leases in
.dos/lane-journal.jsonl.
Step 2 — Parallel Scoping & Pre-Dispatch Arbitration
1. Select Bounded Target Batch (1–3 Issues)
Choose 1–3 target issues based on leverage:
- Option A: High Priority / High Centrality Hotspots (
P0/P1,Corecentrality): Issues in core leaves (gateway,engine,model,compute) with high inbound impact. - Option B: Quick Leaf Wins (Highest Velocity): Self-contained bug fixes or feature additions sitting at 2–4 expected steps with bounded write surfaces.
2. Pre-Dispatch Research & Path Mapping (Parallel Subagents)
Launch parallel specialized discovery subagents in a single turn to research candidate context and verify disjoint boundaries without polluting coordinator context:
[
{
"tool": "task",
"parameters": {
"subagent_type": "researcher",
"description": "Research #1024 gateway timeout context",
"prompt": "Investigate issue #1024: Fix gateway streaming timeout.\nAnalyze relevant files under internal/gateway/, recent commits, and existing test patterns.\nReturn a compact receipt: (1) root cause hypothesis, (2) exact files to edit, (3) proposed reproduction test strategy."
}
},
{
"tool": "task",
"parameters": {
"subagent_type": "explore",
"description": "Explore model KV cache paths",
"prompt": "Inspect internal/model/ for KV cache allocation and recycling paths for issue #1035.\nVerify that its write tree is strictly confined to internal/model/ and shares no files with internal/gateway/."
}
}
]
(If an issue involves deep architectural or concurrency invariants, launch a deep-reason subagent for lock ordering and invariant analysis).
3. Verify Smallness & Contract
# Verify smallness / atomicity (single deliverable, witness == 1):
fak dispatch issue-smallness-lint --issue <number> --json
# Verify issue contract and structure:
fak-dev issue contract --from-issues _scratch/issue-queue/live-issues.json --json
4. Arbitrate Lane Leases
Verify lane lease availability before dispatch:
dos arbitrate --workspace . --lane <lane> --kind keyword --mode exclusive
(Or invoke the dos_arbitrate MCP tool).
- Outcome
acquire: Admitted. Proceed to dispatch. - Outcome
refuse: Lane is held by a peer. Pick another candidate from the queue or wait out the lease.
Step 3 — Parallel Implementation Worker Wave
Launch all selected issues' implementation workers in parallel in a single turn using multiple task tool calls with subagent_type="worker" (using Gemini 3.8 Flash high variant: high). Each worker operates under strict package fences:
[
{
"tool": "task",
"parameters": {
"subagent_type": "worker",
"description": "Implement fix for #1024",
"prompt": "You are an isolated worker resolving issue #1024: Fix gateway streaming timeout.\nLane: gateway\nBoundaries: Edit ONLY files inside internal/gateway/. NEVER touch go.mod, go.sum, dos.toml, or root files.\nDeliverable:\n 1. Write an atomic reproduction test in internal/gateway/stream_timeout_test.go demonstrating the defect.\n 2. Implement the minimal fix in internal/gateway/.\n 3. Verify package tests pass.\nVerification: Execute ONLY package-scoped tests: `go test -v ./internal/gateway` and `go vet ./internal/gateway`. NEVER run `go test ./...`.\nReturn Contract: Return a compact 3-line receipt: (1) files created/modified, (2) package test results, (3) confirmation of fix."
}
},
{
"tool": "task",
"parameters": {
"subagent_type": "worker",
"description": "Implement feature for #1035",
"prompt": "You are an isolated worker resolving issue #1035: Add model KV cache recycling.\nLane: model\nBoundaries: Edit ONLY files inside internal/model/. NEVER touch go.mod, go.sum, dos.toml, or root files.\nDeliverable:\n 1. Write an atomic reproduction test in internal/model/kv_recycle_test.go.\n 2. Implement the KV cache recycling path in internal/model/.\n 3. Verify package tests pass.\nVerification: Execute ONLY package-scoped tests: `go test -v ./internal/model` and `go vet ./internal/model`. NEVER run `go test ./...`.\nReturn Contract: Return a compact 3-line receipt: (1) files created/modified, (2) package test results, (3) confirmation of feature."
}
}
]
Each worker executes the concrete implementation:
- Reproduction Unit Test: Focused test reproducing the defect or specifying the contract.
- Minimal Package Implementation: Code changes strictly confined to
internal/<lane>/. - Package Verification: Scoped checks (
go vet ./internal/<lane>,go test -v ./internal/<lane>).
Step 4 — Parallel Adversarial Cross-Validation & Gap Audit
The coordinator does NOT trust worker narration (dos-witness-claim). Instead, launch parallel verification subagents to independently audit the landed work before commit:
[
{
"tool": "task",
"parameters": {
"subagent_type": "cross-validator",
"description": "Cross-validate #1024 and #1035",
"prompt": "You are an adversarial cross-validator.\nTasks to verify: #1024 (internal/gateway) and #1035 (internal/model).\nResponsibilities:\n 1. Inspect `git diff internal/gateway` and `git diff internal/model` to verify that edits did not leak outside declared package boundaries.\n 2. Execute on-device tests: `go test -v ./internal/gateway` and `go test -v ./internal/model`.\n 3. Verify that reproduction tests genuinely assert the expected behavior and do not test trivial mocks.\nReturn a structured DOS-style proof verdict: VERIFIED or REJECTED with concrete command witnesses."
}
},
{
"tool": "task",
"parameters": {
"subagent_type": "issue-auditor",
"description": "Audit QA gaps and follow-ons",
"prompt": "You are an issue auditor inspecting the changes in internal/gateway and internal/model.\nUncover unhandled edge cases, boundary conditions, or failure modes in the newly added code.\nIf real follow-ons or gaps exist, draft structured GitHub issue tickets with clear reproduction steps and acceptance criteria."
}
}
]
Coordinator independently verifies:
- Toolchain check:
go vet ./internal/<lane>andgo test -v ./internal/<lane>. - Diff boundary check:
git diff --stat internal/<lane>. - Audit review: Incorporate cross-validator proof verdicts and any auditor follow-on tickets.
Step 5 — Re-Measure and Prove Queue Burndown
Re-evaluate the issue queue against the saved baseline to prove burndown:
# Re-snapshot issue state:
gh issue list --state open --json number,title,body,labels > _scratch/issue-queue/updated-issues.json
fak issue-queue --from-issues _scratch/issue-queue/updated-issues.json --compare _scratch/issue-queue/baseline.json
Confirm:
- Target issues are resolved and retired from the dispatchable count.
- Closed count delta reflects the completed batch.
- No new unclassified drift was introduced.
Step 6 — Commit Cleanly by Explicit Path
Commit each finished leaf independently on the trunk. Include a Conventional-Commits subject, signed-off DCO (-s), issue citation (#N), and required (fak <leaf>) trailer:
fak sync reconcile --apply
fak commit --path internal/<laneA> -m "fix(<laneA>): resolve <summary> (#1024) (fak <laneA>)"
fak commit --path internal/<laneB> -m "feat(<laneB>): add <summary> (#1035) (fak <laneB>)"
fak sync push
(Fallback: git commit -s -m "..." -- internal/<lane> without git add -A).
Verify git status shows your lanes are committed cleanly and no peer WIP was staged.
Step 7 — Release Lane Leases & Clean Scratch
Release all acquired lane leases:
dos lease-lane release --lane <laneA>
dos lease-lane release --lane <laneB>
Reap the campaign scratch directory:
fak tree-doctor --reap-scratch issue-queue --json
Report the one-line completion receipt to the operator with the checkable commit SHAs, issue numbers, and test witnesses.
04 同仓库更多 Skills
serve-receipt
On-demand research protocol + deterministic receipt for serving a Hugging Face model on a concrete GPU target — fan out research lanes (model facts/files, engine support matrix, serving recipes, KV/state memory math), compute the tiered feasibility verdict with `fak serve-receipt` (never narrated math), and emit a witnessed launch receipt. Use when asked for an "initial config", "serving receipt", or "how do I serve <model> on <GPUs>".
caveman
Ultra-compressed communication mode. Cuts output tokens 65% (measured) by speaking like caveman while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
quality-report
Score the repo quality and emit a report card.
ctx-overlay
Compact the context window and prune the memory store when a session grows too long.
quality-report
Score the repo quality and emit a report card.
ctx-overlay
Compact the context window and prune the memory store when a session grows too long.