/sdlc:backlog-triage

Generated from solutions/ontological/plugin/plugins/sdlc/skills/backlog-triage/backlog-triage.md.

Description

Walk untriaged backlog files in docs/planning/backlog/ and decide what to do with each: promote to task, promote to milestone, defer (bump last_reviewed), or skip. Promotion calls sdlc task create / sdlc milestone create directly and updates the backlog frontmatter to point at the new artifact. Commits each decision atomically on the current branch, honouring the project’s branching conventions.

Allowed tools

Read
Edit
Bash
Glob
AskUserQuestion

Source

Usage:

/sdlc:backlog-triage — walk every untriaged backlog file.
/sdlc:backlog-triage <slug-or-path> — triage just the named file.

Untriaged ≡ frontmatter has no state: field. Any task with state: set (whether promoted/* or closed/*) is considered already triaged and skipped by the no-arg pickup.

Project context (don’t re-derive every run):

Backlog files live at docs/planning/backlog/<slug>.md. Schema at ${CLAUDE_PLUGIN_ROOT}/lib/model/entities/backlog/schema.ts.
Two usage patterns coexist (see the template head comment). This skill targets single-candidate files — those representing one idea that may get promoted. Multi-item dump files (where the body holds many ideas) typically don’t ever get state: set; for those, this skill offers “defer” (bump last_reviewed) but the per-item promotion is up to the author.
Frontmatter mutations go through sdlc backlog update <backlog> --set '<json>' (schema-validated before write, body byte-untouched, a null value deletes a key); the standalone validator is sdlc entities validate.
Promotion writes both a new task/milestone file AND updates the backlog frontmatter. Both go in one commit per decision so the link is atomic.
Commit each decision on the branch you are already on. Do NOT switch branches, and do NOT assume main is committable — a project may require that its main checkout stay clean and that all work happen on a branch or worktree. Read the project’s own conventions before the first commit. If they forbid committing on main and that is where you are standing, stop and ask the user where to work rather than committing anyway. Whether the run ends in a PR is the caller’s decision, not this skill’s.

1. Survey

If an argument was given, resolve it:

Absolute path → use as-is if the file exists under docs/planning/backlog/.
Otherwise, glob docs/planning/backlog/<arg>*.md then docs/planning/backlog/*<arg>*.md. If exactly one matches, use it. If multiple match, present the list via AskUserQuestion and let the user pick. If none, exit NO BACKLOG FOUND for "<arg>".

If no argument, list docs/planning/backlog/*.md and read frontmatter from each. Filter to the untriaged set (no state: field at all). Sort by filename (alphabetical). If the untriaged set is empty, exit NO UNTRIAGED BACKLOG FILES.

Report at the start: how many files will be triaged, and their slugs.

2. Per-file decision loop

For each file in turn:

Read the file. Capture:
- Frontmatter (current state, tags, last_reviewed).
- Headline (the first # line in the body, stripped).
- Body summary — the first ~200 chars after the headline. If the body is short, show the whole thing.
Present the file to the user as a short text block: slug, headline, current tags, last_reviewed (if set), then the body summary. Keep this concise — three to six lines.
Ask via AskUserQuestion (4 top-level options):
- Promote to task — create a task via sdlc task create, then set this backlog to state: promoted/task with result: [[<new-task-basename>]]. Default action for items that map to one concrete change.
- Promote to milestone — create a milestone via sdlc milestone create, then set this backlog to state: promoted/milestone with result: [[M-<NNNN>-<slug>]]. For larger outcomes spanning multiple tasks.
- Close — discard without promotion, or record that the item shipped without ever being promoted. A second AskUserQuestion asks the reason: abandoned (won’t do / no longer relevant; no result: needed), duplicate (followed by a plain-text ask for the canonical backlog slug → result: [[<other-slug>]]), or delivered (the idea was built directly, no task/milestone in between — followed by a plain-text ask for the PR link or a short note of what shipped → result: <that text>).
- Defer — bump last_reviewed: to today; no other change. Use when the item is still relevant but you’re not ready to promote.
Execute the chosen action (steps 3–6 below). Then continue the loop.

There is no explicit “skip” option. To leave an item undecided, interrupt the session: committed decisions stay and the unprocessed files remain untriaged, resurfacing in the next run.

3. Promote to task

Preview the slug + id task create would assign for the backlog headline, and surface any collision so the user can decide whether this backlog is already a task:
```
${CLAUDE_PLUGIN_ROOT}/cli/sdlc task preview-id "<backlog-headline>" --output json
```
The op is read-only: it derives the slug (the same capped deriveSlug create uses with --slug omitted) and reports the would-be id, plus exists/exact_match (an existing task with the identical slug) and similar[] (existing tasks with a close slug). If the input has no alphanumeric content it exits non-zero (INVALID_INPUT) — that’s the only “empty slug” case; when it happens, ask the user via AskUserQuestion for a different headline to derive from.

Then make the load-bearing “is this backlog already a task?” decision via AskUserQuestion, keyed off the preview output:
- If exists is true (or exact_match is non-null), an existing task already carries this exact slug — offer reuse (point this backlog’s result: at exact_match.id and skip creation) vs override (free-form text via Other for a distinct slug to pass as the positional below).
- Else if similar[] is non-empty, surface those neighbors (their ids + slugs) and offer the same reuse-vs-proceed choice.
- Else (no exact, no similar) proceed straight to creation — no override needed.
Create the task. With --slug omitted, create DERIVES the slug from the headline (the same derivation preview-id just showed), so don’t hand-pass it. Only pass an explicit <slug> positional when the user chose override above:
```
${CLAUDE_PLUGIN_ROOT}/cli/sdlc task create \
  --headline "<backlog-headline>" \
  --state planning/draft \
  --impact medium \
  --complexity medium
```
Capture the printed path and the minted id. The task’s canonical id is the T-<NNNN> form preview-id reported (and create prints) — the schema-assigned id, not a dated basename. Use it for the result: wikilink. (When the user chose reuse, skip this step and point result: at the existing exact_match.id instead.)
Update the backlog frontmatter via sdlc backlog update (schema-validated; the body is left byte-untouched):
```
${CLAUDE_PLUGIN_ROOT}/cli/sdlc backlog update <backlog-path> \
  --set '{"state":"promoted/task","result":"[[T-<NNNN>-<slug>]]","last_reviewed":"<today>"}'
```
The result: wikilink MUST be the canonical [[T-<NNNN>-<slug>]] form (the schema-assigned id, NOT the dated basename); the op rejects a date-prefixed shape. <today> is today (UTC, YYYY-MM-DD). The op fails non-zero if the resulting frontmatter does not validate — fix the --set payload and re-run before committing.
Commit atomically — only the two files; don’t sweep in unrelated changes. Stage the exact paths, then author the message through sdlc commit create (subject + body; no shell re-parse of the conventional-commit parens):
```
git add <task-path> <backlog-path>
${CLAUDE_PLUGIN_ROOT}/cli/sdlc commit create \
  --subject "docs(planning): promote backlog/<backlog-slug> to task/<task-basename>" \
  --body "<backlog-headline>"
```

4. Promote to milestone

Mirror step 3, but:

Use sdlc milestone create instead of sdlc task create. The milestone op auto-assigns the next M-<NNNN> id — capture it from the printed path.

Update the backlog via sdlc backlog update with state: promoted/milestone and result: [[M-<NNNN>-<slug>]]:

${CLAUDE_PLUGIN_ROOT}/cli/sdlc backlog update <backlog-path> \
  --set '{"state":"promoted/milestone","result":"[[M-<NNNN>-<slug>]]","last_reviewed":"<today>"}'

Stage both files and commit through sdlc commit create:

git add <milestone-path> <backlog-path>
${CLAUDE_PLUGIN_ROOT}/cli/sdlc commit create \
  --subject "docs(planning): promote backlog/<backlog-slug> to milestone <M-id>" \
  --body "<backlog-headline>"

The milestone create call:

${CLAUDE_PLUGIN_ROOT}/cli/sdlc milestone create \
  --title "<backlog-headline>" \
  --state open/draft

(Don’t seed tasks or other fields — the milestone will be fleshed out later by /sdlc:milestone-new follow-ups or by hand.)

5. Close

The user picked Close in step 2.3. Ask via AskUserQuestion which reason applies (3 options):

Abandoned — won’t do, no longer relevant. No result: needed.
Duplicate — already captured elsewhere. Follow up with a plain-text ask: “Which backlog slug is this a duplicate of? (just the slug, no [[...]])”. Validate the response against SLUG_RE from ${CLAUDE_PLUGIN_ROOT}/lib/util/slug.ts. Confirm the target file exists at docs/planning/backlog/<slug>.md; if not, ask again or offer to abandon instead.
Delivered — built directly, without ever going through promoted/task or promoted/milestone. Follow up with a plain-text ask: “PR link or short note of what shipped?” → result: carries that text verbatim (a markdown PR link, e.g. [#1880](https://github.com/sksizer/dev/pull/1880), or a short freeform note — no wikilink shape required).

Then update the backlog frontmatter via sdlc backlog update:

Abandoned: the schema FORBIDS result: on closed/abandoned, so null-delete any prior result: in the same call.

${CLAUDE_PLUGIN_ROOT}/cli/sdlc backlog update <backlog-path> \
  --set '{"state":"closed/abandoned","result":null,"last_reviewed":"<today>"}'

Duplicate:

${CLAUDE_PLUGIN_ROOT}/cli/sdlc backlog update <backlog-path> \
  --set '{"state":"closed/duplicate","result":"[[<other-slug>]]","last_reviewed":"<today>"}'

Delivered: the schema REQUIRES result: on closed/delivered, freeform (not wikilink-shaped).

${CLAUDE_PLUGIN_ROOT}/cli/sdlc backlog update <backlog-path> \
  --set '{"state":"closed/delivered","result":"<PR link or note>","last_reviewed":"<today>"}'

The op is schema-validated; it fails non-zero if the result does not validate. Then commit only that file through sdlc commit create:

git add <backlog-path>
${CLAUDE_PLUGIN_ROOT}/cli/sdlc commit create \
  --subject "docs(planning): close backlog/<backlog-slug> as <reason>" \
  --body "<one-line note: backlog headline for abandoned; '\"<headline>\" — duplicate of <other-slug>' for duplicate; '\"<headline>\" — delivered in <PR link>' for delivered>"

6. Defer

Update the backlog frontmatter via sdlc backlog update: set last_reviewed: to today. Do not change state:. The op is schema-validated and leaves the body byte-untouched.
```
${CLAUDE_PLUGIN_ROOT}/cli/sdlc backlog update <backlog-path> \
  --set '{"last_reviewed":"<today>"}'
```

Commit only that file through sdlc commit create:

git add <backlog-path>
${CLAUDE_PLUGIN_ROOT}/cli/sdlc commit create \
  --subject "docs(planning): defer backlog/<backlog-slug>" \
  --body "Reviewed but not yet promotion-worthy."

7. Wrap up

After the loop finishes (or the user stops it), print a short summary:

N files considered.
For each: what happened (promoted to task/<basename>, promoted to milestone M-<NNNN>, closed/abandoned, closed/duplicate of <slug>, closed/delivered, deferred).
If anything was committed, hint that the user can git log --oneline to review or git reset HEAD~<n> to undo a contiguous batch.

Acceptance criteria

Every promoted backlog file has state: promoted/<entity> AND a canonical result: wikilink ([[T-<NNNN>-<slug>]] for a task, [[M-<NNNN>-<slug>]] for a milestone — never a date-prefixed basename) AND last_reviewed: set to today.
Every closed/duplicate backlog file has state: closed/duplicate AND result: [[<other-backlog-slug>]] AND last_reviewed: set to today, and the referenced backlog exists.
Every closed/abandoned backlog file has state: closed/abandoned AND last_reviewed: set to today, and NO result: field.
Every closed/delivered backlog file has state: closed/delivered AND a non-empty result: (a PR link or short note of what shipped) AND last_reviewed: set to today.
Every modified backlog file passes sdlc entities validate.
Every promotion produced exactly one new artifact file AND one updated backlog file, both in the same commit. Every close updated exactly one backlog file in its commit.
Deferred backlog files have only their last_reviewed: changed.
Files left unprocessed by the session are byte-identical to their pre-skill state.
No file outside docs/planning/ was modified.

Notes

Promotion does NOT invoke the interactive /sdlc:task-new or /sdlc:milestone-new skills — they ask too many follow-up questions for a triage flow. The new artifact lands with sensible defaults (task: state: planning/draft, impact: medium, complexity: medium; milestone: state: open/draft, no version or target_date). The author refines them later via /sdlc:task-define and /sdlc:milestone-new follow-up edits.
The backlog body is NOT carried over into the new task/milestone. The body stays in place on the backlog file as the origin story; the new artifact starts empty. To seed the body content into the task, follow up with /sdlc:task-define or paste it in by hand.
This skill never changes the body of a backlog file — only frontmatter. Strike-through / deletion of promoted items inside multi-item dump files is the author’s job.
Backlog files with state: already set are NOT re-triaged. To re-promote (e.g. you decide the task it pointed at should actually be a milestone), edit the backlog frontmatter manually — clearing state and result returns the file to the untriaged set.
Committing model-generated messages. Each decision’s commit is authored through sdlc commit create (--subject/--body, or --message - for whole messages on stdin) so the conventional-commit parens never reach a re-parsing shell. See ${CLAUDE_PLUGIN_ROOT}/conventions/commit-messages.md — the op is the canonical pattern; the mktemp + quoted-heredoc + git commit -F form stays documented there only as the no-CLI-available fallback. Stage the exact paths with git add <paths> first — commit create commits the staged index, it does not narrow scope.