Chapter 7 · Foundations

Choosing your first slice

The narrowest thing worth shipping is not the easiest thing to build. Four tests a candidate slice has to pass, and why the demo-friendly version fails all of them.

8 min read

You now have a map of the system from the previous chapter. This chapter decides which corner of it to build first. It is the most consequential hour in the project and it involves no code, which is exactly why it usually gets skipped.

The trap

The natural first slice is the one that demonstrates well. For Atlas that would be:

Ask Atlas anything about the business and it answers.

This is attractive, takes about a week to get working badly, and is the wrong choice for a specific and non-obvious reason: it cannot fail informatively. When a broad assistant gives a poor answer, every component is a suspect. Was the document not ingested? Was it chunked badly? Did retrieval rank it ninth? Did the model ignore it? Was the person not allowed to see it anyway?

A good first slice narrows the suspect list to one or two components. That is the whole criterion. Shipping value matters, but you will not reach shipping value through a system you cannot debug.

The four tests

A candidate slice has to pass all four.

1. One user group

Not one user — one group with one permission profile. Permissions are the hardest part of this system and they are also the part where a bug is a real incident rather than a disappointment. Starting with a single group means the permission logic is exercised, because the group still has limits, but you are not debugging the interaction between three profiles at the same time.

For Atlas that is inside sales: 24 people, who may see all policy and product documents but only contracts for accounts they own.

2. One source shape

Documents, or a database, or an API. Not two. Chapter 12 spends a chapter on why these are genuinely different engineering problems rather than variations on one; combining two in the first slice means every quality problem has two possible origins.

Documents first is usually right, for an unglamorous reason: documents are where the knowledge that people currently ask colleagues for actually lives. A database answers questions people can already answer themselves with a report.

3. Read-only

No writes, no sends, no tickets. An action that cannot be taken back changes the risk profile of every bug from "embarrassing" to "expensive", and it brings in confirmation flows, idempotency and audit requirements — all of section 6 — before you know whether the retrieval underneath is any good.

4. A question set you can write down today

This is the test most often failed, and the one that predicts the outcome best.

If you cannot list thirty real questions the slice must answer, you do not have a slice. You have a direction.

Thirty is not arbitrary. It is roughly the smallest set that stops you tuning to a handful of examples, and it is small enough to collect in an afternoon by asking the people who will use the thing. Those thirty questions become the first eval set in section 9, the retrieval test set in chapter 49, and the thing you demo against. They are also where chapter 10 gets its numbers.

Collect them verbatim. "What is our returns policy for damaged goods?" is a question. "Policy lookup" is a category, and categories cannot be scored.

Atlas's first slice

Written as one sentence, because a slice that needs a paragraph is not a slice:

Inside sales can ask a question in plain language and get a cited answer from the policy, specification and contract documents, with contracts restricted to accounts they own.

That is about six weeks of work done properly, and it exercises ingestion, chunking, permission-filtered retrieval, generation, citation and evaluation. Five of the seven components from the previous chapter. It leaves out only the router and tools.

What "explicitly out" is for

The out-of-scope list is not documentation. It is a commitment device, and it has to be visible to the people who will use the system, because the first thing that happens after a successful demo is a request to add the database.

// Scope as a config file rather than an understanding. The registry in
// chapter 21 grows out of this.
export const SLICE_V1 = {
  userGroups: ['inside_sales'],
  sources: ['policy_docs', 'product_specs', 'customer_contracts'],
  capabilities: ['retrieve', 'cite'],
  excluded: {
    orders_db: 'Section 6. Needs tool calling and a latency budget.',
    tickets_api: 'Section 6. Third-party rate limits need their own handling.',
    sales_email: 'Personal data review not complete. See chapter 16.',
    writes: 'Needs confirmation flows and audit logging. Section 6 and 10.',
  },
} as const

The value of writing the reason beside each exclusion is that it answers the question "why not?" without a meeting, and it distinguishes "not yet, here is the blocker" from "never, here is why". Those are very different answers and they get conflated constantly.

Sizing the slice honestly

A useful sanity check before committing. For Atlas's slice:

Quantity	Number	How it was obtained
Documents in scope	~2,400	Counted in the document store, filtered by folder
Pages, roughly	~31,000	Document store reports page counts
Chunks, at ~800 tokens	~45,000	Pages × ~1.4 chunks per page
One-time embedding cost	Low tens of dollars	Chunks × tokens × the model's rate
Questions collected	34	Asked eight sales reps for five each
Index storage	Under a gigabyte	45,000 × a 1,536-dimension vector plus text

Run these numbers before you start. They take twenty minutes and they occasionally change the plan: a corpus of two million documents is a different project from a corpus of two thousand, and the difference shows up in chunking strategy, in whether a full re-index is a casual operation, and in whether hybrid retrieval is optional.

# The twenty-minute version. Counting beats estimating.
find ./export/policy -type f -name '*.pdf' | wc -l
find ./export -type f \( -name '*.pdf' -o -name '*.docx' \) -print0 \
  | xargs -0 du -ch | tail -1

The failure mode: scope creep through the back door

The slice will not be widened by a decision. It will be widened by a sequence of small reasonable requests, each of which is genuinely small.

Somebody asks whether it can also check stock levels. That is one database query — a day of work. Then stock levels are stale because they are read from the nightly index rather than live, so now it needs a live query path. The live query path has a latency budget, so now there is caching. The cache needs invalidation. Six weeks later the document retrieval that was the actual slice is still returning the wrong chunk for nine of the thirty-four questions, and nobody has looked at it since week two.

The defence is not willpower. It is the measurement from chapter 10: a numeric gate on the current slice that has to be met before the next one opens. "Coverage is at 54% against a target of 70%, so the database is after that, not before" is an argument that survives a hallway conversation. "We should stay focused" is not.

Key points

A good first slice narrows the suspect list when something goes wrong. That matters more than how well it demos.
Four tests: one user group, one source shape, read-only, and thirty real questions written down today.
Documents first, usually — that is where the knowledge people currently ask colleagues for actually lives.
Write the out-of-scope list with a reason beside each item, distinguishing "not yet" from "never".
Count the corpus before building. A twenty-minute count sometimes changes the plan.
Scope creeps through small reasonable requests, and only a numeric gate stops it.

Next: setting up the project — the repository, model access, and the three decisions in the first commit that are irritating to change later.