RonanCodes/skills/backlog-audit

Backlog Audit

Issues added across different days drift: relationships go implicit, priorities go stale, duplicates creep in, and "what do I build first" stops being obvious. This skill is the periodic refinement pass that re-imposes order, so the backlog stays kickable by a human or by /ro:ultracode without archaeology.

Siblings: /ro:project-status (reports the backlog), /ro:ultracode (executes the build queue), /ro:slice-into-issues (creates child slices). This skill is the groomer that keeps their shared input clean.

When to run (be proactive)

• Proactively after a session adds 3+ new issues, or after a burst of issues across multiple days that were never cross-linked. Don't wait to be asked: if you've just filed several issues, offer to run it.
• On demand when the user asks to refine/groom/audit the backlog.
• Before kicking off a /ro:night-shift or /ro:ultracode drain, so the order is trustworthy.

True auto-fire needs a hook and issue-creation isn't a clean local event, so the realistic trigger is behavioral: the agent runs it when it notices backlog churn. Note that honestly rather than pretending it's automatic.

Steps

1. Pull the whole open backlog

gh issue list --repo <repo> --state open --limit 100 \
  --json number,title,labels,body,createdAt,comments

Read each body + the coordination-hub comments. --repo defaults to the current repo's gh remote; --hub defaults to the pinned coordination issue (the one labelled the hub, e.g. the "coordination" / shared-memory anchor) or ask.

2. Build the dependency graph

For every issue, infer:

• Parent / children — from ## Parent\n\n#N, PRD slice lists, or prd-labelled umbrellas.
• Blocks / blocked by — explicit "blocks #N", "depends on #N", "needs #N", a key/secret/spend/legal gate, or a referenced unbuilt slice.
• Enables — the inverse of blocks (this unlocks #N).
• Priority — existing priority:* labels, pinned ordering, age + size + unblocks-others (the night-shift 4-signal intuition).
• Created cohort — group by created date so same-day batches are visible and reconciled against each other.

3. Detect problems (the audit)

Flag and report:

• Orphans — no parent, no relations, unclear where it fits.
• Cycles — A blocks B blocks A in the blocks graph.
• Blocked-by-closed — blocked by an issue that's already closed (likely now unblocked).
• Likely duplicates / overlaps — near-identical titles or scope.
• Stale priority — priority:next on something now blocked, or a high-priority item superseded.
• Un-ordered cohorts — a day's batch of issues with no relative order set.

4. Normalize each issue (with --apply)

Insert/replace an idempotent block at the top of each issue body (replace the existing one if present, never stack duplicates):

<!-- backlog-audit:relations -->
## Relations
- **Parent:** #N (or none)
- **Blocks:** #A, #B (or none)
- **Blocked by:** #C (or none) — <why, if a gate>
- **Enables:** #D
- **Priority:** next | later | someday
- **Added:** YYYY-MM-DD (cohort)
<!-- /backlog-audit:relations -->

Apply consistent labels: priority:next / priority:later, blocked (+ a one-word why via a blocked:key|spend|legal|dep label or note), prd, parent linkage. --dry-run (default) prints the plan; --apply writes via gh issue edit / gh issue comment.

5. Refresh THE canonical map (one place)

Write/replace a single Backlog map comment on the coordination hub (idempotent — edit the prior audit comment if found, else post one). This is the artifact that makes "how should I do this" obvious:

## Backlog map (audited YYYY-MM-DD)
### Build order (ready, unblocked)
1. #49 — leads schema + create-lead  [enables #48]
2. #48 — voice outreach workflow      [needs #43, #49]
...
### Blocked (and on what)
- #27/#32/#33 — Telnyx NL number (~date)   [spend]
### PRD umbrellas → open slices
- #1 Relations → #48 ...
### Flags for human
- possible dup: #X ~ #Y
- #Z blocked by closed #W → likely unblock

6. Report

Print: counts (audited / relinked / relabelled), the build order, and the flags needing a human decision. Keep it tight.

Guardrails

• Read-mostly + structured writes. Only edits issue bodies' relations block, labels, and the hub map comment. Never closes issues or changes titles without surfacing it first.
• Idempotent. Re-running produces the same shape, the relations block and hub comment are replaced, not duplicated.
• Don't invent dependencies. If a relationship isn't evidenced in the issues, flag it as a question, don't assert it.
• Respect repo-mode: on a work repo with no GH side-effects, write the map to the local backlog file instead.