Feature Design Docs

Core Rule

Use doc/features/<feature>/design.md as the default feature design entry point. A feature design doc is authoritative for one coherent product feature's user-visible behavior, UI contract, visible state, disabled and error states, and product-level acceptance rules.

Feature docs may name the systems or packages that implement the feature, but they must not define internal cross-package architecture, storage models, provider/backend mechanics, lifecycle state machines, or package-private implementation details.

Feature docs outrank system and package docs for user-visible behavior. System and package docs must satisfy feature contracts without duplicating them.

Required Structure

Use this design structure:

1. First mandatory section: # Goals.
2. Optional section under goals: ## Non-goals.
3. Second mandatory section: # Decisions.
4. Third mandatory section: # Engineering Rigor.

State goals as what product problem the feature solves, not how. Put only target-state decisions under # Decisions. Exclude implementation phases, migration steps, status notes, current-state excuses, process reminders, and historical commentary.

In # Engineering Rigor, select the feature scope's versioned rigor profile and modifiers using
the engineering-rigor skill. Put user-visible consequence, recovery, trust, and exposure
requirements here when they cannot be expressed by catalog identifiers. Do not duplicate generic
profile definitions or package-local implementation constraints.

Feature Scope

Before writing or updating a feature doc:

1. Read project instructions and any project-declared documentation authority.
2. Read relevant system and package docs when implementation ownership affects feature wording.
3. Identify the feature's user-visible workflows and non-goals.
4. Identify UI surfaces, commands, visible states, disabled states, recovery states, and user-facing failure behavior.
5. Separate feature-owned behavior from system architecture and package-owned reusable boundaries.

Use feature docs for product behavior that cannot honestly be owned by one package.

Design Content

Capture the user-visible contracts implementation must satisfy:

• User workflows, visible outcomes, and disabled/error states.
• UI surfaces, interaction states, empty states, and recovery states.
• User-facing commands, menus, actions, and permissions.
• Visible ordering, identity, provenance, and user-intent preservation.
• User-visible async, cancellation, retry, rollback, and partial-failure behavior.
• Accessibility, localization, and visible performance expectations.
• Systems and packages that implement the feature, named without defining their internal contracts.

Put internal dataflow, storage, schema, protocol, provider, cache, lifecycle, and cross-package responsibility details in system docs.

Supplemental Files

Create supplemental feature files only when they reduce entry-point size or improve review quality. Common supplements include UI details, user-flow details, visible state details, mockups, and decision appendices.

When a supplement redistributes normative contracts or an existing feature authority needs
decomposition, apply the project-doc-authority skill's authority-decomposition workflow before
editing. It governs review signals, co-reading groups, entry-point routing, contract preservation,
and selective-read validation. Adding a purely illustrative file without redistributing authority
does not require that workflow.

When adding a supplemental file:

• Link it from doc/features/<feature>/design.md.
• State whether it is normative, illustrative, or historical.
• Keep normative decisions consistent with the feature entry point and higher authority.
• Keep normative rigor details consistent with the profile and modifiers named in the feature entry
  point.
• Do not let mockups override written behavior unless the feature entry point explicitly says they do.