Notes
The Notes section is the informal layer of this operations manual — a place for architecture reviews, decision records, working notes, and anything that captures important thinking that doesn't fit neatly into the structured sections above.
If the rest of this manual is the "what" and the "how", Notes is the "why".
What Belongs Here
| Type | Examples |
|---|---|
| Architecture Decision Records (ADRs) | Why we chose Cyrus over MediatR, why we use Dapper for reads, why Cloudflare Pages instead of Azure Static Web Apps |
| Architecture reviews | Periodic reviews of the system design — what's holding up well, what needs revisiting |
| Post-incident notes | What broke, why, how we fixed it, what we changed to prevent it — written after a production incident |
| Research & evaluation notes | When we evaluated multiple options before making a decision — e.g. Ollama evaluation, database provider comparison |
| Working notes | Thinking-in-progress that hasn't become a formal decision yet |
| Session notes | Key decisions made during development sessions that need to be preserved |
What Does Not Belong Here
Notes is not a dumping ground. If something belongs in a structured section — a runbook in Infrastructure, a coding pattern in Development, a brand decision in Design — put it there. Notes is for context and decisions that don't fit anywhere else.
How to Write a Good Note
Date it. Context decays fast. A note without a date is hard to interpret six months later.
State the decision clearly. "We decided to use X" is more useful than three paragraphs of deliberation with no clear conclusion.
Capture the alternatives considered. The value of a decision record is understanding what was rejected and why — not just what was chosen.
Note what might change it. If you know the decision might be revisited under certain conditions ("if we ever exceed 10,000 tenants, revisit this"), write that down.
Current Notes
| Note | Date | Summary |
|---|---|---|
| Architecture Review | 2026 | System architecture review — design decisions, trade-offs, and areas for future improvement |
Adding a New Note
- Create a markdown file in
docs/roundtrip/notes/ - Add it to
sidebars-roundtrip.tsunder the Notes category - Use the date in the filename if it is time-specific:
2026-07-incident-graph-api.md - Follow the structure above — date, decision, alternatives, conditions for revisiting
:::tip Post-Incident Notes After any production incident, write a brief note here while the details are fresh. Even a short paragraph covering what broke, why, and what changed is valuable. The Graph API / Entra tenant migration incident from July 2026 is a good example of the kind of institutional knowledge that belongs here. :::