<!--
Practice example for the "Designing a System: Decomposition" chapter (Chapter 13). A system spec is
the plan you write BEFORE you build anything: one big goal, broken into a few specialists, each with a
clear job, its inputs, its output, and how it hands off to the next. This is what "designing a system"
looks like on paper. It uses this pack's sample-data.csv as the source and example.com addresses only —
no real people, no real business, no secrets.

You don't need to memorize any format. The point is: a good spec keeps the system SMALL, gives every
part one job, makes every handoff explicit, and builds in a check before anyone trusts the result. When
you ask Claude to "help me decompose this goal," something like this is what you're designing together.
-->

# System Spec: Weekly Account Brief

## The goal (one sentence)
Turn my raw account list into a short, reviewed brief that tells me which accounts need attention this
week — prepared for me to read, never sent on its own.

## Why a system, not a single tool
This has natural stages (read → flag → draft → check), and each stage benefits from a specialist
focused on one job. If it were just "read the file and list overdue rows," one tool would do — and I'd
build one tool. It's the drafting and the cross-checking that make it worth a small system.

## The specialists (the smallest set that does the job)

### 1. Reader (read-only)
- **Job:** Read every row of the account list and hand on a clean, structured list.
- **Input:** `sample-data.csv`
- **Output:** A tidy list of accounts with their stage, owner, next step, and last-update date.
- **Handoff:** Passes the structured list to the Flagger.
- **Tools:** File reading only. Cannot edit, run commands, send, or reach the network.

### 2. Flagger (read-only)
- **Job:** Decide which accounts need attention — a next step overdue, a stalled stage, a passing due date.
- **Input:** The Reader's structured list; today's date.
- **Output:** The subset of accounts that need attention, each with a one-line reason.
- **Handoff:** Passes the flagged accounts to the Drafter.
- **Tools:** Reading and analysis only. No sending, no editing.

### 3. Drafter
- **Job:** Write a short, plain-English note for each flagged account and collect them into a one-page brief.
- **Input:** The Flagger's flagged accounts with reasons.
- **Output:** A one-page draft brief, most urgent first.
- **Handoff:** Passes the draft to the Verifier.
- **Tools:** Reading and writing a draft file only. No sending.

### 4. Verifier (read-only) — the reliability stage
- **Job:** Cross-check the draft against the original rows: are the facts right, is anything missing, is
  anyone flagged who shouldn't be? Flag problems before I ever see the brief as finished.
- **Input:** The draft brief; the original `sample-data.csv`.
- **Output:** The brief marked "checked," plus a short list of anything it flagged.
- **Handoff:** Hands the checked brief to me. **This is where the system stops.**
- **Tools:** Reading only.

## The handoffs, at a glance
`sample-data.csv` → **Reader** → structured list → **Flagger** → flagged accounts → **Drafter** →
draft brief → **Verifier** → checked brief → **me (human checkpoint)**

Run these in **sequence** — each needs the one before it. (If I later added a second data source, its
Reader could run in *parallel* with this one; I'd weigh the speed against the extra cost first.)

## The guardrails (fill these in before running on anything real)
- **Least privilege:** every specialist above is read-only except the Drafter, which may only write a
  draft file. None can send.
- **Human checkpoint:** the system **stops at the Verifier** and hands me the brief. Nothing is sent,
  posted, or changed on my behalf.
- **Verification stage:** the Verifier cross-checks every fact — the system never treats a draft as done.
- **Observability:** after a run, I read what each specialist did and what it cost.
- **Cost ceiling:** a monthly limit is set; the read-only stages use a cheaper model since they don't
  need the strongest one. (Numbers change — see claude.com/pricing.)
- **Kill switch:** I know the one way to stop the whole system at once, and I've confirmed it works.

## Done looks like
I open a one-page brief, most urgent first, that has been cross-checked against the source — and I'd be
comfortable acting on it after I've read it. Nothing left my computer to get here.

## The honest ceiling
This is a **supervised** system: I run it, the specialists do the parts, I read the checked result. It
is not something that should run unattended overnight, guarantee its own reliability, or send anything
on my behalf. If I needed that, it would be a job for a human engineer — not a no-code system.