# Decisions & retrospectives

Keep durable reasoning and use session evidence to propose a small environmental improvement.

## Why are we debating the same choice again?

A fresh session finds a cache but no explanation for its five-minute lifetime. It changes the lifetime to a day, and an old problem returns. Code reveals the implemented choice; the constraints behind it may be missing.

Other costs live outside the code: following obsolete instructions, searching the wrong documents and repeating manual checks. This lesson preserves durable reasoning and turns session evidence into one testable environmental improvement.

> Code is the materialized view of all the decisions made
>
> — Matt Pocock, [source](https://x.com/mattpocockuk/status/2107560148243812772), 2026-10-06

## Use an ADR for a decision that still needs explaining

Record context, choice, rationale, consequences and status in an architecture decision record. Manage temporary execution steps separately. When a decision changes, identify its replacement so a reader can distinguish historical reasoning from the current agreement.

Figure: An ADR preserves context, choice, rationale, consequences and status. ([s12-adr-fields](/art/s12-adr-fields.en.svg))

- **Context and choice** What constraints mattered, and what was selected?
- **Rationale and consequences** What alternative was set aside, and what cost was accepted?
- **Status** Is this current, undecided or superseded by a named record?

This field list is ours. Use the team's review and change process to maintain it; another person's committing habits are not a requirement. Update durable reasoning separately from current task progress.

## Start a retrospective with observed evidence

`/retro` examines real sessions and review feedback: slow document discovery, stale references, missing tools and missing checks. Successful delivery can still contain expensive detours, so inspect successful sessions too.

Figure: Use session evidence to propose a small improvement for human confirmation. ([d12-retro-flow](/diagrams/d12-retro-flow.en.svg))

Connect each observation to a minimal improvement and a way to verify it. A person confirms the change before it becomes policy. Prefer repairing navigation or a definite check when that addresses the evidence.

## A glossary needs an active checking step

A business term may name different things for different readers. Record its meaning, confusing alternatives and relationships. Then check a ticket or report against those entries. A general request for consistent language gives no observable result by itself.

Matt withdrew one experiment with a passive style instruction. That does not establish that all writing requirements fail. Identify a real ambiguity, name the terms to check and compare how readers understand the revised text.

## Exercise: produce a record and a proposal

### Explain the cache and repair the route to its documentation

- Fictional site example: a session read an obsolete interface guide; two failed runs preceded discovery of the current guide.
- Confirmed decision: status may lag by at most five minutes, so cache for five minutes and accept more requests.
- Task: Write a five-field ADR, then propose one retrospective improvement and its verification.

Suggested approach: Record the latency constraint, five-minute choice, rationale, request cost and current status. Propose redirecting the status-interface pointer after human confirmation and marking the old guide superseded. Ask a fresh session to locate the interface and observe whether it reaches the current guide directly.

> **Our inference**
> Our suggestion: change one evidenced obstacle, then observe a similar task. Define a shorter route as locating the current reference; a shorter conversation alone does not establish improvement.

## Done means both outputs can be assessed

The ADR explains an accepted cost and identifies its status and replacement, if any. The proposal points to session evidence, a minimal change, a confirming person and a verification action. An unapproved proposal remains a proposal.

For a lasting rule, use [standards and checks](/en/standards-and-checks) to choose where it should run.

## Quick reference

- **ADR** Keep durable context, choice, rationale, consequences and status.
- **Retrospective** Evidence → minimal improvement → verification → human confirmation.
- **Glossary** Define the language and check real documents against it.

## Sources

- Matt Pocock, [code and decisions](https://x.com/mattpocockuk/status/2107560148243812772), 2026-10-06.
- Matt Pocock, [retro prompt](https://x.com/mattpocockuk/status/2105951409887949107), 2026-10-02; independently interpreted.
- Matt Pocock, [withdrawn style experiment](https://x.com/mattpocockuk/status/2085681281795232026), 2026-08-07; independently interpreted.
- The ADR fields, development record and answer are ours. [Copyright details](/en/about-and-copyright).

Unofficial, non-commercial study notes, with no affiliation with or endorsement by Matt Pocock. Quoted works belong to their authors; MIT reuse carries separate copyright and licence notices.

The diagram CSS on this page is adapted from Archify (https://github.com/tt-a1i/archify) under the MIT licence; the complete licence follows.

### Full licence: Archify (tt-a1i/archify)

```text
MIT License

Copyright (c) 2026 tt-a1i (Archify)
Copyright (c) 2025 Cocoon AI

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```