doc-feature

/doc-feature — Feature Documentation Generator

Position in Ecosystem

product-discovery  →  requirements docs  →  [dev phase]  →  doc-feature
    (JTBD, RICE)      (PRD, contracts)      (code)           (feature doc)

doc-feature fills the gap between product specs and code-level docs. Routing decisions (where each piece of information belongs) come from the doc-routing skill.

Usage

/doc-feature [Feature Name]
/doc-feature Reports Phase 2
/doc-feature Search Module

Output Location

docs/features/{kebab-case-name}.md

---

⛔ MANDATORY RULES (NON-NEGOTIABLE)

1. NEVER skip Phase 2 (PRESENT & ASK) — always show what you understood and ask clarifying questions
2. NEVER generate the doc without the user's answer or an explicit "skip" — wait for a response
3. ALWAYS read the actual source code — don't just list files, READ the implementation
4. ALWAYS check project memory (e.g. .claude/memory/MEMORY.md or your auto-memory file) — it contains API gotchas, decisions, and patterns already documented
5. ALWAYS fill ALL template sections — use "N/A — [reason]" for empty sections, NEVER omit them
6. ALWAYS include real API response shapes — not placeholders, actual { field: type } from the type definitions
7. ALWAYS trace data flow through code — follow imports: page/entry point → hook/service → API call → type → response
8. ALWAYS capture the business WHY — not just "what it does" but "why the user needs this"

---

Process (3 Phases)

Phase 1: GATHER — Collect Maximum Context (automatic, thorough)

This phase MUST be thorough. Spend time reading code, not just listing files.

1. Detect scope: git diff --name-only main..HEAD → group by directory

   • Count: new files, modified files, deleted files
   • Identify: which module/feature area is affected

2. Read existing knowledge (MUST read all that exist in your project):

   • Project memory file — existing notes about this feature (API gotchas, decisions, patterns)
   • docs/requirements/ — related requirements, business rules, user stories
   • docs/GLOSSARY.md — terminology (metric names, domain types, role names)
   • .claude/research/ — research docs relevant to this feature
   • docs/requirements/product/PRD.md — product strategy context
   • Your issue tracker — task context if the branch/commit mentions an issue ID

3. Analyze code IN DEPTH (MUST actually read the files, not just grep). Layer names below are examples from a typical frontend stack — map to your architecture:

   • Hooks/services: Read each new/modified one. Trace: what API calls? What state? What transforms?
   • API layer: Read the API client code for relevant endpoints. Note:
     • Request params (what goes in)
     • Response shape (what comes back — EXACT type, not placeholder)
     • Any gotchas: numeric precision (e.g. BigInt → string), dict vs array responses, nested response wrappers, pagination style
   • Types: Read the shared type definitions for relevant types
   • Components/UI: Read the entry point and key components. Note: what the user sees, what interactions
   • Mappers/transformers: If present, read them — they reveal data transformations

4. Detect gaps: What's NOT documented that should be?

   • New API patterns not in project memory
   • New terms not in the glossary
   • New use cases not in requirements
   • Edge cases discovered in code (null checks, fallbacks, error states)

Phase 2: PRESENT & ASK — Show Understanding + Ask Questions (in chat)

This is a MANDATORY checkpoint. You MUST present what you learned and ask questions.

Output a structured summary to chat:

📋 FEATURE DOCUMENTATION: {Feature Name}

📊 SCOPE ({N} files changed, {M} new):
  • Hooks/services: {list}
  • API: {endpoints used}
  • Components: {list}
  • Types: {list}

✅ WHAT I UNDERSTAND:
  • Goal: [1 sentence — what problem this solves for the user]
  • User: [who uses this and in what scenario]
  • Data flow: [Source] → [Transform] → [UI Component]
  • Key behavior: [what the user sees/does]
  • API gotchas found: [list any response format surprises]

