slices

a slice is one domain-owned MDX file specifying and auditing one complete vertical capability: user outcome, high-level design, runtime and data flow, exact implementation, and verification evidence. it is the enforceable, debuggable unit between a user expectation and the code that realizes it.

not a task list, component inventory, or partial implementation note — if a reader cannot trace the outcome through boundaries to exact code, it is not yet a slice.

without slices (or with stale ones):

• a user-visible bug forces scattered-comment archaeology across six files; design vs implementation blame is undecidable.
• two agents fixing the same subsystem silently contradict each other — nothing to reconcile against.
• a third agent cargo-cults code without the outcome or invariants and violates a constraint documented nowhere.

one slice tracing outcome through boundaries to exact code gives every later investigation a single entry point with invariants, the implementation manifest, and verification commands attached. the invariant protected: one auditable source per capability, checkable by both humans and the hash verifier against live code.

organize slices by their shortest exact domain word:

slices/
  workflow/
    approve-run.mdx
  billing/
    record-purchase.mdx

compound filename only when both domain words are needed for uniqueness: workflow/approve-run.mdx, not provider-workflow-approval-flow.mdx.

every slice begins with concise, non-collapsed sections:

1. outcome — actor, expected result, and non-goal.
2. design — responsible domains and the end-to-end flow in a few steps.
3. invariants — the facts that must always remain true.
4. acceptance evidence — exact proof that the user-visible behavior and its durable effects match the contract.
5. implementation freshness — the declared hash state and required action if stale.

---
title: complete an action
visibility: private
status: implemented
kind: slice
domain: process
capability: complete-action
implementation_files:
  - packages/runtime/src/~processes/completeActionProcess.ts
  - packages/domain/src/process/completeAction.ts
implementation_hash_algorithm: sha256
implementation_hash: 5c0d...
implementation_reviewed_at: 2026-08-24T00:00:00Z
implementation_review_status: current
---

• implementation_files — ordered manifest of exact repository-relative paths.
• implementation_hash — SHA-256 digest the project slice verifier computes from the exact bytes of the manifest in listed order; machine-owned, never hand-calculated or hand-edited.
• implementation_review_status — current (hash verified, full slice reviewed) · stale (code and slice may disagree) · blocked (names the exact missing authority or evidence in visible prose).

keep these inside <Accordions> so the top level stays a design surface while a full audit lives in the same file:

<Accordions>
  <Accordion title="Request and authorization boundary">
    Route, schema, policy, typed failure outcomes, and exact owning files.
  </Accordion>
  <Accordion title="Durable workflow and persistence">
    Step identity, idempotency key, state transition, tables, and artifacts.
  </Accordion>
  <Accordion title="Interface and verification">
    UI states, query invalidation, checks, observed output, and residual risk.
  </Accordion>
</Accordions>

one accordion per independently auditable boundary: API/auth, domain/service, persistence, provider, workflow/queue, interface, verification. include exact file paths, exported symbols, schemas, tables, events, error codes, and commands where they matter. never split that detail into another document to keep the slice short.

before changing any file in implementation_files:

1. read the slice's visible design and every accordion in full.
2. run the slice verifier to compare its manifest hash with implementation_hash.
3. hash differs → mark implementation_review_status: stale and create a tracked slice review task before implementation continues.
4. update the high-level design and detailed evidence first, then code.
5. after verification, let the verifier write the new hash, timestamp, and current status; review the whole slice again against the final code.

a stale slice blocks a completion claim — it never permits guessing that behavior still matches the user expectation.

start every bug investigation from the relevant slice: check the visible outcome and invariant, then use the accordions to test each boundary in order. the repair is accepted only when slice, implementation hash, and acceptance evidence agree — an auditable claim about the declared capability, never proof that unrelated code has no bugs.

• make one slice cover several unrelated user outcomes.
• hide the high-level design in an accordion.
• use directory globbing, a generated filename, or an informal file list as the implementation manifest.
• update code while the slice is stale without an explicit slice review task.
• mark a slice current from a partial read, a diff alone, or a successful compile without behavior evidence.

bad

checkout-notes.mdx (ad hoc notes):

# Checkout Features

Components:
- CheckoutForm.tsx
- PaymentButton.tsx
- ConfirmationPage.tsx

Routes:
- POST /checkout
- GET /checkout/confirm

TO DO:
- figure out what happens to the order if payment fails mid-request
- need to check if inventory is already decremented

a payment failure hits production: the agent reads this file, then searches for decrementInventory across five service files. two services handle inventory — one from checkout, one from a batch job — and no slice says whether orders roll back or retry. the agent fixes the first service without checking the second; orders are now double-decremented in the batch job. a third agent later adds email notification by copying the confirmation page without reading outcome or state transitions, emailing deleted user accounts.

good

slices/billing/record-purchase.mdx:

---
title: record a purchase after payment settlement
visibility: private
status: implemented
kind: slice
domain: billing
capability: record-purchase-after-payment
implementation_files:
  - apps/backend/src/domains/billing/recordPurchaseAfterPayment.ts
  - apps/backend/src/~workflows/purchaseWorkflow.ts
  - apps/backend/src/infra/drizzle-orm/tables/billing/purchaseOrderTable.ts
implementation_hash: a1b2c3d4...
implementation_review_status: current
---

outcome: after a payment provider confirms settlement, record an immutable
purchase order. idempotency ensures no duplicate records if the workflow retries.
failure in this step must not delete inventory or send duplicate email.

invariants:
- a purchase order records exactly one complete purchase from one buyer
- a purchase order is never deleted; incorrect orders transition to corrected state
- inventory is committed before payment confirmation is sent to the buyer
- email notification is always sent exactly once for each completed order

design: payment provider → workflow step → record order + decrement inventory
(atomic) → emit purchase-recorded event → send email (via separate queue)

acceptance evidence: trigger settlement event for test account → query purchases
table → verify order.status = completed, order.created_at is current, inventory
is decremented. trigger same settlement again → verify no duplicate purchase
record, inventory unchanged.

on the same payment failure, the agent reads this slice and immediately knows the exact entry point (settlement event), the idempotency boundary (step name), the durable fact (purchase order table), and the verification command to confirm the fix. no archaeology; no guessing. the slice is the debuggable unit.

specification-first · change visibility · MDX authoring · domain glossary · verification evidence