Project Acme: The Client Onboarding

The companion finale attacked the product — six incidents, one trial, judgment under pressure. This finale builds the relationship: Acme, a facilities-services company, is onboarding onto the platform. Discovery interviews, the real ask behind the ask, a 30-day plan, one dataset with contracts, success metrics defined together, and a stakeholder review that proves the outcome. The one principle for the whole chapter: onboard the workflow, not the data.

The shape of the engagement

Four weeks, four artifacts. Each week ends with something the client can hold — and each artifact has an owner on the client side, because an onboarding owned only by the vendor is a demo with a longer timeline:

Notice what's missing: there is no "migrate all the data" week and no "train everyone" week. The engagement is scoped to one dataset, one workflow, one review. Everything else is explicitly refused in the plan — with the refusal written down, the way the borough-pack tradeoff memo wrote down its refusals. Scope discipline isn't saying no to the client; it's saying no to the second, third, and fourth engagements hiding inside the first.

The minimum concept: onboard the workflow, not the data

Every failed onboarding Dev has seen failed the same way: the team treated the engagement as a data-migration project — extract, load, transform, celebrate row counts. The client's actual problem was never "our data isn't in your system." It was a workflow that hurt: a supervisor building tomorrow's backlog by hand at 11 PM, a standup that starts with guesses, a spreadsheet nobody trusts. The data is the fuel; the workflow is the engine. Onboard the engine.

The protocol, in order — it mirrors the triage protocol's shape (scope, then evidence, then the smallest safe change), but its instruments are people:

Three things about this order. First, discovery before the done-line: you cannot write what "done" looks like until you've watched the workflow that hurts. Second, the client owns the done-line: "worth it" is their judgment, and the artifact that records it carries their signature — because the person who decides whether the pilot continues is the person who defined success. Third, the review is a deliverable, not a ceremony: it runs on the same grammar as an incident briefing — what happened, what's true now, what changed permanently — because an onboarding review and an incident briefing are the same skill: bad news delivered early, with a plan attached, to someone who needs to act.

Week 1: the discovery interviews

This is the Stage 1 skill — clarify the ask — applied to a client who is paying for the answer. "See everything in one place" is a stated ask; it describes a dashboard, not a problem. The discovery interviews exist to find the workflow that hurts. Two 30-minute interviews and one shadowed shift:

• The night-shift supervisor (the person closest to the work): "Every night around 11, I build tomorrow's backlog. I pull the inbox, the three spreadsheets, and my notebook. Takes about 40 minutes. If I miss an urgent ticket, the morning standup finds out at 6 AM."
• The ops director (the person who decides): "My best week is a week where the 6 AM standup starts with the backlog already prioritized and nobody's surprised. I don't need trends. I need Tuesday to not start with a surprise."
• The shadowed shift: the supervisor's notebook has urgency codes the spreadsheets don't — "will flood by morning" isn't a column anywhere, but it decides the order of the backlog.

Interviews tell you what people say the workflow is. Shadowing shows you what the workflow actually depends on. And the notebook leaves the engagement's first open data question on the table: the urgency codes live in a paper notebook — in no spreadsheet, no inbox export. The new workflow cannot reproduce the supervisor's prioritization unless urgency enters the data deliberately. So discovery ends with a decision, not a finding: the ops director chooses where urgency enters the new workflow before Week 3. Her answer: the supervisor tags urgency, in her own codes, when the site's daily CSV is produced — turning the notebook's tacit knowledge into an explicit, validated field at the source.

The real ask, written down and read back to the client for correction: the night-shift supervisor needs tomorrow's prioritized backlog before the 6 AM standup, built from Acme's tickets, with nothing urgent missed. Not a data lake. Not dashboards. Not trends. One workflow, one person, one deadline. The ops director corrects one word — "prioritized by our urgency codes, not yours" — and that correction is the most valuable sentence of the engagement, because it becomes a contract requirement in Week 3.

The done-line: written with the client