📝 WHAT I WILL DOCUMENT:
  • Business context: [problem, users, use cases]
  • Architecture: [data flow, endpoints, key files]
  • Decisions: [N key decisions found in code/memory]
  • Edge cases: [N edge cases found]
  • New terms: [terms to add to the glossary]

🔄 REQUIREMENTS SYNC:
  In requirements:  [list existing use cases found in docs/requirements/]
  Missing from requirements:
    • [UC: scenario discovered in code but not in requirements]
  → These will be added to docs/requirements/ in Phase 3

❓ WHAT NEEDS CLARIFICATION:
  1. [Specific question about business context]
  2. [Specific question about user behavior]
  3. [Specific question about edge case handling]

Answer the questions — I'll capture answers and generate documentation.
Or "skip" — I'll create the doc with [NEEDS_CLARIFICATION] markers where answers are needed.

⛔ STOP HERE. WAIT for user response.

• If the user answers → incorporate answers into Phase 3
• If the user says "skip" → generate the doc but mark unclear sections with [NEEDS_CLARIFICATION: original question]
• If the user corrects your understanding → update it before generating
• NEVER proceed to Phase 3 without a user response

Phase 3: GENERATE — Create/Update Documentation (after answers)

Bidirectional flow — discoveries flow not only into the feature doc, but also BACK to requirements.

Execute these steps IN ORDER:

Step 1: Create the feature doc

Create docs/features/{kebab-case-name}.md using the template below. Fill ALL sections with real data from Phase 1 analysis + Phase 2 answers.

Quality requirements for each section:

• Why > Problem: 2-3 sentences explaining the USER's pain, not the technical implementation
• Why > Users & Use Cases: Real scenarios with role names from the glossary. "The analyst wants..." not "user can..."
• Why > Success Criteria: Measurable items, not vague "works correctly"
• What > Data Flow: Actual component/hook/API names, not abstractions
• What > API Endpoints: REAL response shapes from types, include a gotchas column
• What > Key Files: Every file a developer needs to understand to modify this feature
• How > Key Decisions: Include WHY (business/technical reason) and WHAT WAS REJECTED
• How > Domain Terms: Link to the glossary, explain how each term applies to this feature
• Limitations: Be honest — what doesn't work, what's hacky, what needs improvement

Step 2: Update requirements (MANDATORY check)

⛔ This step is NOT optional. Requirements must stay in sync with implementation reality.

1. Read docs/requirements/ — find the file(s) related to this feature
2. Compare use cases in requirements vs what was actually implemented:
   • New user scenarios discovered during development
   • New filter/parameter combinations users can apply
   • New data views or interaction patterns
   • Business rules that became clear only during implementation
3. Add missing use cases to the appropriate requirements file in the format:

### UC-{NNN}: {Scenario name}

**Actor:** {Role from the glossary}
**Precondition:** {What must be set up}
**Flow:**

1. {Step}
2. {Step}
   **Result:** {What the user gets}
   **Source:** Discovered during {feature name} implementation (YYYY-MM-DD)

4. Report in the Phase 3 summary:
   • If use cases were added: Updated: docs/requirements/... (+N use cases)
   • If requirements were already complete: Verified: docs/requirements/... (no gaps found)

Why this matters: Requirements are the SSOT for product behavior. If they don't reflect what was actually built, future sessions will lack business context. Feature docs capture HOW (architecture), requirements capture WHAT (user scenarios). Both must be current.

Step 3: Update the glossary

If new domain terms appeared (widget types, metric names, filter categories):

• Add them to docs/GLOSSARY.md with clear definitions

Step 4: Add doc-comment @example to API functions

For each API endpoint used by the feature, add an @example to the function in your API layer (TSDoc/JSDoc/docstring — whatever your stack uses):

/**
 * @example
 * // Response shape:
 * // { orders: [{ order_id: "9007199254740993", status: "shipped", total: 129.5 }] }
 * // Gotcha: order_id exceeds Number.MAX_SAFE_INTEGER — keep it as a string
 */

