# Feature Slicing Strategy

This doc clarifies how we reconcile two goals that can conflict if handled naively:

1. Capture human intent and constraints once (discovery / delivery / design).
2. Ship small, low-risk PRs (vertical slices) with fast feedback.

## Two Levels: Capability vs. Slice

We treat "feature" in two different ways depending on which artifact we are talking about.

### 1) Capability Docs (Shared Context)

These artifacts capture durable intent/constraints and can (and often should) be shared across multiple slices:

- `docs/discovery/<capability>.json` and `docs/discovery/<capability>.md`
  - Outcome, opportunity, PR/FAQ, taste (delights/frustrations/feeling), scope, unknowns
  - Source of truth for "taste" when present

- `docs/delivery-specs/<capability>.md` (optional)
  - Functional requirements + non-functional requirements
  - Acceptance criteria and rollout notes
  - Can cover a capability that will be delivered across multiple slices

- `docs/design-docs/<decision>.md` (optional)
  - Architecture decisions (ADR-style) that may apply to many slices

### 2) Feature Slices (Execution Units)

These are the units we track in `specs/FEATURES.json` and implement as small PRs:

- Each slice should be independently valuable or a necessary, verifiable step toward value.
- Each slice should have its own implementation + verification specs.
- Each slice can reference the same capability docs (discovery/delivery/design) via `feature.docs.*`.

Key rule:
- Multiple slices may share the same `docs.discovery_json` / `docs.delivery_spec` / `docs.design_doc`.
- Slices should NOT share the same `specs/F###-IMPLEMENTATION_SPEC.md`.

## Practical Heuristics

- Prefer a single discovery doc per capability, then slice delivery into multiple `FEATURES.json` entries.
- Keep implementation specs bounded (max ~7-10 steps). If the plan is bigger, split into more slices.
- If two slices have different success criteria / taste / outcome, they should not share the same discovery JSON.

## What This Buys Us

- No repeated interviews: taste is captured once and reused.
- Small PRs: execution stays incremental and testable.
- Lower drift: shared intent stays consistent, slice specs stay bounded.