A document that reads well and a document that works are two different things. You only find out which one you wrote by handing it to a stranger and watching them try to use it.
Phase 7 is where the documentation gets proven by use, not by reading — before the team that wrote the system walks out the door.
Every idea below is paired with the real thing — examples come from a fictional but fully worked engagement, Harbor Mutual, a regional insurer.
Why this phase exists at all
In a consulting engagement, the documentation is the handoff
The build is feature-complete. The system runs. And in a few weeks the people who wrote it are gone. Everything this phase produces is what the client lives with after that — so the only question worth asking is whether someone who isn't us can understand, run, and operate it from the documents alone.
This isn't hygiene and it isn't "write the docs at the end." Most of the record already exists — specs stayed current as the code changed, decisions were signed when they were made. Phase 7 consolidates what's there, checks it against the system as built, closes the open decisions, writes the operational manual — and then proves all of it.
The proof is the whole point. A document nobody has executed is a promise, not a fact.
Build closed feature-complete: 44 features merged, the system running in Harbor's dev and test environments, the claim-decision clock instrumented. One question remained for the week:
"Can Harbor understand, run, and operate this system without us in the room?"
After this week the pod leaves. Whatever the docs don't say, Harbor's on-call engineer won't know — at 3 a.m., alone.
It stays "just docs" right up until the client's on-call engineer is alone with the system at 3 a.m. In a consulting engagement, this phase is the product the client keeps.
Go deeper — the full method
Build is feature-complete; the gated phases resume. Phase 7 exists to answer one question: can someone who isn't us understand, run, and operate this system from its documentation alone? In a consulting engagement that question is not hygiene — it is the handoff. Everything this phase produces is what the client's team lives with after we leave.
This method generates most of its documentation as it goes: specs stay current by construction (the spec changes in the same PR as the behavior), ADRs were signed when decisions were made, and the harness is versioned in the repo. So Phase 7 is not "write the docs at the end." It is: consolidate what exists, verify it against the system as built, close the decision debt, write the operational docs — and then prove all of it by use, not by reading.
New features, deployment to production, and monitoring configuration are out of scope — they belong to the Build loop (now closed), Phase 8, and Phase 9. Defects found by documenting — an unintentional drift, a broken setup step — are in scope and ride the build loop as specs before the phase can close.
It's "just docs" until the client's on-call engineer is alone with the system. In a consulting engagement, this phase is the product the client keeps.
The rule that governs everything
Claude drafts from the code; humans verify by use
The same spine runs through every phase: the AI does the reading, the diffing, and the first drafts; people make every decision and carry the accountability. Phase 7 has its own sharp edge — the AI wrote most of the system, so now it drafts most of the record of it, but it can never declare that record true.
- Claude drafts the README from a fresh checkout, diffs every endpoint against the signed contracts, sweeps the build history for decisions nobody wrote down, and drafts the operations manual from the real pipeline.
- People decide whether a difference was a choice or a defect, sign each decision, and — the part that matters — verify by use.
Why so strict? Reading your own output back is the author grading the author. The AI can't prove its own docs any more than it can review its own code.
Claude drafted the README, the API docs, and the runbook procedures. But none of those counted as done until a human used them. The phase belonged to Nadia Brooks, the Quality Engineer, whose job was to define what "verified" meant — and to make sure the people doing the verifying were not the pod.
"Claude drafts from the code and the specs; humans verify by use."
Go deeper — the full method
Claude wrote most of the system; now it drafts most of the record of it. The human rule of the phase: Claude drafts from the code and the specs; humans verify by use.
- Drafts the README and user-facing docs from the repo as it actually is, including setup against a fresh checkout — then gets corrected by what the cold run finds.
- Generates the API documentation by diffing, not transcribing. Every endpoint is read from the implementation and compared against the Phase 2 contracts. Each drift gets a what, a when, and a why — or a defect flag. Transcribing the code would faithfully document the bugs; the diff is what finds them.
- Sweeps the Build history for undocumented decisions. A read-only pass over the merge history and spec library, looking for the choices that never got an ADR: a dependency added, a pattern changed, an alternative rejected in a PR thread. Each finding becomes a drafted ADR for humans to sign or strike.
- Drafts the RUNBOOK procedures from the real pipeline and infrastructure — then gets corrected by the ops walk-through.
What Claude never does: declare a document verified, decide whether a drift was intentional, or sign an ADR. Reading its own output back is not verification — that is the author grading the author, and the rule survives the Build loop intact.
What the week must answer
Four questions — and deliberately nothing else
Phase 7 isn't a place to add features, deploy to production, or wire up monitoring — each of those has its own home. Everything this week produces exists to answer exactly four questions.
- Is the written system the built system? The API docs get diffed against the signed contracts; every difference is explained or fixed.
- Can a stranger run it? Proven by a newcomer doing a setup from scratch.
- Can a stranger operate it at 3 a.m.? Proven by an ops engineer walking real procedures in a real environment.
- Is the decision record complete? Every significant choice from the build has a written record — nothing lives only in someone's head.
- The endpoint diff produced a catalog of exactly two differences — one a deliberate choice, one a defect.
- Ines Roy, a Harbor engineer hired three weeks earlier, ran the README on a clean machine.
- Tom Reilly, Harbor's platform engineer, executed a deploy, a rollback, and a simulated failure from the runbook.
- The history sweep found two decisions living in PR threads and one person's memory; both became signed records.
It feels efficient to start prepping the production deploy now, or to sketch the alerts. Don't. The runbook can point at things that don't exist yet — it must not invent them. Documenting a topology that isn't built is documenting fiction.
Go deeper — the full method
Phase 7 answers four questions, and nothing else:
- Is the written system the built system? (API docs diffed against the Phase 2 contracts, every drift explained or fixed; specs spot-audited against behavior)
- Can a stranger run it? (the README, proven by a cold checkout)
- Can a stranger operate it at 3 a.m.? (the RUNBOOK, proven by a cold walk-through of real procedures in a real environment)
- Is the decision record complete? (every significant Build-era decision has an ADR; nothing lives only in someone's head)
New features, deployment to production, and monitoring configuration are out of scope — they belong to the Build loop (now closed), Phase 8, and Phase 9. Defects found by documenting — an unintentional drift, a broken setup step — are in scope and ride the build loop as specs before the phase can close.
It feels efficient to start prepping the production deploy now, or to sketch the alerts. Don't. The runbook can point at things that don't exist yet — it must not invent them. Documenting a topology that isn't built is documenting fiction.
The technique that earns the phase
Diff the docs against the code — never transcribe
There are two easy, wrong ways to write API documentation. Copy the old contracts, and the docs describe a plan the system may have outgrown. Copy the code, and the docs faithfully describe every bug as if it were a feature. The honest way is to read both and compare them.
Every endpoint gets read from the implementation and held up against what it was promised to do. Each gap is a drift — and each drift gets a human label:
- Intentional — somebody chose this during the build. Fine, but the why gets written down and the contract updated.
- Unintentional — nobody decided this; it's a defect. It goes through the same fix-and-review loop as any other bug, before the phase can close.
The diff is what makes drift visible. Transcribing either side hides it.
Fourteen weeks of build, and the diff surfaced just two differences — the receipt for keeping specs current the whole way. One of each kind:
The degraded "pending verification" response also carries the replica's last-refresh timestamp — added so adjusters could judge how stale it was. Approved at the time; the why is now in the contract.
Claims-search returned a bare 500 with an empty body on a replica timeout, bypassing the standard error format. No decision behind it. Fixed through the loop, merged, deployed.
A short catalog after a long build is the discipline showing: behavior and its contract changed together all along, so the system mostly is the contract. A long catalog is a build-quality finding, not a documentation chore.
Go deeper — the full method
Two drafting streams run at once on day 2, because they touch nothing shared: one drafts the README and user-facing docs from the repo; the other reads every endpoint implementation and diffs it against the Phase 2 API contracts.
The diff produces the drift catalog: every difference between the contracts and the built system, each labeled by a human — intentional (the decision and its why get documented, the contract updated) or unintentional (a defect spec, into the loop, fixed before the phase closes). One row per drift: what the contract said, what the system does, the label, and the resolution. The catalog is reviewed with the client's lead engineer — the contracts are theirs after close.
Documenting the plan, not the build (transcribing the contracts) leaves the drift undetected and the docs lie from day one. Transcribing the code, bugs and all, faithfully documents the defects as features. The diff against the signed contracts is the only thing that makes drift visible — diff, never transcribe.
Specs changed in the same PR as behavior all through Build, so the contract diff finds almost nothing — and what it finds, it finds before deployment instead of after. A long catalog is a Build-quality finding, not a documentation chore.
The one idea this phase is built around
Prove the README by handing it to someone who has never seen the repo
A senior engineer can read a setup guide, nod, and approve it — and still be wrong, because they fill every gap with what they already know. The only honest test is to give the document to someone with no prior knowledge and watch them follow it, word for word, without help.
A person who has never touched the system follows the README exactly, on a clean machine, while the team watches in silence. Every place they stall — every assumed tool, every "wait, what's my…", every step they can't complete without asking — is a documentation defect, logged on the spot.
The defects get fixed the same day, and then the same person runs it again from step one, end to end. A partial re-run that starts at the broken step proves nothing about the steps above it.
"They managed with a little help" is a fail. The help is exactly the thing the client won't have after close.
Ines Roy — three weeks at Harbor, never opened the repo — was the week's most valuable contributor, precisely because the README is for her. She started at 9:00 with the pod silent.
The local-secrets bootstrap assumed a vault read permission that new Harbor engineers don't have by default. Nobody helped. The stall was the data.
A bootstrap script plus a documented access-request path (with a named approver) merged before lunch. The 11:30 re-run was clean, end-to-end, forty minutes.
The README failing on a new hire's permissions in week one of the close — instead of month one of ownership — is the phase doing its job.
Someone leans over the verifier's shoulder: "oh, you just need to…". The run is now void. The stalls are the data; helping erases the data.
Go deeper — the full method
On day 5, a client engineer who has never opened the repo follows the README exactly, on a clean machine (a fresh OS account or VM with none of the project's toolchain pre-installed — the verifier installs everything the README tells them to, and nothing it doesn't), while the pod watches without helping.
Every stall, every assumed tool, every "wait, what's my…" is a documentation defect, fixed the same day and re-run. A stall is any step the verifier cannot complete as written without information from outside the document — having to ask, guess, or go searching counts; a typo they can read past does not. The QE observes and logs each stall as it happens: the step number, what was missing, and what the verifier did instead. That log is the doc-defect list.
The re-run is the same verifier, from step one, end to end — a partial run that starts at the failed step proves nothing about the fixes upstream, and the verifier is still cold for every step they never reached. "They got through it with a little help" never counts as a pass.
Someone leans over the verifier's shoulder: "oh, you just need to…" The run is now void. Stalls are the data; helping erases the data. The pod stays silent.
Writing for the worst moment
The operations manual is written for someone exhausted, stressed, and new
The runbook's reader isn't a calm engineer at their desk. It's whoever is on call when something breaks — possibly seeing the system for the first time, mid-incident, at 3 a.m. Every procedure is written for that reader, or it isn't written at all.
Every procedure is numbered steps, exact copy-pasteable commands, an observable check after each one ("you should now see…"), and a recovery path if a step fails. The failure scenarios aren't imagined — they come from what the engagement actually learned: the constraints, the designed-in degradations, the near-misses from the build.
"See the wiki" and "ask the team" are banned strings. After close, there is no wiki to trust and no team to ask. If it isn't in the runbook, it doesn't exist.
Five failure scenarios, every one earned during the engagement — the nightly data-replica refresh window, a failed sync, a storm-surge queue (sized from a real 2024 catastrophe event), an AI-accuracy regression, and a bad deploy. The first scenario opens with the question a 3 a.m. responder actually needs:
"First question — what time is it? 02:00–04:30 Eastern: this is the replica's nightly refresh window. EXPECTED. Do nothing. Any other time: continue to step 1."
"See the wiki" and "ask the team" appear zero times. Each scenario also names the alert that should catch it — so when monitoring is configured later, the runbook and the alerts describe the same failures.
Go deeper — the full method
The reader of a runbook is exhausted, stressed, and possibly seeing the system for the first time, mid-incident. Every procedure is written for that reader: numbered steps, exact copy-pasteable commands, an observable check after each step ("you should now see…"), and a recovery path if the step fails.
The failure scenarios come from what the engagement actually learned: the constraints from Phase 0, the degradation behaviors designed in Phase 2, the incidents and near-misses from Build. Each scenario notes what Phase 9's monitoring should alert on — the runbook and the alerts must end up describing the same failures.
"See the wiki" and "ask the team" are banned strings. After close, there is no team to ask — every pointer to knowledge that lives outside the repo is a 3 a.m. failure deferred. Write it down or it doesn't exist.
Collecting the debt before the debtors leave
Sweep the build history for decisions nobody wrote down
During a long build, real decisions get made in passing — a dependency added, a pattern changed, an alternative rejected in a review thread. Each one that never got written down is tribal knowledge. And at close, the tribe leaves the building.
Claude does a read-only pass over the merge history and the spec library, looking for the hard-to-undo choices that never got a written decision record. Each candidate becomes a drafted record — context, options, decision, consequences — for humans to sign or strike.
This is debt collection, done while the people who made the choices are still in the room to confirm them. Anything found to be mere implementation detail is struck — and the fact that it was struck is itself recorded.
The sweep surfaced four candidates; the humans triaged them to two real ones:
The claim-document retention tiering — a storage choice made with Harbor's data lead in a review, irreversible after go-live, written down nowhere.
Both got context, options, consequences — and signatures from the people who'll live with them. The other two candidates were struck as implementation detail, recorded as struck. No decisions left undocumented.
The choices that live only in PR threads and pod memory walk out the door with the pod. Six months later the client hits one, asks "why is it built this way?", and there's no one left to answer.
Go deeper — the full method
On day 4, Claude's read-only sweep of the Build-era history surfaces candidate undocumented decisions. Humans triage — the Setup Owner with the client's lead engineer: each real one becomes an ADR — context, options, decision, consequences — co-signed by the client's lead engineer like every ADR before it. Open ADRs get closed as accepted or superseded.
This is debt collection. An unwritten decision is tribal knowledge, and at close, the tribe leaves. Anything found to be mere implementation detail is struck — and the fact that it was struck is itself recorded.
If the sweep dredges up a disagreement — a Build-era choice the client's engineer would not have signed — that is better surfaced now, in a room, than discovered after close. It gets an ADR with the disagreement recorded, or a re-opened decision, explicitly.
Build-era decisions that live in PR threads and pod memory walk out with the pod at close. The sweep and the signatures are the collection mechanism — do it while they're here.
How a phase actually ends
A gate, not a calendar — and the verification is the gate
The default week is five days, but the phase doesn't close because five days passed. It closes when a specific list is true and a named human on each side signs to advance. The teeth on that list are the cold runs — the things proven by use, not by reading.
Automated checks confirm the mechanical parts; people own the judgment. Gates report; humans decide. And because the gate is a billing milestone, an unmet teeth item isn't something the pod quietly absorbs — the phase doesn't close until it's true.
If the client can't free a genuinely-new verifier, you slip the gate rather than verify by reading — and you say so at steering. The verification isn't a step in the phase; it is the phase.
Both cold runs passed — Ines on the README after her clean re-run, Tom on the runbook after one rewrite (a scale-up step had assumed a subscription role the pod held and Harbor didn't). The gate passed; the sponsor signed at steering with one honest line on the record:
The full checklist — tick it:
- A client engineer new to the repo completed the README cold checkout exactly as written — observed, unassisted, on a clean machine
- The client's ops engineer executed a deploy, a rollback, and a failure scenario from the RUNBOOK, cold, with their own permissions
- The API docs match the implementation; the drift catalog is empty, or every open item has an owner and a next-phase decision
- No decisions left undocumented — the sweep ran and every significant build choice is recorded and co-signed
- The spec-library sample audit passed, or its mismatches became defects, now fixed
- Defects found by the cold runs are fixed and the failed run was re-run clean — "managed with a little help" is a fail
- The next-phase handoff exists: inventory, honest gaps, the deployment checklist, decision status
- A named human on each side has approved the move to the next phase
Go deeper — the full method
The default calendar is 5 business days. The first half drafts and diffs; the second half verifies by use and fixes what the verification finds. It stretches when the drift catalog is long or a cold run fails badly — both of which are the phase doing its job.
Phase 7 closes when all of these are true, verified at the gate:
- A client engineer new to the repo completed the README cold checkout exactly as written — observed, unassisted, on a clean machine (verification teeth)
- The client's ops engineer executed a deploy, a rollback, and at least one failure scenario from the RUNBOOK, cold, in the dev environment, with their own permissions (verification teeth)
- API documentation matches the implementation; the drift catalog is empty or every open item has an owner and an explicit Phase 8 blocker decision.
- No open ADRs; the decision sweep ran and every significant Build-era decision is recorded and co-signed.
- The spec library sample audit passed (or its mismatches became defect specs, now merged).
- Doc defects found by the cold runs are fixed and the failed run was re-run clean — "they managed with a little help" is a fail.
- The Phase 8 handoff exists: inventory, gaps, deployment checklist, ADR status.
- A named human on each side approved the advance — gates report, humans decide.
The bar is exact: a failed cold run is fixed and re-run clean, by the same verifier, from step one. If the client can't free the verifiers, slip the gate rather than verify by reading — and say so at steering. Because the gate is a billing milestone, an unmet teeth item is the client's problem to unblock, not the pod's to absorb.
Now watch the whole thing happen
The week, end to end
You've got the ideas; here's the actual rhythm at Harbor. The first half drafts and diffs; the second half verifies by use and fixes what the verification finds. The two streams — understanding the system and proving the docs — converge on Friday's cold runs. Step through it.
Decide who reads what, then trust-but-verify the specs
With the client in the room: who reads each document (their engineers, their ops, their users), what already exists and is current, what must be created. Then a sample of specs gets checked against live behavior — the pass that proves the specs really did stay current all through the build.
The README and the contract diff, at the same time
Two drafting streams run at once because they share nothing: one drafts the README and user-facing docs from the repo as it actually is; the other reads every endpoint and diffs it against the signed contracts. The diff produces the drift catalog — reviewed with the client's lead engineer, since the contracts are theirs after close.
Write for 3 a.m.
Every procedure as numbered steps, exact commands, an observable check, a recovery path. The failure scenarios come from what the engagement learned, not from a template's imagination. Each scenario names the alert that should catch it. "See the wiki" and "ask the team" are banned — after close, there's nobody to ask.
Collect the decision debt before the debtors leave
A read-only sweep of the build history surfaces choices that never got a written record. Humans triage each candidate: the real ones become signed decision records, co-signed by the client's lead engineer; the rest are struck as implementation detail. Any defect the documenting surfaced rides the fix loop the same day.
The cold runs, then a signature
A new engineer follows the README on a clean machine while the pod stays silent — every stall fixed and re-run. The ops engineer walks real procedures in the real environment with their own permissions. Then the automated gate, the next-phase handoff, and steering: the sign-off, the billing milestone, advance to Deployment.
Go deeper — the full method
The default calendar is 5 business days. The first half drafts and diffs; the second half verifies by use and fixes what the verification finds.
Day 1 — scope, inventory, and audiences. The documentation scope gets decided with the client before anything is written: who reads each document (their engineers, their ops, their users), what already exists and is current (the spec library, the ADR registry, the harness docs), what must be created (README, API docs, RUNBOOK), and any client documentation standards the deliverables must follow. The spec library gets a sample audit: the QE picks five to ten specs, weighted toward HIGH-risk and recently changed, and executes each spec's acceptance checks by hand against dev — the trust-but-verify pass that proves the construction held.
Day 2 — parallel drafts: the README and the contract diff. Two drafting streams run at once, because they touch nothing shared: one drafts the README and user-facing docs from the repo; the other reads every endpoint implementation and diffs it against the Phase 2 API contracts. The diff produces the drift catalog, reviewed with the client's lead engineer — the contracts are theirs after close.
Day 3 — the RUNBOOK, written for 3 a.m. Every procedure for that reader: numbered steps, exact copy-pasteable commands, an observable check after each step, a recovery path. The failure scenarios come from the engagement's own history; each notes what Phase 9's monitoring should alert on. "See the wiki" and "ask the team" are banned strings.
Day 4 — the decision sweep. Claude's read-only sweep surfaces candidate undocumented decisions. Humans triage: each real one becomes an ADR, co-signed by the client's lead engineer; open ADRs get closed as accepted or superseded. Any defect the documenting surfaced rides the fix loop.
Day 5 — verified by use, then the gate. The cold checkout (a client engineer who has never opened the repo, clean machine, pod silent) and the cold walk-through (the ops engineer running real RUNBOOK procedures in dev with their own permissions). The QE stages the failure scenario in dev ahead of time and hands the ops engineer only the symptom. Defects fixed and re-run clean. Then the automated gate check, the Phase 8 handoff (inventory, honest gaps, the deployment checklist, ADR status), and steering: the sign-off, the billing milestone, advance to Deployment.
A long drift catalog is a Build-quality finding, not a documentation chore — the phase holds until each open item has an owner and a Phase 8 blocker decision. A cold checkout that fails early and often is the test working; budget a re-run. The client can't free the verifiers → the verification is the phase, so slip the gate rather than verify by reading.
How it goes wrong
The failure modes, and the defense against each
Every one of these has happened to someone. Knowing them by name is half the defense — and Harbor's structure caught one of them in the act.
| The trap | What it looks like | The defense | At Harbor |
|---|---|---|---|
| Verified by reading | Someone senior reads the README, nods, approves it | Reading checks prose; only use checks truth. The cold run is the phase — protect it. | Ines ran it cold; step 4 failed under observation |
| The helpful cold run | "Oh, you just need to…" leaned over the verifier's shoulder | Stalls are the data; helping erases the data. The pod stays silent. | Pod silent; the stall was logged, not solved |
| Documenting the plan | API docs transcribed from the old contracts, never checked against the code | Diff, never transcribe. The contract diff is what finds drift. | Diff caught both drifts before deployment |
| Transcribing the code | Docs generated from the implementation, bugs documented as features | Diff against the signed contracts; that's what makes a defect visible. | The bare-500 defect surfaced and got fixed |
| "See the wiki" | Pointers to knowledge that lives outside the repo | The 3 a.m. reader has nobody to ask. Write it down or it doesn't exist. | Banned strings appeared zero times |
| Decision debt walking out | Build-era choices that live only in PR threads and memory | The sweep plus signatures is the collection mechanism — do it while they're here. | Two records signed; two struck on purpose |
| The documentation fork | A shiny new "system specification" duplicating the specs | Two sources of truth means one starts lying. Consolidate and point. | No fork — the specs stayed the truth |
Go deeper — the full method
- Verified by reading. Someone senior reads the README, nods, approves. Reading checks prose; only use checks truth. The cold run is the phase — protect it.
- Documenting the plan, not the build. API docs transcribed from the Phase 2 contracts instead of diffed against the code. The drift goes undetected and the docs lie from day one. Diff, never transcribe.
- Transcribing the code, bugs and all. Docs generated from the implementation with no contract comparison faithfully document defects as features. The diff against the signed contracts is what makes drift visible.
- "See the wiki." Every pointer to knowledge outside the repo is a 3 a.m. failure deferred. The runbook reader has nobody to ask — write it down or it doesn't exist.
- The helpful cold run. Someone leans over the verifier: "oh, you just need to…" The run is now void. Stalls are the data; helping erases the data.
- ADR debt walking out the door. Build-era decisions that live in PR threads and pod memory. At close, that memory leaves the building. The sweep and the signatures are the collection mechanism.
- The documentation fork. A shiny new "system specification" duplicating what the specs already say. Two sources of truth means one is lying within a quarter. Consolidate and point; don't fork.
- Treating the phase as a formality. It's "just docs" until the client's on-call engineer is alone with the system. In a consulting engagement, this phase is the product the client keeps.
When Phase 7 is done
The proof is the deliverable
Documentation doesn't close because the documents read well. It closes because a stranger ran the system from them — a newcomer set it up cold, an ops engineer operated it cold, every difference between the docs and the code is explained or fixed, and every decision is written down and signed. That's a handoff the client can actually live with. Where to go next: