Defer an out-of-scope finding to the backlog. Use when a bug, tech debt, idea, or risk is discovered but not appropriate to solve now.
${CLAUDE_SKILL_DIR}/scripts/defer.py
All commands output JSON. The script bootstraps .backlog/ automatically on first use.
Detect where /defer was called from:
.protocols/0001-feature/03-api.md)code-reviewFrom $ARGUMENTS and conversation context, determine:
| Field | Required | How to get |
|---|---|---|
| title | yes | From $ARGUMENTS, or ask |
| type | yes | bug, debt, idea, or risk — infer from context, confirm if ambiguous |
| priority | yes | p0–p3 — infer from severity, confirm if ambiguous |
| area | no | Freeform domain tag (e.g. batch, map, bot, auth) — infer from context |
| effort | no | xs/s/m/l/xl — usually filled later during triage, not at creation |
| origin | no | Auto-detected from step 1 |
| description | yes | Self-contained paragraph answering: (1) what's wrong, (2) why it matters, (3) why deferred, (4) how to fix. Must be understandable without reading the code |
python ${CLAUDE_SKILL_DIR}/scripts/defer.py create \
--title "<title>" --type <type> --priority <priority> \
--area "<area>" --effort <effort> \
--origin "<origin>" --description "<description>"
Multiple items: When creating several items at once, use parallel Bash tool calls (one per item) — do NOT chain them with &&.
Returns JSON:
{"action": "create", "slug": "auth-coupling", "path": ".backlog/items/auth-coupling.md", ...}
If inside a protocol step — insert a [DEFER] line into the step's Findings:
python ${CLAUDE_SKILL_DIR}/scripts/defer.py link-finding \
<step-file-path> <slug> "<title>"
If during code review — include the returned path in the triage table Rationale column. Do not run link-finding.
If standalone — no linking needed.
Tell the user what was created:
path field# List active items (with optional filters)
python ${CLAUDE_SKILL_DIR}/scripts/defer.py list --status open
python ${CLAUDE_SKILL_DIR}/scripts/defer.py list --type bug --area bot
python ${CLAUDE_SKILL_DIR}/scripts/defer.py list --priority p1
# Generate a view (saved dashboard grouped by a field)
python ${CLAUDE_SKILL_DIR}/scripts/defer.py view --group-by priority -o .backlog/views/by-priority.md
python ${CLAUDE_SKILL_DIR}/scripts/defer.py view --group-by area -o .backlog/views/by-area.md
python ${CLAUDE_SKILL_DIR}/scripts/defer.py view --group-by type -o .backlog/views/by-type.md
# Filtered view (e.g. only batch items grouped by type)
python ${CLAUDE_SKILL_DIR}/scripts/defer.py view --group-by type --area batch
# Close and archive a resolved item
python ${CLAUDE_SKILL_DIR}/scripts/defer.py close <slug>
# Bootstrap .backlog/ without creating an item
python ${CLAUDE_SKILL_DIR}/scripts/defer.py bootstrap