Skip to content
Skills Library
Programming · Automation

issue-queue

/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.

Repository
fak ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

98/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene13 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

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.

Arguments

/issue-queue [--lane <name>] [--top N] [--subdivide] [--triage] [--from-issues <path>]  (no args = baseline + resolve top 1-3 ready i
Original author 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.

How it works

  1. The Rule of Bounded Batches
  2. Step 1 — Measure Baseline & Inventory Queue
  3. Step 2 — Parallel Scoping & Pre-Dispatch Arbitration
  4. Step 3 — Parallel Implementation Worker Wave
  5. Step 4 — Parallel Adversarial Cross-Validation & Gap Audit
  6. Step 5 — Re-Measure and Prove Queue Burndown
  7. Step 6 — Commit Cleanly by Explicit Path
  8. Step 7 — Release Lane Leases & Clean Scratch
Original SKILL.md headings · 236 lines, 1,598 words
SKILL.md preview
---
name: issue-queue
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.
disable-model-invocation: false
user-invocable: true
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)"
---

# /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-orchestrator` coordinates large-scale multi-wave campaigns across many workers,
> `/issue-queue` executes 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:

1. **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.
2. **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.
3. **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`.
4. **Collision safety**: Pre-dispatch lane arbitration via `dos arbitrate` is mandatory before touching files.
5. **Coordinator stays clean via specialized subagents**: Substantive investigation, code edits, and verification are delegated to isolated subagents via the `task` tool (Gemini 3.8 Flash high `variant: high`). The coordinator verifies, witnesses, and commits.
6. **Non-forgeable witness**: Issues are closed only by git ancestry on trunk (`Fixes #N` with `(fak <lane>)`), verified by `dos commit-audit` and `dos 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`):

```bash
# 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:
```bash
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`, `Core` centrality)**:
  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:

```json
[
  {
    "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
```bash
# 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:
```bash
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:

```json
[
  {
    "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:
1. **Reproduction Unit Test**: Focused test reproducing the defect or specifying the contract.
2. **Minimal Package Implementation**: Code changes strictly confined to `internal/<lane>/`.
3. **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:

```json
[
  {
    "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:
1. **Toolchain check**: `go vet ./internal/<lane>` and `go test -v ./internal/<lane>`.
2. **Diff boundary check**: `git diff --stat internal/<lane>`.
3. **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:

```bash
# 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:

```bash
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:

```bash
dos lease-lane release --lane <laneA>
dos lease-lane release --lane <laneB>
```

Reap the campaign scratch directory:
```bash
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.

Versions

The database has no other skills named issue-queue.

Database snapshot: 13.11.2026 · package version 233c815227a6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100issue-orchestrator
    Plan, partition, and coordinate multi-wave parallel subagent campaigns to resolve and close GitHub issues. Uses `fak issue-orchestrator --plan-waves` (or `fak issue-lanes`) to partition the backlog into tree-disjoint cohorts, arbitrates lane and tree leases via `dos arbitrate`,…
  • 100burndown-issues
    Pick one open GitHub issue off this repository's queue, implement the fix, and open a pull request for it. One issue and one PR per run. Use when the user asks to burn down the issue backlog, or when the issue-burndown workflow invokes it. It never merges, never closes an issue,…
  • 100issue-burndown
    Use when asked to work through many open GitHub issues at once — "fix all the open issues", clear or triage the backlog, figure out which issues are already fixed or covered by PRs, batch-fix issues, or drive a set of issues to merged PRs.
  • 100debt-clean
    One repeatable, evidence-backed pass that retires a bounded batch of maturity debt worst-first across the system's dedicated debt lanes. Features rich queryability (--query, --health), cross-indexes related items (dual-repo companions, tests, runtime-proofs, benchmarks, inbound…
  • 87burn-down-github-issues
    Run an unattended burndown of a GitHub issue backlog as cards on a per-operator GitHub Projects board whose lanes are an explicit state machine: appraise and size the inbox, carve what is over the ceiling, fix the ready ones in parallel git worktrees, prove each fix on a draft…
  • 100queue
    Manage the issue queue for sequential and batch pipeline processing. Add, list, remove, and clear queued issues. Supports epic expansion and label-based queuing. Use when staging which issues the pipeline processes next, or when clearing the queue.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.