Module 07 · Prove it · 35 min · You are: Platform team
Capstone: the first decision and the first 90 days
In this module
- You learn: How to record a decision so the next person knows why (an ADR with the options considered), and how to plan a platform's first 90 days in three phases that each end on a measured result, not a date.
- You do: Write the decision behind the first golden path and the 90-day plan that follows from it. Try a plan that ends on dates, and fix it. Then write ADR 0002 for a real decision in your own company, open it as a pull request and see the check pass there.
- You end with:
docs/adr/0001-first-golden-path.mdandplan/90-days.yamlpass the check. Your owndocs/adr/0002-*.mdis merged through a pull request with a green check. Every part of the design passesnpm run check.
Six months from now someone will ask why the platform team built a golden path before a portal or a database. Without a record, the answer is "we thought it was best", and the decision gets made again. An architecture decision record keeps the context, the options and the consequences next to the code. Michael Nygard, 2011 proposed the format: a title, context, decision, status and consequences; this course adds the options considered, because a decision with one option was not a decision. The plan then turns the decision into three phases, each ending when a metric from the scorecard says so.
Open this module in the interactive course to track progress.
Concepts
- Architecture decision record
- A short file per decision: context, options considered, the decision, its status and its consequences. Numbered, never rewritten: a new ADR supersedes an old one.
- Options considered
- At least two real options, including the one not taken. It shows the reader what was weighed, and lets them reopen the decision if the context changes.
- See it, pave it, prove it
- Three phases of 30 days: measure what exists, build the first path, show the result. This course's pattern for a first quarter.
- Exit on a result
- A phase ends when a metric says it has done its job (a baseline published, a team shipping alone), not when the calendar says so.
- Maturity is a direction
- The CNCF Platform Engineering Maturity Model describes four levels (provisional, operationalized, scalable, optimizing) across investment, adoption, interfaces, operations and measurement. Ninety days moves one step, not four.
How the files you wrote connect
| File | Refers to | Checked by |
|---|---|---|
platform.yaml | the owner in teams.yaml | T5 |
capabilities.yaml | owners in teams.yaml | O1 |
golden-paths/new-service.yaml | capabilities; AGENTS.md | G2, G5 |
agents/policy.yaml | capabilities; the agent user in platform.yaml | A2, A4 |
metrics/scorecard.yaml | owners; a cost metric because agents have budgets | O1, M4 |
plan/90-days.yaml | capabilities and paths it builds; metrics it exits on; the ADR | N2, N3, N4 |
Files to know
Open them in your editor or on GitHub; the bullets say what to look at.
docs/adr/0001-first-golden-path.md(reference, your repo): The decision behind the first golden path.plan/90-days.yaml(reference, your repo): The first 90 days.
Steps
1. Write the decision
Why the first thing to build is a golden path with team-checkout, and not a portal or a database.
cd ~/platformengr/platform-design
Create docs/adr/0001-first-golden-path.md
# ADR 0001: The first golden path is a new HTTP service, built with team-checkout
Status: accepted
Date: 2026-11-15
Owner: platform team
## Context
New services wait about two weeks for a namespace, a pipeline and DNS, through four tickets (platform.yaml,
product-developer). Coding agents guess how to build and deploy each repo. Team-checkout starts two new services
next quarter and has asked for help. The platform team has three engineers and one product manager.
## Options considered
- A developer portal first, with a page for every existing ticket. Visible, but the tickets stay behind it.
- A golden path for a new HTTP service, built in collaboration with team-checkout, with AGENTS.md in the template.
- A managed Postgres service, the second most requested item. Useful, but no new service needs it on day one.
## Decision
Build the `new-service` golden path first, together with team-checkout, until they ship a service on it without
help. Then the interaction becomes X-as-a-Service. The portal shows the path; it does not replace it.
## Consequences
- Postgres stays planned for this quarter. Teams that need one now keep using the ticket.
- The platform team spends about half its time with team-checkout until 2027-02-28.
- Success is measured by path adoption and lead time in metrics/scorecard.yaml.
Expect ok docs/adr/0001-first-golden-path.md. The check looked for the four sections, the status line and at least two options.
npm run check
2. Write the 90-day plan
Three phases. Each item that builds something names the capability or path from your map; each phase ends on a metric from your scorecard.
Create plan/90-days.yaml
# The first 90 days: see it, pave it, prove it. Each phase ends on a measured result.
# Owner: the platform team; agreed with leadership. Read by the design check (rules N1 to N4).
decisions:
- docs/adr/0001-first-golden-path.md
phases:
- name: See it
days: 0-30
items:
- t: List the AI tools, agents and MCP servers in use, and who owns each
- t: Measure lead time, recovery time and time to first review for every team
- t: Label AI-assisted pull requests, so their change fail rate can be compared
- t: Publish the agent policy, with default deny
builds: [agent-identity]
exit:
metric: lead-time
when: The baseline is measured for every team and published
- name: Pave it
days: 31-60
items:
- t: Build the new-service path with team-checkout
builds: [new-service, repo-template]
- t: Put AGENTS.md and skills into the template
builds: [agent-instructions]
- t: Give the checkout coding agent its own identity and scoped access
builds: [agent-identity]
exit:
metric: path-adoption
when: Team-checkout ships its first new service on the path without help
- name: Prove it
days: 61-90
items:
- t: Report outcomes and cost per change to leadership
builds: [cost-report]
- t: Fix the flakiest tests first, because they block people and agents alike
builds: [ci-pipeline]
- t: Compare the change fail rate of AI-assisted changes with the rest
exit:
metric: change-fail-rate
when: Reported for one full month, with a decision on wider agent access
Run the check. Expect eight lines of ok and All checks passed.: the whole design, every file referring correctly to the others.
npm run check
git add -A && git commit -qm "ADR 0001 and the 90-day plan" && git push -q
gh run list --workflow design-check --limit 1
3. Capstone: a decision of your own (Challenge)
Think of a real platform decision your own company faces or made recently: a first golden path, build or buy, which team to start with, whether agents may deploy. Write it as ADR 0002, in your own words, on a branch. No copying from the reference: there is no ADR 0002 there.
Done when:
docs/adr/0002-<your-title>.mdexists on a branchadr-0002, with a#title, aStatus:line and the sections Context, Options considered (at least two options), Decision and Consequences.- The context names a user problem you could find evidence for, and at least one consequence says what gets worse.
- If the decision changes the design (a new capability, an agent permission, a metric), the matching file is changed in the same branch.
npm run checkprintsAll checks passed.on your laptop.
4. Open it as a pull request
The way a platform team changes its design: a pull request, the check on it, a review, a merge.
git switch -c adr-0002
Write your ADR now, in your editor, then commit it to the branch:
git add -A && git commit -qm "ADR 0002" && git push -qu origin adr-0002
Open the pull request. --fill uses your commit message as the title.
gh pr create --fill
Wait for the check on the pull request. Expect design-check with pass:
gh pr checks --watch
Ask a colleague to read it before you merge, if you can. Then merge it and go back to main:
gh pr merge --squash --delete-branch && git switch main && git pull -q
Simplified for the course
One ADR and one plan. A platform team writes an ADR for every decision that would be expensive to reverse, and reviews the plan every month.
The plan is a file. Most teams track the items in their usual backlog and keep this file as the agreed shape of the quarter.
You reviewed your own pull request. In a team, the design repo requires a review from the platform's product owner and from a user team.
Break it on purpose: A plan that ends on dates
Leadership wants dates. You rewrite the first phase's exit as a calendar date, so the plan fits the quarterly report.
You practise: turning a deadline into a result you can show, while still giving leadership a date.
1. Break it
Change in plan/90-days.yaml
- exit:
- metric: lead-time
- when: The baseline is measured for every team and published
+ exit:
+ when: 2026-12-15
npm run check
2. What you see
Expected: ok plan/90-days.yaml. You get: FAIL and a line with [N3] naming See it.
3. Fix it yourself
Give the phase back an exit that a metric from the scorecard can confirm. Done when the check passes and you can tell leadership both when the phase should end and how they will know it did.
Hint 1
On 2026-12-15, how would anyone know whether "See it" had done its job?
Hint 2
The phase measures baselines. Which metric's baseline does the plan wait for, and what result ends the phase?
The fix
The days field already gives leadership the date: days 0 to 30. The exit says how they will know it is done, which is what they need to decide on the next phase.
Change in plan/90-days.yaml
- exit:
- when: 2026-12-15
+ exit:
+ metric: lead-time
+ when: The baseline is measured for every team and published
npm run check
git add -A && git commit -qm "Phase one ends on a measured result" && git push -q
After you fixed it: the five questions
- What failed?
- The plan. A phase could end on time without having done anything.
- How was it detected?
- By rule
N3of the check. - Who responds?
- The platform's product owner.
- How is it corrected?
- Keep the days for the calendar; put a metric and a result in the exit.
- How is it prevented?
- Review each phase at its exit result, and report the result with the date.
Quiz
- What does an ADR's "Options considered" section add?
- A list of tools to evaluate during the next quarter
- A record of what was weighed, so a later reader can tell whether the decision still holds when the context changes
- The approvals the decision needs before it can be accepted
- An old ADR no longer fits. What do you do?
- Write a new ADR that supersedes it, and mark the old one superseded
- Edit the old ADR so it describes the new decision
- Delete the old ADR so nobody follows it by mistake
- Why should a 90-day phase exit on a metric rather than a date?
- Metrics are easier to put into a quarterly report than dates
- Leadership is not interested in dates
- A date shows only that time passed; a result shows the phase did its job, and the date stays in the plan anyway
Answers
- A record of what was weighed, so a later reader can tell whether the decision still holds when the context changes Nygard's format has context, decision, status and consequences; options make the trade-off visible.
- Write a new ADR that supersedes it, and mark the old one superseded ADRs are a history: the old context explains why the old decision was right then.
- A date shows only that time passed; a result shows the phase did its job, and the date stays in the plan anyway The
daysfield keeps the calendar; the exit keeps the purpose.
Field note
The ADR I go back to most often is one where we chose not to build a portal yet. Two years later a new CTO asked why we had none. The ADR answered in a page, and it also told us the condition had changed, so we wrote the one that superseded it.