Capture reasoning durably, navigate it at any altitude, communicate it without synthesis overhead.
Maintain two separate systems.
Thinking notation captures reasoning — decisions, tradeoffs, constraints, consequences, value, evidence. It answers why the work has the shape it has and whether it is delivering what was intended. It remains alive after the work closes and evolves through amendment, not deletion.
Work scope captures execution — epics, issues, tasks, milestones. It answers what to do and tracks whether it happened. It closes when the work closes.
These systems reference each other. Neither contains the other. Writing reasoning inside work artifacts and losing it when tickets close is the failure mode this framework prevents.
The capture test is handoff-readiness. If a piece of reasoning would be lost when an initiative changes hands — the why behind a decision, the value proposition, the constraints that shaped the system — it needs notation. If it is already preserved in durable form elsewhere (a commit, a ticket system, a shared platform's own documentation), a reference is sufficient. Do not duplicate; do reference with a "so what" sentence when the significance is not self-evident.
Thinking notation is orthogonal to work process. It is compatible with any execution method.
Organize thinking notation by altitude, not by topic.
Altitude is determined by blast radius and reversibility. The same subject requires different treatment at each altitude. An artifact that tries to serve multiple altitudes serves none of them well.
| Altitude | Audience | Question answered | Reversibility |
|---|---|---|---|
| Mandate | Leadership, self | What scope of concern is this and why is it coherent | Foundational |
| Value | Stakeholders, leadership | Why does this exist, for whom, and is it delivering | Very expensive |
| Principles | Anyone | What do we not compromise | Nearly none |
| System boundary | Executive, stakeholders | What are the major components and where do they stop | Very expensive |
| Integration | Engineering leadership | How do components communicate | Expensive |
| Operational | Engineers | How does it run and fail | Moderate |
| Implementation | Engineers | What specific tools and patterns | Cheap |
Higher altitude decisions constrain lower altitude decisions. Document downward from mandate. Each layer narrows the solution space for the layer below.
Some decisions straddle two altitudes. When this happens, place the artifact at the higher altitude. It is cheaper to discover an artifact is more detailed than expected than to discover it exists somewhere below where you looked.
The framing artifact for the entire notation system. It answers: what scope of concern does this system of reasoning cover, and why is that scope a coherent whole rather than unrelated parts.
A mandate changes very rarely. It is not a decision record — it is the context that makes all decision records legible. It is the preamble, not a layer. One per thinking notation system, and optionally one per initiative when the initiative's scope warrants its own framing.
The atomic unit of the thinking notation system.
Altitude: Value | Principles | System boundary | Integration | Operational | Implementation
Status: Proposed | Accepted | Superseded by DR-XXX | Dormant | Archived
Context: What forced a decision here.
Decision: What was chosen.
Consequences: What this enables and constrains downstream.
Reviewed:
YYYY-MM-DD Reviewed against DR-XXX, remains valid.
YYYY-MM-DD Reviewed against DR-XXX, superseded — see DR-YYY.
Decision records do not get deleted. When reasoning changes, write a new record that supersedes the old one. The history of reasoning is preserved. The current truth is findable. This is the amendment model.
Two relationships exist between decision records:
- Supersession is temporal. "This replaces that because our reasoning changed." Expressed in the status line.
- Constraint is structural. "This is bounded by that because a higher-altitude decision narrows the solution space." Expressed in the context block: "Constrained by DR-XXX."
The Reviewed log at the bottom of a decision record captures confirmations — moments when the record was evaluated against new context and found still valid. This prevents the failure mode where readers encounter an old record and cannot tell whether it accounts for recent changes. Reviewed entries are append-only.
The depth of a decision record should match the blast radius of the decision. A nearly-irreversible system boundary decision warrants full treatment with multiple options documented. A cheap implementation choice may warrant a single paragraph or none at all.
Decision records exist at every altitude from Value through Implementation. A decision about which use cases to pursue is a value-altitude decision record. A decision about a retry policy is an operational-altitude decision record. Same format, different weight.
The continuous capture stream. This is where reasoning lives before it has earned a decision record — and where the thousand small observations land that may never become decisions but inform them.
Working notes are append-only and timestamped. They are not edited after the fact. They are not polished. Their purpose is to externalize thinking at the speed it occurs so that it is available later when a decision crystallizes.
A working note entry needs only three things: a date, what altitude it concerns, and the thought. No other structure is required. When a working note entry or cluster of entries matures into a decision, it feeds a decision record. The working note is the raw material; the decision record is the refined output.
Working notes exist at every altitude. At value altitude, they capture realization evidence — observations about whether value propositions are landing, who is being served, what impact is visible. At mandate altitude, they often take the form of an impact journal — evidence that the scope of concern is delivering value across its constituent initiatives: people enabled, practices adopted, platforms leveraged, influence radiated. At implementation altitude, they capture technical observations and spikes. Same artifact type, different content.
Working notes are scoped to an initiative or to the system generally. They accumulate continuously.
Problem framing at value altitude. A pitch captures:
- The friction and who bears it
- The outcome if the friction is resolved
- The appetite — how much this is worth, stated as a constraint, not an estimate
- The approach at sketch resolution
- What is explicitly out of scope
A pitch is a decision about whether to bet on an initiative. It lives independently of the work it may authorize.
The system mental model at stakeholder and engineering altitude. Two levels are sufficient for most systems:
Level 1 shows the system, its users, and its external dependencies. One diagram, no jargon, any audience.
Level 2 shows the major deployable components and how they communicate. For engineers and technical stakeholders.
Each non-obvious boundary or communication choice links to a decision record. The diagram is the map; the decision records are the rationale for the borders.
Every artifact in the thinking notation system has a lifecycle state.
| State | Meaning |
|---|---|
| Active | Current truth. This artifact reflects live reasoning. |
| Dormant | Not currently relevant but not wrong. The initiative paused, the context shifted, the decision hasn't been tested yet. |
| Superseded | Replaced by a newer artifact. The link to the successor is in the status line. |
| Archived | The system, initiative, or context this artifact described no longer exists. Retained for historical reasoning. |
Lifecycle transitions are captured in the artifact itself — a status line change with a date and one sentence of why. This is lightweight but prevents the slow accumulation of artifacts that are technically present but practically dead, which degrades navigability.
A thinking notation system is only as good as its navigability. Two mechanisms:
Index artifacts. A document at each major scope boundary — system-wide, per-initiative, per-altitude where useful — that lists the artifacts within that scope, their status, and a one-line summary.
Index artifacts are not just navigation. They are the minimum viable summary at their scope boundary. Each entry carries a status sentence that is updated as part of the regular capture practice. The portfolio-level index at value altitude — listing all initiatives, their current value status, and links downward — is the lightest-weight reporting surface in the system. It answers "where are we across everything" without requiring synthesis on demand.
Index artifacts are updated as part of every change that adds, supersedes, or archives an artifact.
The single-link test. Any reasonable question at a given altitude should resolve to a single navigable artifact. If answering a question requires synthesizing across multiple documents, either an artifact is missing or something is at the wrong altitude.
When a question genuinely spans altitudes — and some do — the answer is a wayfinding artifact: a thin document whose only content is curated links with one-sentence context for each. This is navigation, not synthesis. It exists to bridge altitudes, not to flatten them.
At any point in time, for each active initiative and for the portfolio as a whole, the following should be true:
- Every decision that would be lost on handoff has a decision record at the appropriate altitude.
- Value-altitude working notes reflect current realization evidence — not stale, not months old.
- The portfolio index reflects current initiative status.
- The mandate-altitude impact journal reflects recent evidence of cross-cutting value delivery.
This is the target. Any review process — daily, weekly, human, automated — can diff current state against this target and close gaps.
Two approaches work, independently or combined:
Continuous capture. At the start of a working session, write one sentence in the relevant working notes: the initiative, the altitude, and why it matters now. At the end, capture the decision delta. This costs seconds per session in steady state.
Periodic review. At a regular cadence — daily, weekly, whatever is sustainable — review activity logs, conversation transcripts, and memory. Extract the captures that matter. This accommodates high-throughput working styles where continuous capture would interrupt flow.
Both feed the same artifacts. The method is a personal or team choice. The desired state is the constant.
When capture capacity is exceeded, prioritize by altitude. A missed value-altitude observation is more expensive than a missed implementation-altitude one, because the former cannot be reconstructed from code while the latter often can. When time permits only a fragment, capture the forcing context — why a decision was forced — even if the full decision record must wait. Context decays faster than conclusions.
Maintain a hard separation between two things.
A practice is guidance for how to think about and execute a domain of work. It is environment-agnostic. It applies regardless of toolchain or organizational context. It is the reasoning and method.
A platform is an opinionated implementation of a practice in a specific operational environment. It has system diagrams, decision records, and operational documentation. It is a reference implementation, not the practice itself.
A practice document may cite a platform as a recommended implementation. That is a pointer, not a dependency. The practice remains valid if the platform changes.
They have different audiences, different lifecycles, and different homes. Develop them independently.
This framework is a practice. Its projection into a specific enterprise's tools and repositories is a platform.
The thinking notation system requires homes for:
- Mandate — one per system, rarely changing, highly visible
- Pitches — per-initiative or system-wide, living independently of work authorization
- System diagrams — system-wide with initiative-scoped supplements as needed
- Decision records — system-wide and per-initiative, at every altitude, separately navigable
- Working notes — per-initiative and system-wide, at every altitude, append-only
- Index artifacts — at each scope boundary and at portfolio level, carrying status summaries
- Incubation space — a home for experiments and explorations that have not yet earned a pitch or an initiative boundary; these are pre-initiative, tracked lightly, and graduate into full initiatives when they gain enough shape to warrant a pitch and their own reasoning stack
Thinking notation can be centralized in a single location or distributed across initiative-scoped locations with a portfolio layer above. Both are valid. The key constraint is that each initiative's reasoning must be self-contained — able to be understood and handed off without depending on artifacts elsewhere. A portfolio layer provides cross-cutting navigation, mandate-level artifacts, and the impact journal, but it does not contain initiative-scoped reasoning. It links to it.
These live separate from work artifacts and separate from application code. The thinking notation system is not inside the work system or the code system. It is adjacent to both and references both.
The specific structure — repositories, directories, naming conventions, numbering schemes — is a platform concern. Design artifact structure to be navigable by humans and parseable by automated tooling. Consistent naming, structured frontmatter, and predictable file paths serve both audiences.
The documentation cost is front-loaded. The communication cost approaches zero over time.
Every question answered with a link rather than a synthesized explanation is evidence the system is working. Every artifact that already exists when a stakeholder asks is time not spent context-switching into presentation mode.
The thinking notation system is an observability layer over the work, not inside it. Maintain it as such.