PlatformEngr® Platform fundamentals course

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.md and plan/90-days.yaml pass the check. Your own docs/adr/0002-*.md is merged through a pull request with a green check. Every part of the design passes npm 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

FileRefers toChecked by
platform.yamlthe owner in teams.yamlT5
capabilities.yamlowners in teams.yamlO1
golden-paths/new-service.yamlcapabilities; AGENTS.mdG2, G5
agents/policy.yamlcapabilities; the agent user in platform.yamlA2, A4
metrics/scorecard.yamlowners; a cost metric because agents have budgetsO1, M4
plan/90-days.yamlcapabilities and paths it builds; metrics it exits on; the ADRN2, N3, N4

Files to know

Open them in your editor or on GitHub; the bullets say what to look at.

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:

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 N3 of 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

  1. 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
  2. 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
  3. 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
  1. 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.
  2. 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.
  3. A date shows only that time passed; a result shows the phase did its job, and the date stays in the plan anyway The days field 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.

Report a problem with this module