backlog

Backlog deferred task pool

Shared constraints SSOT:../shared/constraints.md

This skill follows the shared constraints SSOT: gating markers, yaml-summary-v1, Task delegation, user confirmation, Recovery format, read-only / dry-run, FUTURE tri-state, realign / spec_version see skills/shared/constraints.md. This file only describes backlog-private rules.

Positioning

backlog is keel'sdeferred task pool: records items that already have a source ID, are temporarily not entering the current development loop, but will need to be traced in the future.

It only maintains docs/devdocs/backlog.md this centralized index, does not create a new numbering system, and does not modify the original numbered files. Entries use source_id + entry_no as local anchors, allowing multiple deferred items to be produced from the same source.

Boundaries:

Distinct from PO grooming: no product prioritization, value review, or owner assignment.
Distinct from Jira / Linear: no maintaining boards, swimlanes, or Sprint capacity.
Distinct from 04-dev-tasks.md: does not represent currently scheduled tasks, only deferred and traceable ones.

Entry point and trigger words

CLI entry point

/backlog --park <source_id>       # 写入 parked 条目
/backlog --reactivate <source_id> # parked → reactivated
/backlog --close <source_id>      # parked → closed
/backlog --supersede <source_id>  # parked → superseded（可选）
/backlog --list[=status]          # 列出条目，默认全部
/backlog --init                   # 初始化 docs/devdocs/backlog.md（使用 templates/backlog-template.md）

Orchestration entry point

/pipeline backlog routes to this skill, passing in:

skill: backlog
mode: read | dry-run | apply
inputs:
  command: park | reactivate | close | supersede | list
  source_id: F-01
expected_output: yaml-summary-v1

Trigger words

Triggered when explicitly managing deferred items:暂缓、任务暂缓、先记下、暂时不做、回到 backlog、backlog 管理、backlog entry、park、reactivate。

Trigger word conflict handling:

User intent	Route
"Note this P3 down for now / do not do it for now / put it in backlog"	`backlog`
"List the backlog / reactivate F-01's deferred item"	`backlog`

backlog.md Schema

docs/devdocs/backlog.md is the only SSOT. Status is maintained only in this file; the original F/US/AC/T/INS/BUG/FR/NFR file does not add status fields.

File frontmatter

---
generated_by: backlog
spec_version: backlog.v2
generated_at: 2026-05-19T10:30:00+08:00
updated_at: 2026-05-19T10:30:00+08:00
---

File structure

## Index: grouped by status, including parked / reactivated / closed / superseded。
## Entries: one block per entry, title recommended ### F-01#1 - <短标题>。
## Change Log: optional, records status transition time, operator skill, and reason.

Entry frontmatter

Each backlog item must contain a YAML frontmatter block.

source_id: F-01
entry_no: 1
status: parked
created_at: 2026-05-19
created_by_skill: verify
note: "P3 边界 case 待优化"
related_ids: [AC-05, AC-07]

Required fields:

Field	Rule
`source_id`	Reuse an existing ID:`F-XX` / `US-XX` / `AC-XX` / `T-XX` / `INS-XX` / `BUG-XX` / `FR-XX` / `NFR-XX` / `M-XXX`; forbidden `B-XXX`
`source_id`（`M-XXX` exception)	`M-XXX` isthe only one allowed to carry sources that "do not yet have any ID": new requirements that emerge during development are attached to "which segment it emerged from." ⛔ This is the only exception and must not be generalized to other prefixes
`entry_no`	Under the same `source_id` , increments from 1
`status`	`parked` / `reactivated` / `closed` / `superseded`
`created_at`	ISO date, written as the entry creation date
`created_by_skill`	Source skill that produced it, such as `verify`

Status conditional fields:

status	Required fields	Meaning
`reactivated`	`target_flow` / `target_id`	Already transferred into the target process, such as `dev-tasks` + `T-08`
`closed`	`reason`	Reason it is no longer handled
`superseded`	`superseded_by`	Which source or entry replaced it

Optional fields:note、related_ids、created_from、updated_at、updated_by_skill、decision_log。

State machine

stateDiagram-v2
  [*] --> parked
  parked --> reactivated: target_flow + target_id
  parked --> closed: reason
  parked --> superseded: superseded_by
  reactivated --> [*]
  closed --> [*]
  superseded --> [*]

Rules:

The initial state can only be parked。
reactivated indicates it has been consumed into the target process, not equal to done.
closed indicates it is explicitly no longer handled, and must explain reason。
superseded is an optional terminal state, used to record replacement by another ID or entry.
Forbidden done status; completion should be recorded by the target process itself.

Production-side integration

When other skills produce “deferred but non-blocking” items, preferentially declare them to the orchestration layer via yaml-summary-v1 , and the orchestration layer then calls backlog --park to write. Reason: maintain the single responsibility of the source skill and avoid multiple skills directly modifying the same SSOT, causing concurrency and schema drift.