Before any plan, any code, any data — the done-line, written with the ops director, carrying her signature. It has the same shape as the acceptance lines from the trial: specific, dated, and naming who decides.

Study what the done-line does. It names the person (the supervisor), the moment (the 6 AM standup), the evidence (reconciliation under the agreed policy; metrics reviewed against recorded baselines), and the owner of the judgment (the ops director). The "agreed outcome metrics" it references were sketched in Week 1's discovery and formalized — definitions versioned, baselines planned — in the Week 2 plan, before the pilot ran. It does not mention dashboards, trends, or row counts. If the engagement ended with 12,400 tickets loaded and the supervisor still building the backlog by hand at 11 PM, the done-line says it failed — and the done-line is right. Write the verdict before the work, with the person who delivers it.

Week 2: the 30-day plan

The plan is one page. It fits on one page because anything that doesn't fit is a second engagement. Every row names the deliverable, the owner, and — the load-bearing column — what is explicitly refused:

The refused column is what protects November 30. Each refusal was a real sentence someone said — "while you're at it, can we get the mobile app," "we should really do all six sites at once" — and each one is answered in the plan with the reason: the pilot proves one workflow, then earns the right to the next. The ops director signs the plan including the refusals, which is what makes them stick when the requests resurface in Week 3. They will resurface. That's what the signature is for.

The signed plan also carries the success-metric definitions (v1) and the baseline collection plan — because acceptance is defined before the pilot runs, the way eval acceptance is defined before the system runs. The RAG-evals lesson's rule transfers directly: define the metric after seeing the outcome and you can always choose the flattering one. Week 4 measures against these definitions; it does not invent them.

Week 3: the first dataset is a conversation, not a load

Week 3 opens with the pilot site's first data drop: 90 days of maintenance tickets, 12,400 rows, one CSV — one site, one workflow, the small blast radius the plan promised. The temptation is to load it. The discipline is to interrogate it — because the first dataset is where the client's mental model of their own data meets reality, and they are never the same thing.

Before any loading, the data-boundary decision — the PII thinking from the security lessons, applied to someone else's data. The tickets contain free-text notes, and free text contains names: technicians, tenants, "called Maria about the leak." The contract states the classification up front: raw free text stays inside Acme's approved sensitive-data boundary — the storage and processing environment the ops director's security contact approved for sensitive text, with access and retention controls, defined once in Week 2 and used consistently from here on. Only the minimized fields the workflow needs (ticket id, site, status, urgency, opened time) cross to the shared platform; anything uncertain is refused into the review queue — which is an approved sensitive-data store with access controls, or the data doesn't go there. Minimize first; detect what remains; block according to policy. The boundary is agreed in Week 2, before the data exists.

Worked example: contracts, then reconciliation

The contract is the client's vocabulary, written as code — the validation lesson's Pydantic contract, with the curriculum's rule applied twice: the client's vocabulary is validated, never guessed at — and the Week 2 urgency decision is where that rule gets teeth:

from pydantic import BaseModel, field_validator, ValidationInfo

KNOWN_STATUSES = {"OPEN", "IN_PROGRESS", "ON_HOLD", "CLOSED"}  # Acme's vocabulary,
    # confirmed with the ops director in discovery — "prioritized by OUR codes"
KNOWN_URGENCIES = {"routine", "urgent", "will_flood_by_morning"}  # the supervisor's
    # notebook codes ("will flood by morning", normalized) — the codes the old
    # workflow actually sorted by. Week 2 decision: the supervisor tags urgency
    # when the site's daily CSV is produced, so every row carries Acme's
    # classification at the source.

class MaintenanceTicket(BaseModel):
    ticket_id: str
    site: str
    status: str
    urgency: str  # no default: a blank urgency is an unknown, and unknowns
                  # quarantine — see the Week 2 decision below
    opened_at: str

    @field_validator("status", "urgency")
    @classmethod
    def known_vocabulary(cls, v: str, info: ValidationInfo):
        known = KNOWN_STATUSES if info.field_name == "status" else KNOWN_URGENCIES
        if v not in known:
            raise ValueError(f"unknown {info.field_name} {v!r}: quarantine, don't coerce")
        return v

