# Feature Documentation — the LLD (docs/features/{feature}.md)

Truth document. Use for: every feature in `docs/features/`. The feature doc is the feature's **LLD (low-level design)**: the same file persists from design (Status: Draft, written in LLD Mode) through implementation to live reference (Status: Active). Sections fill in as the feature matures — no template swap. The body always describes the feature as it currently is; the journey lives in the linked plan and changelog entries.

**Required vs optional.** Required in every feature doc: the frontmatter, **Goal**, and **Background** — plus **Files** once implementation exists (a Draft for unbuilt code has no real paths to list) and **Current Behavior** once research or implementation exists (at Draft it's the pre-feature baseline; at Active it's how the feature works today). Every other section is optional: include it only when the feature has something real to put in it (no Redux → no Redux section; no risks worth naming → no Risks section). A **minimal form** is sanctioned for small features: frontmatter + Goal + a short how-it-works section + Files. A two-screen doc that is accurate beats a full-template doc with empty sections.

The four research-derived sections (**Affected Modules**, **Conventions to Follow**, **Current Behavior**, **Ownership Conflicts**) map 1:1 to the `lld-mode` agent's return shape. The orchestrator drops its findings into those slots without restructuring.

```yaml
---
owns: ["src/feature/**", "src/other/file.ts"]   # required — code-path globs this doc owns (the only ownership key)
module: billing                                  # optional — single bounded-context label; omit if cross-cutting
keywords: [invoice, pdf]                         # required — discovery terms
status: active                                   # required — active | draft | deprecated
applies: [docs/architecture/common/security.md]  # optional — architecture docs this surface is BOUND by (obligation, not a bibliography); omit when none
last-reviewed: YYYY-MM-DD                        # optional tooling key — stamped on substantive review/update; the maintenance agent ranks audit priority by it (metadata, never narrated in the body)
type: feature                                    # required tooling key — genre stamp (generator-written or authored; enum = the template names), read by tooling (UI grouping, protected-file mapping); preserve on edits, never narrate
---
```

> Declare the code paths it owns in its `owns:` frontmatter — projected at Draft, confirmed against real code at Active.

```
# {Feature Name}

<!-- Lifecycle lives in the frontmatter `status:` key (active | draft | deprecated) — the single source of truth. Don't restate it in the body. -->
**Plan:** [history/plans/YYYY-MM-DD-feature-name.md](../history/plans/YYYY-MM-DD-feature-name.md)   <!-- added once a plan exists -->

## Goal

One sentence. What this feature accomplishes, in user-facing terms.

## Goals & Non-Goals

**In scope**
- Bullet 1
- Bullet 2

**Out of scope**
- Bullet 1

## Background

Why this feature exists. The user need, the business trigger, the constraint that pushed it above the line. One paragraph.

(For Product-level work, also include: problem statement, key hypotheses, open questions.)

## Approach

High-level shape of the solution. ASCII diagram if it helps. Implementation specifics belong in the plan.

## Affected Modules

(From lld-mode research) Files, routes, components, slices this feature involves. Group by module.

| Module | Path | Role in this feature |
|--------|------|----------------------|

## Conventions to Follow

(From lld-mode research) Naming patterns, structural patterns, doc-fit heuristics confirmed for the area being touched. Cite the source file(s) where the convention is established.

## Current Behavior

(From lld-mode research) How the relevant part of the system works *today*, before this feature lands. Without this baseline the design intent is hard to evaluate.

## Ownership Conflicts

(From lld-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.

| Conflicting doc | Overlapping path(s) | Resolution |
|-----------------|---------------------|------------|

## Architecture

[ASCII diagram. Fill once implementation lands. See style-guide.md for box-drawing patterns.]

## Key Functions

### `functionName(param1, param2)`
**Goal:** What it accomplishes
**Input:**
- `param1` (type) - Description
- `param2` (type) - Description
**Output:** Return type and shape
**Side Effects:** DB writes, API calls, state updates

### `hookName(config)`
**Goal:** What it provides
**Returns:** `{ data, loading, error }`
**Triggers:** On mount, on change, manual

## State

**Frontend (at persistence):**
{
  "data": [],
  "changes": { "added": [], "updated": [], "removed": [] }
  // "cache": {}  // UNUSED: dead key; kept so old persisted state rehydrates
}

**Storage:** localStorage `app_state`

**Backend:**
export const resources = pgTable('resources', {
  id: text('id').primaryKey(),
  data: jsonb('data'),
  // oldField: text('old_field'),  // UNUSED: dead column; nothing reads it
});

**API Shape:**
{ "status": 1, "data": {...} }

## Redux (if applicable)

**Slice:** `sliceName`

**Actions:**
- `setData(payload)` - Replace all data
- `upsertItem(item)` - Add or update single item

**Selectors:**
- `selectAll(state)` → `Array<Item>`
- `selectById(state, id)` → `Item | undefined`

## Files

- `src/path/to/main.js` - Core logic
- `src/path/to/hooks.js` - React hooks

## Open Questions

- Question — who decides, by when
- (Resolved questions: fold the resolution into Background.)

## Risks

- Risk — likelihood / impact / mitigation
```

### Section evolution

Sections fill in across the feature's lifecycle. No template swap — they accumulate in place.

| When | Sections written | Source |
| --- | --- | --- |
| Status: Draft (design) | Goal, Goals & Non-Goals, Background, Approach, Open Questions, Risks | User interview |
| Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | lld-mode agent |
| Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; `owns:` globs confirmed against real code | Main agent (from actual code) |

Resolved Open Questions can be summarized into Background; unresolved ones stay visible.