Step 5: Update project memory

Add a reference to the new feature doc in your project memory file.

Step 6: Output summary

📋 DOCUMENTATION COMPLETE:
  Created: docs/features/{name}.md
  Updated: docs/requirements/... (+N use cases)      [or: no changes needed]
  Updated: docs/GLOSSARY.md (+N terms)                [or: no new terms]
  Updated: <api layer> (N @example added)             [or: examples already present]
  Updated: <project memory> (+1 reference)

---

Document Template

# {Feature Name}

**Date:** YYYY-MM-DD
**Status:** Active | Draft | Deprecated
**Issue:** [your tracker ID, e.g. TICKET-123]
**PRD Section:** [link to PRD section if it exists]

## Why (Business Context)

### Problem

[What BUSINESS problem this solves — from the user's perspective, not the developer's.
Example: "The analyst spends 2+ hours manually collecting numbers scattered across
several source systems. They need automated monitoring with trend visualization."]

### Users & Use Cases

- **[Role from the glossary]:** [Concrete scenario with actions]
  - Precondition: [what must be configured]
  - Action: [what the user does]
  - Result: [what they get]

### Success Criteria

- [ ] [Measurable criterion — e.g. "Data loads in < 3 seconds for 1000 records"]
- [ ] [User-facing criterion — e.g. "Filtering narrows the table in real time"]

## What (Architecture)

### Data Flow

```
[Concrete names: component → hook → API endpoint → response type]
Example:
OrdersPage → useOrdersData() → getOrders() → BackendOrder[]
→ getOrderStats() → BackendOrderStats
```

### API Endpoints Used

| Endpoint   | Method | Purpose        | Response Format                          | Gotchas                                                |
| ---------- | ------ | -------------- | ---------------------------------------- | ------------------------------------------------------ |
| /v1/orders | GET    | Paginated list | `{ data: [...], meta: { page, total } }` | `page` is 1-based; `per_page` > 100 is silently capped |

### Key Files

| File                   | Role                        | Lines of interest             |
| ---------------------- | --------------------------- | ----------------------------- |
| <hooks dir>/use-xxx.ts | Data fetching + aggregation | L45: batch logic, L120: merge |
| <api layer>            | API calls                   | L300: endpoint definition     |

## How (Implementation Details)

### Key Decisions

- **Decision:** [What was decided]
  **Why:** [Business or technical reason — not "because it's simpler", be specific]
  **Alternative considered:** [What was considered and why it was rejected]
  **Date:** YYYY-MM-DD

### Domain Terms Used

- **[Term]** (see GLOSSARY.md): [how it applies to this feature]

## Limitations & Edge Cases

| Case                 | Current Behavior   | Workaround / Future Plan |
| -------------------- | ------------------ | ------------------------ |
| [Concrete edge case] | [What happens now] | [What's planned]         |
| [API error]          | [How it's handled] | [What could be improved] |

## Related

- Requirements: `docs/requirements/...`
- Research: `.claude/research/...`
- ADR: `docs/architecture/decisions/ADR-NNN`
- Memory: <project memory file> → [section name]

---

Rules Summary

1. GATHER thoroughly — read actual code, not just file names
2. PRESENT and WAIT — never skip the user checkpoint
3. Fill ALL sections — "N/A — [reason]" for empty, never omit
4. Real data, not placeholders — actual types, actual response shapes, actual file paths with line numbers
5. Business WHY first — every feature exists to solve a user problem
6. Bidirectional updates — feature discoveries flow back to requirements + glossary
7. API gotchas are gold — dict vs array, numeric precision, pagination style — ALWAYS document
8. Link to project memory — check existing knowledge, add new references
9. Decisions need WHY + REJECTED — "we chose X because Y, considered Z but rejected because W"
10. Honest limitations — what doesn't work, what's a hack, what needs future work