Skip to main content

ADR-0008 — Slice-by-slice build

  • Status: Accepted
  • Date: 2026-04-22
  • Decision-makers: Tom Anderson

Context​

Two ways to build a multi-feature product:

Horizontal: build the data layer for everything, then the API layer for everything, then the UI for everything. Common in waterfall and in startups that believe in "platform first."

Vertical: pick one feature (a slice), build it end-to-end (schema + API + UI + tests + docs), ship it, pick the next slice. Common in Agile and in single-developer products.

For Helm specifically, horizontal would mean: design all 75 tables, then build all ~150 endpoints, then build all 10 screens. We'd see no production value for many months.

Vertical means: build slice 2 (Customers) end-to-end, then slice 4 (Service tickets) end-to-end, etc. Each slice ships a deployable, useful, demoable piece. The shop sees value at each release.

Decision​

Build Helm slice by slice. The 11 slices (slice overview) are sequenced by dependency and business value, not by layer. Each slice ships:

  • Schema migration files
  • Backend endpoints
  • Frontend screens
  • Tests
  • Documentation in this bible
  • Migration scripts for AIM data (when applicable)

Within a slice, "done" means the slice's user can use it in production. Not "data layer for the slice complete" or "API for the slice complete" — fully working.

Consequences​

Positive:

  • The shop sees value continuously, not in one big bang at the end
  • Mistakes are caught at slice end, not at the integration phase
  • Re-prioritization between slices is easy; we're never committed to building something we don't need yet
  • One slice's failure doesn't doom the whole build
  • The dev's morale stays up — shipping is the reward

Negative:

  • Cross-cutting concerns (auth, audit, observability) need attention from slice 1, not "added later" — they're effectively their own slice (slice 1) but also threaded through every other slice
  • Some design choices are constrained by what we built early; we don't get to retrofit cleanly
  • Tests for cross-slice integration come later and may surface late bugs
  • Refactoring shared code requires coordinating across slices

Mitigations:

  • Slice 1 (Identity & Audit) is foundational — invest in it generously
  • The bible documents conventions (code style, slice development pattern) so each slice follows the same shape
  • Integration tests for cross-slice flows are part of each slice's "done" definition

Notes​

The slice order matters. Slice 1 (Identity) before slice 2 (Customers) because customers need staff context. Slice 4 (Service Tickets) before slice 5 (Sales) because tickets convert to sales. The order is in slice overview.

This decision is reversible per-slice; a particular feature might want a "research-only" non-shipping pass first (e.g., AI integration, slice 11, has a spike phase before slice work).

See also​