6.4 Documentation, Implementation Guidance & the Lifecycle Loop

By this point in an engagement you've run discovery, framed the tradeoffs, and set an SLA the architecture can actually meet. You understand the design completely — you built it. And that's precisely the danger of this next step, because the design that lives in your head, fully understood, is not the same artifact as the design a different team can pick up and build. Everything you didn't write down is a decision someone else will have to either re-derive from scratch or, worse, silently reverse without realizing why it was there.

This is the moment the lifecycle calls HANDOFF — transferring the design, with documentation and implementation guidance, to whoever builds and runs it next. And handoff succeeds or fails almost entirely on the quality of what you write down here. A brilliant design with thin documentation is, from the implementation team's point of view, indistinguishable from a mediocre one: they can't tell the difference between a subtlety you deliberately engineered and an arbitrary choice, because you didn't record which was which.

An architecture document has four jobs, and skipping any one of them leaves a gap the implementation team will eventually fall into. It describes the COMPONENTS — the pieces of the system and how they connect. It traces the DATA FLOW end to end: input, processing, output, and feedback — the same shape a monitoring dashboard will eventually need to instrument. It records the PATTERNS chosen — the specific architectural approach selected, which implicitly flags the alternatives that were considered and set aside. And it captures the WHY behind each decision: which tradeoff, from Lesson 6.2, that choice was actually serving.

That last item — the why — is the one people skip under deadline pressure, and it's the one that costs the most later. A decision log that records only WHAT was chosen, without WHY, looks arbitrary the moment someone unfamiliar with the original constraints reads it six months on. Imagine a future maintainer finds "model tier: mid-size" in the document with no explanation, and — under pressure to cut costs — swaps it for the cheapest available tier. If the rationale had been recorded ("mid-size chosen to keep p95 latency under the SLA with reranking enabled"), they'd know exactly what they were risking. Without it, they find out the hard way, in production, when the SLA breaks. Recording rationale isn't extra diligence, it's the thing that makes a decision safe to revisit at all.

Recording rationale alongside a decision, as the previous section established, is the right instinct -- but "record the why" is still vague enough that two architects following the same advice can produce documentation of wildly different quality. One writes a genuine paragraph of reasoning; another writes "chosen for performance reasons" and calls it done, technically satisfying the instruction while providing almost none of its value. What's needed is a concrete, checkable structure: a fixed set of fields that, filled in for every architectural decision, produces documentation that actually survives someone else using it later.

This is a genuine enhancement over documenting "the why" as a single free-text field: it forces the documentation to separate WHAT WAS CHOSEN from WHAT WAS REJECTED AND WHY from THE TRADEOFF from WHO'S ACCOUNTABLE from WHAT EVIDENCE BACKS IT UP -- five distinct pieces of information a single "rationale" paragraph tends to blur together, often omitting one or two of them entirely without the author even noticing, because a paragraph doesn't have empty boxes that visibly need filling the way a checklist does.

All six fields exist to pass one specific test, and the test itself is the more important thing to internalize: COULD SOMEONE WHO NEVER SAT THROUGH THE ORIGINAL DESIGN DISCUSSION READ THIS AND MODIFY THE SYSTEM WITHOUT INTRODUCING A REGRESSION? This reframes documentation quality away from "did we write enough words" and toward "does this actually transfer the knowledge a stranger needs." A document that's long but missing the rejected alternatives, or missing who owns the decision, or missing any evidence beyond "it works," fails this test regardless of its word count -- and a document that's short but hits all six fields for the decisions that actually matter can pass it.

Each field earns its place by closing a specific failure. Without REJECTED ALTERNATIVES, a future maintainer re-proposes an option that was already tried and discarded, wasting time re-litigating a settled question. Without the TRADEOFF stated explicitly, a maintainer sees only the chosen path and has no way to judge whether the tradeoff still holds once circumstances change. Without an OWNER, there's no one to ask when a question the document doesn't answer comes up, and no accountability if the decision turns out to have been under-scrutinized. Without an EVIDENCE ARTIFACT, "it was the right call" is an assertion with nothing behind it -- indistinguishable from a guess dressed up as a decision. And without AUDIT-READY STATUS as an explicit check, a document can look complete to its author, who has all the missing context in their head, while being genuinely unusable to anyone else -- exactly the failure mode the whole discipline of documentation exists to prevent.

A future maintainer reading the six-field version can verify the choice, understand exactly what would need to change to justify revisiting it, and knows who to ask if something's still unclear. The weak version offers none of that -- it's a decision log entry with a vague half-sentence of rationale, no named alternative, no owner, no evidence, and it fails the completeness test the moment anyone outside the original conversation tries to use it.