Candidate interfaces:

Option	Behavior	Trade-offs
A Recommended	The source skill outputs candidates in `summary.details.backlog_candidates` ; the pipeline or the user explicitly calls `backlog --park` to write	Clear responsibilities, convenient for dry-run, avoids double writing
B Optional	The source skill directly calls the `backlog --park` sub-Agent	More automated, but requires strict passing of allowed paths and write locks

Minimal structure of a candidate item:

summary:
  details:
    backlog_candidates:
      - source_id: AC-05
        note: "P3 边界 case 待优化"
        created_by_skill: verify
        related_ids: [F-01, AC-07]

Trigger scenarios:

Source skill	Pool entry scenario
`dev-tasks`	Task deferred, dependencies not ready, beyond the current iteration but needs tracking
`verify`	P3 issues automatically enter the pool; P1/P2 should not be directly parked and need to be handled by verify routing
`insights`	Cross-task optimization opportunity, confirmed but not yet converted to a requirement
`prd`	FR/NFR shelved, not yet imported into keel or awaiting business confirmation
`dev-workflow`	Within a milestone segment / at the end of a segmentNew ideas that arise (`source_id` = current `M-XXX`): the user says them in natural language, and a sub-agent investigates and writes them. Those that can be attached to an existing `F`/`AC` enter the pool under the corresponding number; ⛔ do not attach to M

Consumption-side conversion path

When reactivating, route according to the source_id type:

source_id	target_flow
`F-XX` / `US-XX` / `AC-XX`	`requirements`
`T-XX`	`dev-tasks`
`INS-XX`	`insights`
`BUG-XX`	`bugfix`
`FR-XX` / `NFR-XX`	`prd`
`M-XXX`	Per itemformdetermined, ⛔ no fixed destination: new requirement → `requirements`; defect → `bugfix`; already clear enough to be scheduled directly → `dev-tasks`

reactivate must be written back to target_flow and target_id. If the target process has not yet generated a number, keep parked and return partial, prompting to run the target skill first.

Gating

⛔ Do not continue:--reactivate lacks target_flow or target_id. Recovery method: first run the target process to generate the target number, or migrate the state only after the user explicitly provides target_flow + target_id .

⛔ Do not continue:--close lacks reason. Recovery method: the user supplements the closure reason; before it is provided, keep parked。

⛔ Do not continue: attempt to create B-XXX or another new numbering system. Recovery method: switch to an existing source_id, or first generate a valid source number through the corresponding skill.

⚠️ Must confirm: entering the pool again when the same source_id already has an active parked item. Recovery method: the user confirms whether to append a new entry_no, or update the existing item; if there is no confirmation, do not write. M-XXX Source exception: by defaultappenda new entry_no, ⛔ do not ask. Reason — multiple ideas arising within a milestone segment is normal; asking about each one turns “note it down” into an interruption, and interruption is exactly what this mechanism aims to eliminate. Other source behaviors remain unchanged.

Traceability

Primary anchor:source_id + entry_no, e.g. F-01#1。
related_ids is used to record auxiliary associations without changing the primary anchor.
Change Log records state transitions, retaining from_status / to_status / changed_at / changed_by_skill。

What it does not do

Does not maintain owners, priority boards, swimlanes, or Sprint capacity.
Does not replace Jira / Linear / GitHub Issues.
Does not add B-XXX or any backlog-specific numbering.
Does not modify the original F/US/AC/T/INS/BUG/FR/NFR file.
Does not interpret reactivated as completed, nor provide done status.
Does not automatically change pipeline / dev-tasks / verify / insights / prd, only declares the subsequent integration contract.

Templates and Realign

Initialization template:templates/backlog-template.md
Structural evolution:references/realign.md

backlog.v2 is the current spec version. When modifying required template sections, fields, status enums, or hard validation rules, the current version and Migration Matrix of references/realign.md must be updated accordingly.

Sub-Agent summary format

yaml-summary-v1 envelope: see skills/shared/constraints.md § 2

summary.details private field：

Field	Value range / example
`mode`	`park` / `reactivate` / `close` / `supersede` / `list` / `init` / `realign`
`backlog_path`	`docs/devdocs/backlog.md`
`entries_added` / `entries_updated`	Number of entries added or updated this time
`status_counts`	`{parked: 3, reactivated: 1, closed: 2, superseded: 0}`
`affected_entries`	`["F-01#1", "AC-05#2"]`
`target_flow` / `target_id`	Written to the target when reactivated
`pending_confirmation`	Same-source active parked conflict awaiting confirmation

Artifact field：output_files lists only docs/devdocs/backlog.md；new_ids.backlog_entries records local anchors (e.g. F-01#1), does not record B-XXX。