docs/FEATURE_SLICING.md

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.