The blank-urgency question nearly became a default. The ops director's first instinct was urgency: str = "routine" — her call, her business meaning, and on the surface the curriculum's rule ("defaults encode business meaning, so the client sets them") seemed to bless it. Dev asked the question the pilot promise demanded: "If urgency is blank, are you comfortable treating it as routine — or could a blank ever mean an urgent ticket nobody tagged?" The pilot's core promise is "nothing urgent missed." A blank defaulted to routine could hide exactly the ticket the customer fears most. She changed her answer: a blank urgency is an unknown, and unknowns quarantine — the supervisor classifies it before the row enters the workflow. Client approval makes a default legitimate; it doesn't make it safe. Safety depends on what the default hides if it's wrong. Ask that before encoding any default: what does this default hide if it's wrong?

The load runs. The reconciliation — the same explicit accounting the trial demanded. Note the last column: the 424 are unresolved until the client decides their fate. A quarantine count is not a resolution:

$ python onboard.py --drop acme_pilot_site_90d.csv
received: 12400 | accepted: 11976 | quarantined: 424 | resolved: 0 | unresolved: 424
$ psql -c "SELECT raw->>'status' AS s, COUNT(*) FROM quarantine GROUP BY 1;"
    s     | count
----------+-------
 CANCELLED |   301
 DUPLICATE |   123
-- 301 + 123 = 424. Every quarantined record is accounted for by name —
-- and every one of them is still unresolved, pending the client's policy.

This is the break — and it's a good break, because the contract caught it instead of the standup. The client's vocabulary has two statuses nobody mentioned in discovery. The fix is not to add them to KNOWN_STATUSES and re-run. The fix is a conversation, because the quarantine policy belongs to the data owner, not the lesson: the ops director decides what CANCELLED means for the backlog (excluded from the active backlog, but reported) and what DUPLICATE means (linked to its surviving ticket and deduplicated, with the link recorded). Her decisions go into the versioned mapping table with effective dates — the same pattern that absorbed the codebook change in the trial — and the re-ingest closes the books with the categories preserved: 424 quarantined → 424 dispositioned under the agreed policy → 0 unresolved. The final accounting never pretends all 12,400 became live backlog records: 11,976 accepted as active, 301 excluded-but-reported, 123 deduplicated-and-linked, 0 unresolved. Received, accepted, excluded, deduplicated, unresolved — every ticket in exactly one bucket.

One more contract, and it's the one the security lessons insisted on: the platform proposes the prioritized backlog; the supervisor approves it. These are two different controls. Authorization answers "may this caller act on this resource?" — the platform's service account, scoped to the pilot site, may generate the backlog. Human approval answers "did an authorized human approve this exact snapshot, bound to its content?" — the supervisor approves the specific backlog by its content-addressed snapshot ID (snapshot ID plus payload hash), so the approval binds to the data it was given, not merely to an ID that could later point somewhere else. The approval decision is written through an authenticated authorization path the proposing component cannot forge — the platform can request an approval, but it cannot write the approved state. The backlog becomes the night-shift plan only in the approved state; re-runs mint new snapshots with new content hashes, so an approval can never silently attach to different data. Idempotent executed states, stable unique IDs, and no single model decision with enough authority to turn one failure into a serious incident.

Week 4: measure success, then review it

The metric definitions were written and co-signed in Week 2, before the pilot ran — acceptance defined before the outcome, the same rule the evals lesson drilled for RAG systems. Week 4 is where those definitions get their numbers, and where the evals lesson's durable rule gets its client-side form: version the metric definitions, the baseline, and the measuring method. A metric nobody wrote down is a feeling; a metric written down without its definition is an argument waiting to happen; a metric defined after the results are in is a choice of the flattering one. The one-page metric sheet, measured:

