Cut down, not across

The Portal stacks three layers: a store (data and ids), a domain core (the framework-free rules), and a surface (the web app, the bot, the dashboard). A split runs through that stack one of two ways. A vertical cut takes one thin thread through all three layers for a single story — enough store, enough domain, enough surface to let a role do one new thing. It is demoable end to end, because the thread reaches all the way through.

A horizontal cut takes one whole layer at a time — the courses table, then the courses API, then the courses page. Each layer is real, and each can be small. But none is demoable on its own: the table serves no learner, the API serves no learner, and only when the page lands does anyone see anything. The output of a horizontal cut is a fragment — a slice only another slice can use. Same destination, same total work; the difference is whether each slice ships value the day it lands or waits on the layer above it.

The hero counts the demoable slices; this view names the reason — a slice is demoable only if some role can be shown it. Step across the slices of both cuts. Each vertical slice names the role it serves: a learner can browse, enrol, open a lesson, track progress. Each horizontal slice names no role yet: the courses table, the courses API, and the courses page each serve a learner nothing until the thread reaches the surface.

That is the whole test, made concrete. A slice a role could be shown is a story; a slice only another slice can use is a layer. Reading the role off each slice is how an Operator tells a value split from a layered one before handing the rung to the Author — and it is why the four patterns all cut down, never across.

On the Portal — the learning platform this course builds — “manage the catalogue” cut the right way is the value ladder: browse → enrol → open a lesson → track progress. Each rung threads all three layers for one story, so each is demoable the day it lands. Cut the wrong way, the same work becomes the courses table → the courses API → the courses page: three slices, each one layer, none demoable on its own. The table serves no learner, the API serves no learner, and only the page shows anything — and only after the two below it land.

The ids the slices rest on are already minted — Portal.ID.generate/1 hands back a typed id and Portal.ID.decode/1 reads its .type back — so no slice waits on another to define identifiers. What makes a horizontal slice wait is the layer boundary, not the data. The companion Functional Programming course teaches the Portal’s internals; this course decides the direction of the cut.

# "manage the catalogue" — same destination, two directions.

# VERTICAL → each slice threads store + domain + surface → demoable the day it lands:
#   browse → enrol → open a lesson → track progress        (4 / 4 demoable)

# HORIZONTAL → each slice is one whole layer → a fragment until the surface lands:
#   courses table → courses API → courses page             (0 / 3 demoable)

id = Portal.ID.generate(:course)        # ids are minted — the layer boundary is what makes a slice wait, not the data
assert Portal.ID.decode(id).type == :course

Vertical cuts thread all the Portal’s layers for one story, so each slice is a whole capability a role can demo the day it lands; horizontal cuts take one layer at a time and leave fragments no role can use until the last one lands. The test is demoable-end-to-end: a slice a role could be shown is a story; a slice only another slice can use is a layer. That closes A2.05 — the signal to split is an INVEST failure, the patterns name the seam, and the cut must always run vertically. With stories that are valuable, well-formed, invested, and well-sliced, the chapter turns to pinning each one down with concrete acceptance.

The sources behind the vertical-slice direction, and where it connects in the course.