Backlog

Create a comprehensive backlog item for work we've explored but decided not to implement now.

Instructions

Step 1: Gather Context

Ask these questions to understand what we're deferring:

1. What feature/enhancement are we deferring? (brief name)
2. Why did we explore it? (what problem does it solve)
3. Why are we deferring? (out of scope, lower priority, needs more info, etc.)
4. What did we learn? (key findings from exploration)

Step 2: Determine Category (from filename suffix)

Choose the category and encode it in the filename suffix:

• plan: Comprehensive design for new features (most common for /backlog)
• followup: Post-merge improvements and tech debt
• task-list: Collection of related items
• ideas: Ideas to explore, not yet developed into actionable plans

Use filename format: backlog/{task-name}-{category}.md

Examples:

• backlog/docs-r2-storage-plan.md
• backlog/session-cache-followups-task-list.md

Notes:

• Task name should be kebab-case ({task-name})
• Category is derived from suffix (-{category}), not frontmatter
• Status is derived from location: backlog/ = pending, backlog/done/ = done

Step 3: Create Backlog File

Create a file at backlog/{task-name}-{category}.md with this structure:

---
# Optional metadata only (omit keys you don't need)
topic: {slug-topic-name}
relates_to: {after:other-task-plan|until:other-task-plan}
priority: {1|2|3...} # 1 = highest priority
description: {short summary for UI/list views}
---

# {Feature Name}

## Problem Statement

{1-2 paragraphs explaining why this work matters and what problem it solves}

## Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| {decision point} | {what we'd choose} | {why} |

## Architecture

{ASCII diagram if helpful}

## Implementation Phases

### Phase 1: {Name}

**Files to modify:**
- `path/to/file.ts` - {what changes}

**Files to create:**
- `path/to/new-file.ts` - {purpose}

**Acceptance criteria:**
- [ ] {testable outcome}
- [ ] {testable outcome}

### Phase 2: {Name}
...

## Verification Commands

```bash
# Commands to verify the implementation works

Rollback Plan

{How to undo if things go wrong}

References

• {Related files, PRs, docs, or external resources}

### Step 4: Include Research Artifacts

Incorporate what we learned during exploration:
- Code snippets we prototyped or found
- Configuration examples
- API patterns from existing code
- External documentation links

### Step 5: Commit

Commit the backlog file with message:

chore: add {feature} to backlog

{One sentence on what this enables}

## Quality Checklist

Before finishing, verify the backlog file:

- [ ] Has enough context that a fresh session can understand without the original conversation
- [ ] Includes specific file paths (with line numbers when relevant)
- [ ] Has verification commands or acceptance criteria
- [ ] References related code patterns in the codebase
- [ ] Uses minimal optional metadata only (`topic`, `relates_to`, `priority`, `description`) and omits unused keys
- [ ] Uses kebab-case filename suffix format: `{task-name}-{category}.md`

## List Backlog Items

To see all backlog items, run:

```bash
~/.claude/skills/backlog/scripts/status.sh

Grooming

Detect stale or likely-completed backlog items that were never moved to done/.

~/.claude/skills/backlog/scripts/groom.sh [path/to/backlog]

The script cross-references pending items against git history (title/keyword matches and in-file references) and the filesystem (files that were supposed to be created). It flags items that look done so you can review and close them.

See references/grooming.md for the full grooming workflow and checklist.

Example Usage

User: /backlog
Claude: I'll help capture the work we explored for future implementation.

What feature/enhancement are we deferring?
> R2 storage for docs assets

Why did we explore it?
> Docs screenshots are gitignored, wanted persistent storage without git bloat

Why are we deferring?
> Works fine locally for now, R2 adds complexity we don't need yet

What did we learn?
> R2 bindings in wrangler.jsonc, Worker route pattern, wrangler CLI for uploads

[Creates backlog/docs-r2-storage-plan.md with full implementation plan]

Setting Up backlog/ Directory

See references/agents-schema.md for directory setup, naming conventions, and metadata conventions.

References

• references/agents-schema.md — Categories, lifecycle, filename conventions, directory setup
• references/grooming.md — Backlog maintenance workflow and checklist
• references/README.md — Background, design philosophy, and related projects