Documentation describes the design; implementation guidance is a separate, more concrete layer that lets a team actually BUILD it without re-deriving anything. Think of documentation as the blueprint and implementation guidance as the materials list and assembly instructions — related, but genuinely different artifacts, and a handoff that has only one of them is incomplete.

Concretely, implementation guidance means: pinned model versions (not "the current Sonnet model" but the exact version string, so behavior doesn't silently shift under the team); prompt or Skill structure (the actual templates and organization, not just "use good prompts"); integration protocols (how components actually talk to each other — MCP servers, APIs, message formats); retrieval configuration (chunking strategy, embedding model, top-k, reranking settings); guardrails (the safety and correctness checks in place); and eval/monitoring setup (what gets measured, how often, against what bar). An implementation team handed this layer can start building on day one. An implementation team handed only prose documentation has to reconstruct all of this from scratch — burning time, and risking a reconstruction that doesn't match what you actually intended.

• •Pinned model versions — exact version strings, not "whichever is current"
• •Prompt / Skill structure — the actual templates and their organization
• •Integration protocols — how components communicate (MCP, APIs, message formats)
• •Retrieval configuration — chunking, embedding model, top-k, reranking settings
• •Guardrails — the safety and correctness checks in place
• •Eval / monitoring setup — what's measured, how often, against what bar

Handoff feels like an ending — you've documented everything, the team has what they need, the engagement's design phase is complete. It is exactly that feeling that Task Statement 6.5 exists to correct. An architect's job doesn't end at handoff; it continues across five named phases, and the crucial mental model is that these phases form a LOOP, not a one-directional pipeline that terminates once the design ships.

The five phases, and what each one requires from the one before it: DISCOVERY elicits and validates requirements and constraints (Lesson 6.1). DESIGN chooses patterns, models, integration, and governance, and documents the tradeoffs (Lesson 6.2). HANDOFF transfers the design with documentation and implementation guidance (this lesson, 6.4.1–6.4.3). MONITORING ensures observability and evaluation are actually in place, and watches quality, latency, and cost against the SLA (Lesson 6.3). ITERATION feeds what monitoring and stakeholders report back into design, closing the loop.

Look at how each phase actually depends on the one before it: design depends on discovery's agreed outcome and constraints; handoff depends on design's documentation and rationale; monitoring depends on handoff having included observability and eval setup in the first place; iteration depends on monitoring surfacing real signal, plus the stakeholder feedback loop from Lesson 6.3. Skip a phase, or do it poorly, and every phase downstream inherits the gap.

There's one mistake the lifecycle-loop model exists specifically to prevent, and it's the most-tested idea in this lesson: treating design as finished once handoff is complete. It's an understandable instinct — handoff feels like the finish line, and closing out an engagement is satisfying. But three forces guarantee that a shipped design will need attention again: non-determinism (the system's own probabilistic nature, from Lesson 6.3), model updates (providers ship new versions with different behavior and cost profiles), and data drift (the real-world data flowing through the system changes as the business changes). None of these pause just because you've moved on to the next engagement.

The exam scenario that tests this directly: monitoring reveals that latency has crept past the agreed SLA after a data-volume increase. What should happen? Not nothing — "the design was signed off at handoff" is exactly the trap. Not disabling monitoring to silence the alert — that doesn't fix anything, it just makes you blind to a real problem. Not an unrelated technical tweak grabbed at random. The correct move is to feed the finding back into ITERATION and re-align expectations with stakeholders — precisely the loop this lesson has been building toward, and precisely the proactive-communication habit from Lesson 6.3.3.

This closes the loop on Domain 6 itself, in a fitting way: discovery (6.1) produced the agreed outcome, tradeoff framing (6.2) and SLA-setting (6.3) turned it into commitments, documentation (6.4) made those commitments buildable — and now the lifecycle loop insists that none of it is ever really finished. The architect who keeps the loop turning, rather than walking away at handoff, is the one whose systems stay trustworthy years after the first design review.

You now have the full documentation-and-lifecycle toolkit: what an architecture document must cover, why rationale specifically is non-negotiable, the six elements of implementation guidance, the five-phase loop, and the classic "design is done at handoff" trap. The exercise turns this into a handoff package and a lifecycle response you can reuse.

That closes Domain 6. You've moved from eliciting a business outcome, through framing its tradeoffs and setting an honest SLA, to documenting the design and recognizing that the whole engagement is a loop rather than a line. Every one of these skills earns its 14% weight by protecting the same thing: a stakeholder's ability to trust that what you build will do what you said it would.