feature-capture

Add Feature to Backlog

You are executing the ADD TO BACKLOG workflow.

First: Check Initialization

Read docs/features/DASHBOARD.md to verify the project is initialized.

If docs/features/ directory does NOT exist, tell the user:

"Run /feature-init first to set up the feature workflow structure."

Do NOT create the structure yourself. The init script handles this.

---

FORBIDDEN - Do Not Do These Things

• NEVER create BACKLOG.json - This is an old format. Do not use it.
• NEVER create .feature-workflow/ directory - This is an old format. Do not use it.
• NEVER write DASHBOARD.md - It's auto-generated by hooks. You will be blocked.
• NEVER write JSON files for features - Use markdown only.
• NEVER create docs/features/ yourself - Use /feature-init instead.

REQUIRED - You Must Do This

1. Verify docs/features/ exists (if not, tell user to run /feature-init)
2. Create directory: docs/features/[kebab-case-id]/
3. Write file: docs/features/[id]/idea.md with YAML frontmatter
4. That's it. The hook will auto-generate DASHBOARD.md.

First Step (Do This Now)

Read the file at path: docs/features/DASHBOARD.md

Check for duplicates and understand current features. If the file doesn't exist, that's OK - you'll create the first feature.

Target Files

• Read: docs/features/DASHBOARD.md (to check for duplicates)
• Write: docs/features/[id]/idea.md (to add new feature)

Workflow Overview

Phase	Description	Details
1	Interactive Questions	Capture essential information through focused questions
2	Validation	Check for duplicate IDs in DASHBOARD.md
3	Create Feature Directory	Write idea.md with frontmatter + problem statement
4	Git Staging	Optionally stage changes
5	Confirmation	Display summary and next steps

---

Phase 1: Interactive Questions

See: interview.md

• Ask questions using AskUserQuestion tool
• Capture type, name, problem, priority, effort, impact, areas

Phase 2: Validation

See: validation.md

• Read DASHBOARD.md to check existing features
• Generate kebab-case ID from feature name
• Check for duplicate IDs

Phase 3: Create Feature Directory

See: capture.md

• Create docs/features/[id]/idea.md with frontmatter AND content in ONE write
• After writing idea.md, regenerate the dashboard by running:

  python3 ${CLAUDE_PLUGIN_ROOT}/skills/shared/lib/run_dashboard.py <project_root>
  

• Do NOT attempt to edit DASHBOARD.md - it will be blocked

Phase 4-5: Git Staging & Confirmation

See: confirmation.md

• Optionally stage with git
• Display summary and next steps

---

File Organization

Features are stored in directories with status determined by file presence:

docs/features/
├── DASHBOARD.md              # Auto-generated, read-only for Claude
├── my-feature/
│   ├── idea.md               # Problem statement + metadata (backlog)
│   ├── plan.md               # Implementation plan (in-progress)
│   └── shipped.md            # Completion notes (completed)
└── another-feature/
    └── idea.md

Status Detection by File Presence

Files Present	Status
idea.md only	backlog
idea.md + plan.md	in-progress
idea.md + plan.md + shipped.md	completed

Key Principles:

• /feature-capture creates idea.md only (backlog status)
• /feature-plan adds plan.md (changes to in-progress)
• /feature-implement writes the code following the plan
• /feature-submit opens a draft PR for external review
• /feature-ship adds shipped.md and merges the PR (changes to completed)
• DASHBOARD.md is auto-regenerated by hooks - never edit directly

---

idea.md Format

IMPORTANT: Write idea.md with YAML frontmatter on the FIRST write. Do not write content first and add frontmatter later.

---
id: my-feature
name: Human Readable Name
type: Feature|Enhancement|Bug Fix|Tech Debt
priority: P0|P1|P2
effort: Small|Medium|Large
impact: Low|Medium|High
created: 2024-01-20
---

# My Feature Name

## Problem Statement
Description of the problem this feature solves...

## Proposed Solution
High-level approach (optional, keep brief)...

## Affected Areas
- area1
- area2

---

Integration Notes

This command is the first step in the feature lifecycle:

1. /feature-capture - Creates idea.md in backlog (YOU ARE HERE)
2. /feature-plan [id] - Adds plan.md, changes to in-progress
3. /feature-implement [id] - Writes code following the plan
4. /feature-submit [id] - Creates feature branch, opens draft PR, triggers external review
5. /feature-submit [id] --respond - Addresses review feedback (repeat as needed)
6. /feature-ship [id] - Writes shipped.md, merges PR, changes to completed

---

What Makes a Good Backlog Item?

IMPORTANT: Capture the WHAT and WHY, not the HOW.

DO Capture:

• What you need - The feature, fix, or improvement
• Why it matters - The value, pain point, or opportunity
• Who benefits - Which users or systems are affected
• Context - Any relevant background information

DO NOT Capture:

• Implementation details - Don't describe how to build it yet
• Technical designs - That's for /feature-plan
• Architecture decisions - That's for /feature-plan

Examples

Good (focuses on what/why):

"Users can't find their validation reports after running a scan. They have to search through multiple pages and often give up."

Bad (jumps to solution):

"We need to add a reports dashboard with filters and a search bar that queries the DynamoDB table."

---

Error Handling

• If docs/features/ directory doesn't exist, create it
• If duplicate ID found in DASHBOARD.md, offer to choose different name
• If DASHBOARD.md doesn't exist yet, that's OK - hook will create it

---

Quick Example

For a feature called "User Authentication", you would:

1. Create: docs/features/user-authentication/idea.md
2. With this content:

---
id: user-authentication
name: User Authentication
type: Feature
priority: P1
effort: Medium
impact: High
created: 2026-01-22
---

# User Authentication

## Problem Statement
Users cannot log in securely...

## Affected Areas
- auth
- api

3. Regenerate the dashboard:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/shared/lib/run_dashboard.py <project_root>

That's it. The dashboard regeneration ensures DASHBOARD.md is up to date.

---

Let's capture your idea!