Decisions
OpenSpec specs at openspec/specs/ are Wrkbelt's durable contract record. These pages are different — they explain why the architecture is shaped the way it is.
Two kinds of decisions
- Shipped — rationale for design choices that are in production today. Read these when you want to understand why a current-state pattern exists.
- Deferred — architecturally-significant decisions deliberately postponed, with the trigger that would prompt a revisit. Read these before proposing a change that touches the deferred area.
What goes here vs. what stays in OpenSpec
| If the decision is… | Lives here | Lives in OpenSpec |
|---|---|---|
| Architecturally significant (touches multiple subsystems) | yes | no |
| Spec-level scope (e.g. "this endpoint returns 409 vs 422") | no | yes |
| Deferred with a known revisit trigger | yes (deferred/) | also tracked in current-decisions-for-future-tracking.md |
| Resolved by shipping the spec | yes (shipped/) | resolution noted in archive |
If you can't tell whether a decision is architecturally significant, the heuristic is: would a new engineer onboarding to this part of the codebase be confused by why it works the way it does? If yes, it belongs here.
OpenSpec is the source of truth
These pages are summaries with rationale. The binding record — what we actually built and what shape it has — lives in OpenSpec. If a decision page disagrees with an OpenSpec spec, the spec wins.