backlog

name	backlog
description	Manage backlog todo documents in docs/backlogs with deterministic tooling. Use when manually creating backlog items with duplicate checks, especially deferred follow-ups discovered during in-progress task/RFC work that need recoverable context, or closing/archiving backlog items with explicit reasons.

Backlog Workflow

Use this skill for backlog lifecycle operations. Scripts are executable; invoke them directly (no cargo +nightly -Zscript prefix).

This skill has two prompt workflows:

1. backlog create: create a new backlog todo with duplicate check.
2. backlog close: close/archive an open backlog item with reason.

backlog create Required Flow

1. Understand and confirm the user's backlog intention first.
2. Classify the backlog item before collecting fields:
   • standalone follow-up backlog item, or
   • intentionally deferred work from active task/RFC execution.
3. Collect required base fields:
   • title
   • slug
   • summary
   • reference
   • scope hint
   • acceptance hint
   • optional notes
4. If the backlog item is intentionally deferred from active task/RFC work, require deferred-work context:
   • deferred from: source task doc, source RFC doc/phase, or both.
   • defer reason: why the work is postponed now.
   • findings: what current execution learned and should not be lost.
   • direction hint: what future task/RFC planning should revisit, prefer, or avoid.
5. Run duplicate detection on open backlog docs only:

tools/backlog.rs find-duplicates \
  --title "Backlog title" \
  --slug "backlog-title"

6. If duplicate candidates exist, show candidates and ask whether to continue.
7. Create the backlog doc with allocated id:

tools/backlog.rs create-doc \
  --title "Backlog title" \
  --slug "backlog-title" \
  --summary "..." \
  --reference "..." \
  --scope-hint "..." \
  --acceptance-hint "..." \
  --auto-id

When the item is intentionally deferred from active task/RFC work, also pass:

  --deferred-from "docs/tasks/000040-example.md; docs/rfcs/0006-example.md phase 2" \
  --defer-reason "..." \
  --findings "..." \
  --direction-hint "..."

8. If docs/backlogs/next-id is missing, initialize it first:

tools/backlog.rs init-next-id

Ensure deferred-work backlog docs preserve enough context for a future task or RFC to recover the right design direction instead of re-discovering the same issue from scratch. For multiline text, markdown, Rust code, or any text containing backticks, prefer the file-backed flags (--summary-file, --reference-file, --notes-file, --deferred-from-file, --defer-reason-file, --findings-file, --direction-hint-file) instead of inline shell arguments. Default safe pattern: write the text with a quoted heredoc such as <<'EOF' to a temp file, then pass the file path to tools/backlog.rs create-doc.

backlog close Required Flow

1. Resolve and confirm the target is an open backlog doc in docs/backlogs/.
   • If user input is id-only shorthand (for example backlog close 000123 ...), resolve first:

tools/doc-id.rs search-by-id --kind backlog --id 000123 --scope open

2. Require explicit close reason type and detail.
3. Close/archive with:

tools/backlog.rs close-doc \
  --path docs/backlogs/000123-example.md \
  --type stale \
  --detail "Superseded by later design"

4. Ensure file moves to docs/backlogs/closed/ and includes ## Close Reason. If detail or reference text is longer than a short phrase or contains markdown/backticks, use --detail-file and --reference-file.

Output Quality Bar

Ensure every backlog document is:

1. Specific about why the follow-up exists now.
2. Linked to source task/RFC work when it was intentionally deferred from active execution.
3. Explicit about why the work was deferred and what was learned.
4. Useful as future planning input rather than just a reminder title.

Reference

Read references/workflow.md for detailed create/close checklists.