feature-capture

What this skill does

# 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.

**Multi-repo workspace?** If the root has a `.feature-workspace.yml`, decide scope first: one member → `cd <member>` and capture there; workspace-only → capture here; touches 2+ members → capture a `type: Epic` here with one `repo:id` child per member. See [../shared/workspace.md](../shared/workspace.md).

---

## 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](interview.md)
- Ask questions using AskUserQuestion tool
- Capture type, name, problem, priority, effort, impact, areas

### Phase 2: Validation
**See**: [validation.md](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](capture.md)
- Create `docs/features/[id]/idea.md` with frontmatter AND content in ONE write
- **After writing idea.md, regenerate the dashboard** by running:
  ```bash
  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](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-review-plan` opens a draft PR for external plan review
- `/feature-review-impl` submits implementation for external code 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.

```markdown
---
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-review-plan [id]`** - Creates feature branch, opens draft PR, submits plan for external review
4. **`/feature-implement [id]`** - Writes code following the approved plan
5. **`/feature-review-impl [id]`** - Submits implementation for external code review
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:

```markdown
---
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:
```bash
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!**