Read the honesty in that table. "Unknown — never measured" is a complete and respectable baseline; inventing one would be the midnight-commit behavior the trial condemned. "~40 (supervisor's estimate)" is labeled as an estimate, not a fact. And the definitions are versioned — v1, dated — because the ops director will refine what "urgent" means after watching the backlog for two weeks, and when she does, the change goes through a review with her sign-off, not a quiet edit. The number follows the evidence, never the deadline — even when the deadline is a pilot renewal.

Then the adoption ladder, measured honestly at the review — the same ladder the trial used, because the question is the same: is the system being used, and does the use reach the outcome? One correction the trial taught: the denominator is the intended population — the 6 supervisors and ops leads who run the night-shift workflow at the pilot site — not the 34 technicians company-wide. Adoption measured against everyone with an account is a vanity denominator.

Two honesties in that table. First, the audit log proves a view during the window — not that the backlog drove the meeting; the supervisor confirms meeting use at the review, and the table would say "client-reported" if she couldn't. Don't claim the instrumentation proves more than it observes. Second, readiness and quality are separate rungs: "the standup started with the approved backlog" is auditable; "no surprises" is a quality claim that needs its own evidence — the missed-urgent count and the surprise log.

The ladder is reported with the same neutrality as the 429s: 4 of 6 in repeat use is not a failure to hide, it's the next friction to investigate — and the re-measurement date is set before the review ends. And the honest caveat is stated up front: "9 of 10 standups" can't isolate the platform from everything else that changed in November. Measure anyway, and stay honest about what the measurement can't prove — that's the difference between evidence and theater.

The first stakeholder review

Week 4, Friday. The ops director, the supervisor, and you — the whole engagement compressed into the format a customer can actually use. Study the grammar: it's the incident briefing from the trial, because an onboarding review and an incident briefing are the same skill.

She renews the pilot. Not because the platform is impressive — the evidence against her done-line supports the renewal decision, in her words. The briefing is a deliverable: she forwards its shape to her leadership, the way Maria forwarded the postmortem. The customer sells the renewal internally; your job was to give her the evidence, in her vocabulary, with nothing softened.

The scorecard, from the client's side

The curriculum's milestone scorecard, applied to the engagement. Each dimension names what "good" looked like this month — and the trap it punishes:

Read the right column as a whole: every trap is the same mistake wearing different clothes — optimizing for impressiveness over outcomes. The companion finale graded the same scorecard under fire; this one grades it across the table. The central lesson, stated one final time: the best onboarding isn't the most complete migration — it's the smallest reliable workflow that creates the required customer outcome and survives the client's reality.

Acme, experienced

Step back and name what the engagement proved. Not that the platform works — the milestones proved that. That it lands: in a client's vocabulary, inside their boundary, on their clock, measured by their judgment. Each week converted a lesson into a relationship property — the corrected sentence, the signed done-line, the refused column, the quarantine policy with a name on it, the versioned metrics.

And the arc of the full curriculum lands here, from the other side. Stage 1 taught you to scope the vague ask — here the asker is a client. Stage 2 taught you to move data without losing it — here the data is someone else's. Stage 3 taught you to integrate without trusting — here the trust is negotiated, not assumed. Stage 4 taught you to put contracts around intelligence — here the contracts carry the client's vocabulary. Stage 5 taught you to operate what you shipped — here the operator is the client's data owner. Stage 6 taught you to present the evidence — here the audience decides the renewal. The companion finale was the exam for judgment under fire. This one is the exam for judgment across the table: what to ask, what to refuse, what to measure, and what to tell the customer on Friday at 4 PM — when the customer is the one who wrote the done-line.

Five lines to leave with. Onboard the workflow, not the data. The first dataset is a conversation, not a load. Write the verdict before the work, with the person who delivers it. Every unknown is a question for the data owner, not a guess for the loader. And the last one, unchanged: production green is not success — adoption is the next test, customer outcome is the destination.