# Backlog > Capture explored work as a backlog item for future implementation. Use when you've explored an enhancement, alternative approach, or feature but decided to defer it. Creates comprehensive plan files in backlog/ directory with enough context for a future session to execute efficiently. Use when this capability is needed. - Skill: `tomevault-io/backlog-3` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/backlog-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/backlog-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/backlog-3 --- # 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: ```markdown --- # 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/`. ```bash ~/.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 --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/fairchild) — claim your Tome and manage your conversions.