doccraft-queue-audit

name

doccraft-queue-audit

description

Reconcile the dependency graph, pick-next queue, and backlog status across docs/stories/, docs/queue.md, and docs/backlog.md. Use after adding or editing a story (especially one with depends_on), after reshuffling priorities, or when the user asks "what can I work on next", "what's unblocked", "sanity-check the queue", "check my story dependencies", "fix the queue order", or "what parallel work is ready". In Agent mode (the tool can write files), apply objective mechanical fixes in the same turn and report what changed; in Ask / read-only mode, emit a proposal instead. Stop and report — never guess — on directed cycles, unknown depends_on ids, duplicate ids, or ambiguous editorial reorders.

Managed by doccraft — doccraft update regenerates this file. Local edits will be overwritten. See doccraft.json to override project-specific vocabulary and paths without touching this file.

doccraft — queue, dependency audit, and parallel waves

When to use

• After adding a story, changing depends_on / id, or reshuffling priorities and you want a sanity check on docs/queue.md.
• The user asks "what can I work on next", "what's unblocked", "sanity-check the queue", or similar pick-next / dependency questions.
• The user asks for parallel-ready batches ("what can I run in parallel?") — see Parallel waves below.
• The user pastes the suggested follow-up block from doccraft-story.

Not for: authoring a new story (use doccraft-story), recording a decision (use doccraft-adr), proposing artifacts from a chat thread (use doccraft-session-wrap), or closing one specific story end-to-end (use doccraft-close — it does the status/backlog/queue/epic transition, then defers to this skill's reconcile invariants).

Configuration

Read doccraft.yaml at invocation. Every key below has a default in the rest of this body so a missing config file is a soft fallback, not an error.

Relevant keys:

• docsDir — root folder for all docs. Default: docs. Stories, queue, and backlog are at {docsDir}/stories/, {docsDir}/queue.md, {docsDir}/backlog.md.
• queue.tables.suggestedOrder, queue.tables.platformSpikes — the heading text this skill uses to find the two tables in the queue file. Defaults: Suggested order, Platform spikes. Rename in config if the project uses different headings; the skill matches on heading text, not row position.
• story.id.pattern — regex for valid story ids. Used when listing unknown-id errors and when normalising obvious typos.
• queueAudit.laneFrom — tag-prefix priority list for the lane heuristic in the parallel-waves pass. Default: [area, slice]. Set to [slice, area] for projects that group work primarily by product surface. May also include epic — when present (and an epics extension defines the epic: story field), the queue groups by epic, which is the primary ordering for milestone/epic projects (ADR 016).
• story.status — the project's allowed status values. Whichever of these mean "no longer active work" are terminal (done always, plus any the project adds: done-no-promote, abandoned, absorbed). Wherever this skill says a story is done / shipped, it means any terminal status — read the vocabulary rather than matching the literal done, or a story closed as absorbed will wrongly look unfinished and never satisfy its dependents.
• queueAudit.scale.maxStoryFiles, queueAudit.scale.maxQueueReorderPct — thresholds that trigger stop-and-confirm in Agent mode. Defaults: 5, 50. See Containment below.

Multi-package scope

For monorepo projects (a Known package roots block appears above when packages are declared), this skill operates over multiple docs roots. For single-root projects the entire skill operates on the project-root docs/.

When the project declares packages, the default scope is the active package, determined by (a) an explicit package: arg in the user request; (b) inference from the active file's path under a declared package root; or (c) the project root if neither applies. The skill reads <scope>/docs/stories/, <scope>/docs/queue.md, and <scope>/docs/backlog.md for that scope only.

Cross-scope depends_on. Story depends_on entries of the form <slug>/STR-NNNN reference a story in another package. When checking whether a prerequisite is satisfied, resolve the target against the matching package root, read its status, and treat done as satisfied. Cross-scope edges MUST NOT trigger reorders in the other package's queue — flag any that look stale and let the user choose.

Materialised aggregate (monorepo only). Per ADR 016, the root docs/queue.md in a monorepo is a generated cross-package aggregate, not a hand-maintained file. It composes every package root and the project root into one ordered queue, using queueAudit.laneFrom for the primary grouping (epic first → the milestone/epic roadmap; otherwise area/slice). Each row carries the scope-prefixed id and a resolvable link to the story file (ADR 017).

• Regenerate, don't hand-edit. When the user asks "what's unblocked anywhere", "regenerate the roadmap", reshuffles cross-package priorities, or as the reconcile step of doccraft-close, rebuild this file from the per-scope stories and queues. The file MUST open with a generated-artifact marker (e.g. <!-- generated by doccraft-queue-audit — do not edit by hand; edit per-package queues instead -->) so no one curates it manually. This is the single change ADR 016 makes to ADR 014 §5: the aggregate is generated rather than forbidden.
• Per-package queues stay scope-local. Each package's own docs/queue.md is authored/reconciled normally and is the source of truth; the root aggregate is derived from them and never the place to edit a package's ordering.
• Single-root projects have no aggregate — the one queue.md is a normal authored file, and this paragraph does not apply.

What this skill reads and writes

Reads:

• docs/stories/*.md — YAML frontmatter (id, status, impact, urgency, depends_on, tags, openspec, roadmap_ref, optional openspec_change).
• docs/queue.md — the Suggested order table, plus Platform spikes when parallel waves are in scope.
• docs/backlog.md — the Story files table and the Status column.

Writes (Agent mode only, on objective fixes):

• docs/queue.md — reorder rows; drop rows for shipped stories.
• docs/backlog.md — update the Status column.
• docs/stories/*.md — narrow YAML edits (see Auto-apply rule 4).

Input

The user may paste a one- to three-line briefing (what changed, optional scope). If they omit it, infer from the repo: read every file under docs/stories/ (skip README.md) and docs/queue.md.

---

Mode: propose vs apply

Two behaviours, controlled by the environment — not by user enthusiasm:

• Apply (Agent mode). The tool can write files. Treat the audit as read + fix — apply objective mechanical fixes in the same turn, then report what changed. See Auto-apply below.
• Propose (Ask / read-only mode). The tool cannot write files. Emit a diff-style proposal plus the same issues list; NEVER suggest commits. The user copies anything they want applied into a follow-up turn.

If the environment is Ask mode, NEVER write files even when the user asks — emit a proposal they can apply themselves.

Auto-apply (Agent mode)

Apply in the same turn when the fix is objective — a rule-based reconciliation that any auditor would make the same way:

1. Stale suggested-order rows. A story linked from Suggested order has status: done but still appears in the pick-next table: remove that row and renumber subsequent rows. Optionally backfill a new bottom row from the next obvious pick in the same band (main vs. platform spikes).
2. Backlog status drift. For a roadmap_ref whose story file is status: done, if the matching Status cell in docs/backlog.md still reads planned or equivalent, update it to the project's established "done" phrasing. NEVER mark done in the backlog when the story is still todo or in_progress.
3. Queue order vs depends_on. For each id Q in Suggested order, if some prerequisite d is not done and does not appear above Q: reorder rows minimally until the rule holds, or move Q below every unfinished d. MUST prefer moving blocked work down over reshuffling the whole table.
4. Flat urgency/impact inversions — narrow scope. Only when a story with urgency: later sits above a story with urgency: now in the same band and no depends_on justifies the order: update urgency on the lower-urgency story (users tend to understate, not overstate). If the inversion is not flat — if there is any ambiguity — list it under Remaining proposals instead of editing.

Containment

• Scale threshold. If the audit would touch more than 5 story files or reorder more than half the Suggested order rows, MUST stop and report the full plan first, then wait for user confirmation. Large changes MUST be a human decision.
• Working-tree awareness. If the user has uncommitted changes in docs/queue.md, docs/backlog.md, or any story file you would touch, MUST report the planned changes first and let the user decide. NEVER overwrite in-progress work.
• Commits. NEVER create commits unless the user asks. Describe what changed so they can commit in their preferred grouping. When the user does ask to commit, MUST prefer one commit per file class (queue, backlog, stories) over one mega-commit — easier to review and revert. If the project uses conventional commits, docs(queue): / docs(backlog): / docs(stories): scopes are natural.

Stop and report (no edit)

NEVER guess through these — list them clearly and let the user decide:

• depends_on references an unknown id. List the offending story and the dangling id. Fix only obvious typos that restore a known id (e.g. P0-3 → P0.3) and say you did.
• Directed cycle. List the cycle (A → B → A). NEVER delete edges to break it — the user MUST choose which edge is wrong.
• Duplicate id. Two stories claim the same id. Flag; NEVER rename either.
• Ambiguous editorial reorder. Multiple valid orderings satisfy the constraints. Summarise the options (e.g. "put P0.2 before P0.5 because impact:H, or after because urgency:soon"); NEVER pick.
• Ambiguous scope (monorepo). No explicit package: arg and the user's briefing references stories across multiple package roots. Ask which scope to audit before proceeding.

---

Fields consulted

See doccraft-story for the full frontmatter contract. For the audit, the fields that matter are:

• id — node id in the graph; MUST be unique across stories.
• depends_on — directed edges. Each entry MUST match another story's id or an explicit backlog row; unknown ids are errors.
• status — terminal nodes (any value in story.status that means closed: done, and project additions like done-no-promote, absorbed, abandoned) satisfy prerequisites; non-terminal nodes (todo / in_progress) remain scheduling candidates. Match against the configured vocabulary, not the literal string done.
• impact / urgency — tie-breakers once dependency constraints are satisfied.
• roadmap_ref — ties the story to its docs/backlog.md row for the backlog-drift check.

Graph checks

1. Build directed edges. For each story S and each d in depends_on, add edge d → S ("d is a prerequisite of S"; complete d before scheduling S).
2. Unknown id. depends_on references an id with no story and no clear backlog row: list as an error.
3. Cycles. If the d → S graph has a directed cycle, list it.
4. Open subgraph. Among stories with status ≠ done, the sources (no unfinished prerequisites) are natural "start next" candidates.

Queue checks

Precedence: when story urgency and depends_on disagree, unfinished prerequisites win unless the queue row explicitly documents accepted debt in its Notes column.

1. Parse the Suggested order table in docs/queue.md. Story links and id labels appear in the first column.
2. For each queued row with id Q, every d in depends_on MUST either be done or appear above Q (or be explicitly accepted as parallel work — call that out).
3. Flag any row whose story is done but still listed.

Output format

MUST use these five sections in this order:

1. Summary. Graph health (ok / issues) and whether auto-apply ran.
2. Issues. Unknown ids, cycles, duplicate ids, queue-order violations that remain after fixes.
3. Changes applied. Bullet list — which files, what moved (row numbers / backlog rows / frontmatter fields). If nothing changed, say None.
4. Remaining proposals. Subjective reorders, new rows, or depends_on edges inferred from story bodies but not in YAML — list here when they are not unambiguous enough for auto-apply.
5. Exit. If the graph and queue are clean and the backlog matches shipped stories, say so in one line.

Example output

**Summary:** Graph clean (6 stories, 4 edges, 0 cycles). Auto-apply ran.

**Issues:** None.

**Changes applied:**
- `docs/queue.md`: removed row 3 (P0.3, status: done); renumbered rows 4–6 → 3–5.
- `docs/queue.md`: moved P2.1 below P1.4 (unfinished prerequisite P1.4).
- `docs/backlog.md`: P0.3 Status → "shipped (v0.4.0)".

**Remaining proposals:**
- P2.5 and P2.6 have equal urgency:soon / impact:M and no dependency edge — consider which to prioritise.

**Exit:** Queue and backlog are now consistent with the dependency graph.

---

Queue ordering rules

When reordering or reviewing an auto-apply, these are the rules this skill enforces:

1. Read frontmatter. For each candidate story, read impact, urgency, depends_on. Read story bodies for chains not yet in YAML and add depends_on when a chain is stable.
2. Order. Higher urgency and impact move up, but depends_on overrides: prerequisites MUST be done or appear above this story. If urgency and depends_on disagree, unfinished prerequisites win unless debt is documented.
3. Keep stories honest. If the table order implies new urgency on a story, MUST update the story YAML in the same change — otherwise the table and frontmatter drift apart and the next audit will thrash.
4. Backlog. When a row ships or is dropped, MUST update the Status column for that id in docs/backlog.md. New queued items need a story file and a row in the backlog's Story files table.
5. Planned-tier coverage. Every planned row in docs/backlog.md MUST have a matching file under docs/stories/ and an entry in the Story files table. Reconcile periodically.

---

Parallel waves (optional pass)

Run this only when the user explicitly asks for parallel-ready batches ("what can I run in parallel", "parallel waves", "what's unblocked"). NEVER run as part of every audit — this is a separate pass.

Preconditions. Run the graph / queue checks first and surface any errors before proposing waves. NEVER propose waves on top of a broken graph.

Queue parsing.

• Extract story id from the link text (e.g. [P4.7]), not the filename.
• Preserve row order within each table; lower position = higher priority in the main table.
• Default scope: only stories whose id appears in the main Suggested order table.
• Include Platform spikes only when the user asks. "Spikes only" restricts candidates to that table.

Readiness.

• A prerequisite d is satisfied when the story with id: d has status: done. If d does not match any story file, treat as blocked and list under Problems — NEVER assume done.
• A story is ready when status is todo or in_progress, every prerequisite is satisfied, and its id is in the active scope.

Batching rules.

• Intra-batch dependency rule. No two stories in the same batch may share a depends_on edge (mutual or one-way).
• Lane heuristic. Assign each story a lane from queueAudit.laneFrom in priority order: for epic, use the story's epic: field; for area / slice, the first matching tags prefix; else lane: misc. MUST prefer batches where each lane appears at most once — reduces merge conflicts. If that drops too many ready items, note "merge risk: duplicate lane …" and offer a smaller batch or a second wave.
• Wave ordering. Sort ready candidates by (1) main-table row order, then (2) impact H > M > L, then (3) urgency now > soon

  later.

• Token discipline. Default proposal focuses on the top 3–6 ready items unless the user asks for a full scan.

OpenSpec gate. If the project uses OpenSpec, stories carry openspec: not-needed | recommended | required:

• required — flag prominently. User MUST complete their OpenSpec propose flow before heavy implementation. Link openspec_change when set.
• recommended — one line: "OpenSpec recommended if scope is fuzzy."
• not-needed — no mention needed.

Proposal output. For each candidate story, emit a compact row:

• id, title, status, lane (area/slice), openspec
• Prerequisites — list depends_on with target status
• Link — docs/stories/<file>.md
• Batch id (Wave 1, Wave 2, …)

End with a short Problems list when any id is missing, cyclic, or blocked.

---

Pre-apply validation

Before applying any change in Agent mode, MUST complete these checks:

1. All story files read — scan all docs/stories/*.md frontmatter (skip README.md) and build the full dependency graph before making any edit. NEVER apply partial fixes from an incomplete graph.
2. No directed cycles — if the graph contains a cycle, stop and report. NEVER break cycles by removing edges.
3. No unknown ids — every depends_on entry MUST resolve to an existing story id or backlog row. Fix only obvious typos; flag the rest.
4. No duplicate ids — every id MUST be unique. If duplicates exist, stop and report. NEVER rename either.
5. Scale threshold — if the planned changes exceed the containment limits (>5 story files or >50% of queue rows), stop and present the full plan. MUST wait for user confirmation before proceeding.
6. Working-tree clean — if uncommitted changes exist in any file you would touch, report the plan and let the user decide. NEVER overwrite.

Invalid examples (do not use)

• Deleting a depends_on edge to break a cycle — NEVER; the user MUST choose which edge is wrong.
• Renaming a story id to resolve a duplicate — NEVER; flag both and let the user decide.
• Marking a story as done in the backlog when its story file is still todo or in_progress — NEVER; backlog status MUST follow the story file, not lead it.
• Picking one ordering over another when multiple valid orderings exist — NEVER; list the options and let the user choose.
• Running parallel-waves analysis on a graph with unresolved errors — NEVER; fix or report graph issues first.
• Writing files in Ask / read-only mode — NEVER; emit a proposal only.
• Creating commits without the user explicitly asking — NEVER.

Done condition

The task is complete when:

• Every story file under docs/stories/ has been read and its frontmatter parsed into the dependency graph.
• All graph checks (unknown ids, cycles, duplicates) have been run and either resolved (auto-apply) or reported (stop and report).
• All queue checks (stale rows, ordering violations, backlog drift) have been run and either resolved or reported.
• The output follows the five-section format (Summary, Issues, Changes applied, Remaining proposals, Exit).
• If parallel waves were requested: the wave proposal is appended after the main audit output.
• No file has been written in Ask / read-only mode.

Optional follow-up template

Use when something cannot be auto-fixed (cycles, ambiguous priority) or when the user wants to re-run with narrower scope:

Invoke doccraft-queue-audit.

[Context, e.g. "Break cycle P3.2 ↔ P3.4 by removing depends_on X
from story Y."]
[Optional: "Re-check queue only." | "Parallel waves only."]

References

• docs/queue.md — pick-next tables.
• docs/backlog.md — full P-tier tables and Status column.
• doccraft-story — field contract for story frontmatter.

Project-specific vocabulary (tiers, area/slice tags, queue-table headings, scale thresholds) lives in doccraft.yaml — the Configuration section above lists the keys this skill reads. The tables in this body are defaults used when no config is present.