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`), or proposing artifacts from a chat thread
(use `doccraft-session-wrap`).

## 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
  your 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.
- `queueAudit.scale.maxStoryFiles`, `queueAudit.scale.maxQueueReorderPct`
  — thresholds that trigger stop-and-confirm in Agent mode. Defaults:
  `5`, `50`. See **Containment** below.

## 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; do not suggest commits.
  The user copies anything they want applied into a follow-up turn.

If the environment is Ask mode, do not write files even when the user
asks you to — 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. Do not 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`. 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,
  stop and report the full plan first, then wait for the user to
  confirm. Large changes should 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, report the planned changes first and let the user decide.
  Do not overwrite in-progress work.
- **Commits.** Do not create commits unless the user asks. Describe
  what changed so they can commit in their preferred grouping. When
  the user does ask to commit, 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)

Do not 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`). Do not delete edges
  to break it — the user must choose which edge is wrong.
- **Duplicate `id`.** Two stories claim the same `id`. Flag; do not
  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"); do not pick.

---

## 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` — `done` nodes satisfy prerequisites; `todo` / `in_progress`
  nodes remain scheduling candidates.
- `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

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 —
   leave 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.

---

## How to think about the queue

When reordering by hand or reviewing an auto-apply, keep these rules
in mind — they are the implicit contract the 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` usually move up, but
   `depends_on` can override: prerequisites should 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, 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, 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` should 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").
It does not run as part of every audit — it is a second pass.

**Preconditions.** Run the graph / queue checks first and surface any
errors before proposing waves. Do not 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 — do not 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.** From `tags`, take the first `area:*`, else
  `slice:*`, else `lane: misc`. 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 should 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.

---

## Optional follow-up template

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

```text
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.