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