backlog

Backlog System

Use the backlog as durable planning memory, not as authority over the code. Keep enough history that a later agent can answer what was built, what is next, what was considered, what should not be built, why priorities changed, and what evidence proved completion.

Start With The Right Pass

• If asked to create a backlog system from scratch, read references/layout-and-templates.md first and establish the directory layout, overview, and recurrent tasks before adding many items.
• If asked to add or revise a backlog item, inspect the current code and docs first. Then read references/layout-and-templates.md for the correct item shape.
• If asked to complete or deprecate work, read references/maintenance-checklists.md first so history, ledgers, links, and follow-ups are preserved.
• If asked to clean up, normalize, triage, or sync the backlog, run the hygiene and follow-up flows in references/maintenance-checklists.md.

Apply The Operating Rules

• Read the repository before writing backlog text. Treat stale backlog text as a bug.
• Keep every item standalone enough for a future agent to execute without the original chat.
• backlog owns work-item lifecycle, planning state, and implementation history. adr owns durable cross-task policy.
• Separate committed work from speculative work:
  • planned/ for intended implementation work.
  • proposed/ for plausible but uncommitted ideas, risks, or experiments.
  • completed/ for closed audit records.
  • deprecated/ for superseded, rejected, or indefinitely deferred work.
  • recurrent/ for periodic process tasks.
• Keep one durable overview that records counts, priorities, next recommended work, ledgers, and operating rules.
• Every backlog item file must start with a four-digit global ID prefix: NNNN_<slug>.md. This is mandatory across planned/, proposed/, completed/, deprecated/, and topic subfolders. A number such as 0044 should identify one durable backlog item for search and references.
• Do not put dates in backlog item filenames. Dates belong inside item metadata such as Created, Completed, Deprecated, or completion reports.
• Preserve history instead of rewriting it away. Move items across states and append reports; do not silently replace earlier intent.
• Cross-reference relevant ADRs, docs, code, tests, and related backlog items.
• If a backlog item creates a rule that should outlive the task, do not leave that rule buried in backlog prose. Create or update an ADR before closure, or record explicit ADR state explaining why not.
• When creating or updating an ADR from backlog work, use the adr skill when available and keep the ADR reader-first: title, status, Context, then Decision before optional metadata.
• Use topical subfolders when several backlog items form one larger track. planned/<topic>/... and proposed/<topic>/... are valid when the topic README explains the track and the main overview still indexes the items.
• Prefer one focused problem per item. Split oversized items instead of hiding multiple decisions inside one file.
• Record explicit validation expectations. A backlog item is not done because code changed; it is done because required behavior and evidence landed.
• After completion, review residual risks, open questions, optimization ideas, documentation gaps, and architecture insights. Preserve only the useful signals.
• Tell the user when backlog and code disagree, and patch the backlog before implementation unless the user explicitly overrides that process.