groundwork-method 0.0.1 → 0.10.0

package/src/docs/principles/design/usability-and-ux.md

@@ -0,0 +1,68 @@
+---
+title: Usability & UX
+description: Heuristics and UX laws applied at decision time, cognitive load, form design, error prevention and recovery, and information scent.
+status: active
+last_reviewed: 2026-06-20
+---
+# Usability & UX
+
+## TL;DR
+
+Usability is not a checklist run at the end — it is a set of diagnostic lenses held up to every screen as it is designed. The heuristics and UX laws are tools for *making* decisions, not for auditing them afterwards. The product, not the user, absorbs complexity. Errors are designed out before they are messaged; where they remain, recovery is cheap and the user's work is protected. Every label predicts where it leads.
+
+## Why this matters
+
+Most usability failures are not exotic — they are the same handful of mistakes repeated: silent actions, jargon labels, validation that punishes mid-typing, confirmation dialogs trained into reflexive clicks, forms that ask for what the system already knows, and "click here" links that carry no scent of their destination. Each has a known, defensible fix. The discipline is applying those fixes at design time, when they are free, instead of discovering the problem in a usability test after the structure has hardened around it.
+
+## Our principles
+
+### 1. Apply the heuristics as lenses, not a checklist
+
+Nielsen's ten heuristics are diagnostic lenses held up to a design while it is made: is system status visible, does the language match the user's world, is there a marked exit from every state, is it consistent with what users know from elsewhere, are errors prevented before they are messaged, does it favour recognition over recall, does it serve both novice and expert, is it minimal, do errors route to a fix, is help in context. We reason with them; we do not recite them. A heuristic that surfaces no concrete change to the screen in front of us was not really applied.
+
+### 2. The UX laws carry concrete implications
+
+The laws of UX are design instructions, each with a direct consequence. Fitts: primary actions are large and near the user's pointer, destructive ones small or distant, and screen edges are infinite targets. Hick: reduce and group choices and offer a recommended default. Jakob: meet convention first, because users spend most of their time on *other* products. Miller: chunk information rather than capping menus at seven. Tesler: the product absorbs irreducible complexity through smart defaults and inference. Postel: accept messy input and normalise it silently. Peak-End: invest in the peak moment and the ending. Doherty: keep perceived response under ~400ms, manufacturing it with optimistic UI when real speed is unavailable. Von Restorff: give the single most important action visual distinction; if everything is emphasised, nothing is.
+
+### 3. The product absorbs complexity, not the user
+
+Every system carries irreducible complexity; the only question is who bears it. We make the product bear it — sensible defaults so the common case requires no decision, values derived rather than asked, the happy path optimised for first use with accelerators layered on for experts. We attack *extraneous* cognitive load — visual clutter, inconsistent patterns, unnecessary choices — because every scrap of attention spent decoding the interface is attention not spent on the task. Recognition beats recall: show options and prior choices rather than making the user remember across screens.
+
+### 4. Reveal complexity progressively
+
+We show the common 80% first and tuck advanced options one discoverable layer deep, because deferred complexity is managed complexity and a flatter surface lowers the decision cost of the common case. For complex, branching, or low-confidence flows — onboarding, checkout, anything official — one question per page beats a long wall of fields, because it lowers load and handles validation, branching, and save-progress far better.
+
+### 5. Forms ask less, validate kindly, and never lose work
+
+A form is a single column, top to bottom, with labels above the field — the layout that completes fastest and survives translation — and never a placeholder standing in for a label, because the placeholder vanishes on input and fails review and accessibility. We validate on blur and confirm success inline, never erroring mid-keystroke, because punishing not-yet-finished input is hostile. On a failed submit we keep every entered value, mark each field inline, summarise at the top, and move focus to the first error. We pre-fill what we can infer and cut every field not needed now, because each field measurably lowers completion, and we use the correct input type and accept any reasonable format.
+
+### 6. Prevent the error; make recovery cheap
+
+The cheapest error to recover from is the one that cannot occur, so we design errors out first with constraints, smart defaults, and forgiving formats before designing any message. For reversible actions we act immediately and offer Undo rather than a confirmation dialog, because dialogs train reflexive "yes" clicks and interrupt flow while Undo respects momentum; confirmation is reserved for the genuinely destructive and irreversible. Where a message is still needed, it states what happened, why, and how to fix it, in plain language at the point of the error, styled to be noticed without blame or raw error codes. Work is protected by autosave and a warning before discarding unsaved changes.
+
+### 7. Every label predicts where it leads
+
+Users forage by scent: they choose links and buttons by the payoff each label predicts, so labels are descriptive and specific and match the content they lead to — never "click here," "learn more," or a bare "submit." Every screen answers the wayfinding questions — where am I, how did I get here, where can I go, how do I get back — through an active navigation state, a clear title, breadcrumbs in deep hierarchies, and consistent, persistent navigation. Disorientation is a silent driver of abandonment.
+
+## How we apply this
+
+- [Interaction & Motion](interaction-and-motion.md) — the state, feedback, and perceived-performance decisions usability depends on.
+- [Accessibility](../quality/accessibility.md) — keyboard operability, focus management, and error association as the operable backbone of usability.
+- [Design Foundations](design-foundations.md) — usability is the design-owned risk in the four-risk frame.
+
+## Anti-patterns we reject
+
+- **Heuristics as an audit.** Reciting the ten heuristics after the fact instead of using them to change the design as it is made.
+- **Placeholder as label.** A label that disappears the moment the field is filled, defeating review and accessibility.
+- **Validation mid-keystroke.** Red errors thrown before the user has finished a field, punishing in-progress input.
+- **Lost work on failure.** Clearing the form or losing entered data when a submit fails.
+- **Confirmation-dialog overuse.** "Are you sure?" on routine reversible actions, training the reflexive click that defeats the dialog's purpose.
+- **Asking for the known.** Requiring data the system already has or could derive.
+- **Scentless labels.** "Click here" / "Learn more" / generic "Next" that predict nothing about their destination.
+
+## Further reading
+
+- Nielsen Norman Group, *10 Usability Heuristics* and the supporting article corpus.
+- Jon Yablonski, *Laws of UX* — the laws above, each with its design implication.
+- Luke Wroblewski, *Web Form Design* — single-column forms, label placement, and inline validation.
+- GOV.UK Design System, *Question pages* — one-thing-per-page for complex and branching flows.

package/src/docs/principles/design/visual-design.md

@@ -0,0 +1,84 @@
+---
+title: Visual Design
+description: Perceptual colour, typographic rigour, spatial depth, and visual hierarchy — the craft that separates an implemented design from a framework default.
+status: active
+last_reviewed: 2026-06-21
+---
+# Visual Design
+
+## TL;DR
+
+The visual layer is built on perception, not convenience. Colour is authored in a perceptually uniform space so palettes are even and predictable; type is a system of co-tuned roles, not a list of font sizes; depth comes from light modelled honestly; hierarchy is carried by weight and colour before size. Atmosphere — translucency, ambient glow, and grain — is modelled material used with restraint, never decoration; and the finishing details (optical alignment, pixel-crisp edges, tabular figures) are where polish is won or lost. The gap between a designed interface and a generic one lives entirely in these details, and every one of them has a correct, defensible default.
+
+## Why this matters
+
+Two teams can use the same font, the same brand hue, and the same grid and ship interfaces that feel a class apart. The difference is not effort spread evenly — it is correctness in the places perception is most sensitive. A colour ramp built in HEX has uneven perceived steps because HEX lightness is not perceptual; a shadow built from one layer reads as a fuzzy grey box because real light casts many; type sized without paired line-height and tracking reads as "defaults" because typographic quality lives in the relationships, not the sizes. Getting these right is cheap once known and impossible to fake.
+
+## Our principles
+
+### 1. Author colour in a perceptual space (OKLCH)
+
+We define colour in OKLCH — lightness, chroma, hue — not HEX/RGB/HSL, because OKLCH is perceptually uniform: equal numeric steps in lightness look equal to the eye across every hue. HSL lies — a 50%-lightness yellow is far brighter than a 50%-lightness blue — so palettes built in HSL need per-hue hand-correction and `darken()`/hue-rotation silently break. In OKLCH, fix the lightness curve, sweep the hue, and the ramp stays perceptually parallel. This is not speculative: CSS Color 4 ships `oklch()` in every evergreen browser and mandates OKLCH for gamut mapping.
+
+### 2. Build palettes as luminance-pinned ramps surfaced through semantic tokens
+
+A colour system is two layers. **Primitive ramps**: for each hue, a scale (commonly 11 steps, 50→950) generated by pinning a lightness curve and a chroma *arc* — chroma peaks in the mid-steps and tapers at the light and dark ends, because extreme lightness cannot hold high chroma without clipping the gamut. A flat chroma across all steps is the tell of a naïve ramp. **Semantic tokens**: roles (`surface`, `text`, `border`, `brand`, `success/warning/danger`) mapped onto ramp steps. Components reference only the semantic layer, so a theme swap or rebrand never touches a component. Wide-gamut Display P3 is layered as progressive enhancement, never as the carrier of meaning or contrast.
+
+### 3. Dark mode is a system, not an inversion
+
+A dark theme is a separate semantic mapping over the same token names, governed by three rules: signal elevation with lightness (a raised surface is lighter, not shadowed), because shadows nearly vanish on dark backgrounds; desaturate and lighten brand colours, because a saturated accent at mid-lightness glows against dark; and avoid pure `#000`/`#fff`, because maximum contrast causes halation that vibrates the edges of text. Algorithmic inversion (`filter: invert()`) is never a dark mode — it destroys the carefully built hierarchy and produces wrong colours.
+
+### 4. Contrast is validated, with WCAG as the floor and APCA as the lens
+
+Text meets WCAG 2.2 AA — 4.5:1 for body, 3:1 for large text and for non-text UI elements — as the compliance floor. We design and check with APCA where it matters, because the WCAG ratio is not perceptually uniform: it overstates contrast in dark mode and ignores font weight and size, so a pair that "passes" can be unreadable. APCA models perception, is polarity-aware, and factors size and weight, which makes it the better design tool even though it carries no legal standing yet. Contrast is a property of the token *pairing* in context, never of a colour in isolation.
+
+### 5. Typography is a system of roles, each a bundle of co-tuned properties
+
+A type scale is generated from one base and one modular ratio (1.2 for dense UI, 1.25 for general product, 1.333+ for editorial), exposed as named steps, not per-element magic numbers — and the ratio is relaxed at display sizes, where a pure geometric scale overshoots. Each *role* (display, headings, body, caption, label, mono) carries size **and** line-height (tight for headings, open for body), weight, and tracking (negative for large display, slightly positive for small labels) — because typographic quality lives in those relationships, not in size alone. Sizes name their purpose (`text-body`), never their appearance (`text-16`).
+
+### 6. Render type fluidly, on variable fonts, with optical sizing
+
+Each scale step is a `clamp(min, preferred, max)` that interpolates between two viewport poles, replacing breakpoint font-size jumps with smooth scaling. The preferred value always includes a `rem` term, never pure `vw`, because pure-`vw` text ignores user zoom and fails WCAG resize-text. We ship a variable font and let `font-optical-sizing: auto` tune stroke detail to size, because one variable file replaces many static weights and unlocks continuous, per-role weight and optical adjustments a static cut cannot. Body text holds a comfortable measure (~45–75 characters via `max-width` in `ch`); `font-display: swap` with metric-matched fallbacks prevents invisible text and layout shift.
+
+### 7. Depth is modelled light, not a default shadow
+
+Elevation comes from a multi-layer shadow stack — several shadows with progressively larger offset and blur and inversely scaled alpha — sharing one light-source direction (vertical offset roughly twice the horizontal) and tinted toward the background hue rather than pure black, because real light casts many soft accumulating shadows from a consistent source. A single `box-shadow` is a fuzzy grey box; the layered stack reads as physical. Edges catch light: prefer a translucent, luminosity-aware border or a 1px top highlight over a flat opaque grey line. Gradients interpolate in OKLCH/OKLab and carry ~1% noise to kill banding, because sRGB interpolation produces a muddy mid-stop dead zone.
+
+### 8. Atmosphere is modelled material — translucency, glow, and grain, used with restraint
+
+High-end surfaces read as material in an environment, not flat fills, and the techniques that build that atmosphere are exactly the ones a generic build skips. **Translucency (glass):** a surface tinted with alpha over a `backdrop-filter` blur samples the content beneath, placing the surface in front of a scene rather than on a void — reserved for layered chrome (navigation, overlays, command surfaces), always with a tint opaque enough to hold text contrast and a solid fallback for engines without backdrop support. **Ambient glow and gradient mesh:** a barely-perceptible radial wash (opacity well under ~0.15, fading to transparent over a solid fallback) warms a large surface and leads the eye — interpolated in OKLCH with ~1% noise, never a hard two-stop dump. **Grain:** a fine, low-opacity noise overlay defeats banding and lends tactility to large flats. Depth is multi-plane: foreground, surface, and background blur and move differently so the interface reads as layers, not a sheet. The whole discipline is restraint — atmosphere serves the content; when blur, glow, and grain become the subject, the surface has become decoration. Borrow the *technique and rigour* of the work you admire, never its signature look: the look dates, the rigour does not.
+
+### 9. Hierarchy is carried by weight and colour before size
+
+The fastest way to a flat, undifferentiated screen is to express every level with a different font size. We build hierarchy with a small set of greys (near-black primary, mid secondary, light tertiary) and two weights first; size is the last lever, not the first, because secondary text that is merely smaller still competes for attention, while lightening it makes it recede. We compose grayscale-first — if the layout fails without colour, its weight-and-spacing hierarchy is broken — and never let colour be the sole differentiator. Proximity groups: related elements sit closer than unrelated ones, so equal spacing everywhere destroys structure.
+
+### 10. Align optically and render crisp; set figures in tabular numerals
+
+Polish lives below the level most builds check. **Optical alignment is not mathematical alignment:** a triangle or play icon centred by its bounding box looks off-centre, and text centred by its line box sits high — nudge by eye to where the visual mass balances. **Render on the pixel grid:** keep 1px borders and hairlines crisp rather than smeared across two subpixels — integer offsets for sharp edges, no fractional positioning of thin lines. **Set figures in tabular numerals** wherever values are compared or change in place (tables, metrics, timers, counters) so digits hold their columns and the layout stops jittering; reserve proportional numerals for running prose. Each of these is invisible until it is wrong, and collectively they are the difference between considered and almost.
+
+## How we apply this
+
+- [Layout & Space](layout-and-space.md) — the spatial scale and grid the visual rhythm sits on.
+- [Design Systems & Tokens](design-systems-and-tokens.md) — how colour, type, and depth decisions become the semantic-token contract.
+- [Accessibility](../quality/accessibility.md) — contrast, colour-independence, and zoom as non-negotiable constraints on the visual layer.
+
+## Anti-patterns we reject
+
+- **HEX/HSL palette math.** Ramps and `darken()`/hue-rotation built in a non-perceptual space, producing uneven steps and unpredictable brightness.
+- **Flat-chroma ramps.** A scale with constant chroma across all steps — the signature of a generated-but-not-designed palette.
+- **Inverted dark mode.** Algorithmic inversion or pure-black-on-pure-white, ignoring elevation, desaturation, and halation.
+- **Size-only type tokens.** Font sizes named by their pixel value with no paired line-height, weight, or tracking, and one global letter-spacing.
+- **The single-layer shadow.** One `box-shadow` with a pure-black colour, plus a flat opaque grey border, the documented "AI slop" depth signature.
+- **The default gradient.** A two-stop indigo/purple hero gradient interpolated in sRGB with visible banding.
+- **Blur as decoration.** Backdrop blur on opaque or non-layered surfaces, or without a contrast-safe tint and a solid fallback — the cost of glass without the layered-scene payoff.
+- **Glow/grain dump.** A high-opacity or hard-stop "ambient" gradient, or heavy noise, used as ornament rather than a sub-perceptual wash that serves the content.
+- **Signature mimicry.** Copying a named product's signature surface look instead of borrowing the underlying technique and restraint.
+- **Bounding-box centring.** Trusting mathematical centre for icons, arrows, and optically-uneven glyphs instead of nudging to optical balance; blurred hairlines from fractional pixel offsets.
+- **Hierarchy by size alone.** Five font sizes standing in for a hierarchy that weight and colour would carry better.
+
+## Further reading
+
+- Andrey Sitnik / Evil Martians, *OKLCH in CSS* — why perceptual colour replaces HEX and HSL for palette building.
+- Josh Comeau, *Designing Beautiful Shadows* and *Make Beautiful Gradients* — modelling light honestly in CSS.
+- *Utopia* (utopia.fyi) — fluid type and space from anchor points, with the zoom-safe `clamp()` method.
+- *Refactoring UI*, Wathan & Schoger — hierarchy by weight and colour, grayscale-first composition.

package/src/docs/principles/foundations/code-craft.md

@@ -0,0 +1,86 @@
+---
+title: Code Craft
+description: Simplicity, readability, the discipline of deletion, and the refusal to build for hypothetical futures.
+status: active
+last_reviewed: 2026-06-19
+---
+# Code Craft
+
+## TL;DR
+
+Code is read far more than it is written. Our craft is to write code that the next reader — human or agent — can understand, change, and delete with confidence. Simplicity is the default; abstraction is a cost that must be earned.
+
+## Why this matters
+
+In a codebase that is alive for more than a year, the dominant cost is not writing code — it is understanding the code already there so you can change it. Every abstraction, every layer of indirection, every "flexible" interface is a tax on future readers. Our stance is that taxes must be justified. When we optimise for future flexibility we have not yet needed, we pay a certain cost today against an uncertain benefit later; more often than not, the benefit never arrives and we are left with the cost.
+
+## Our principles
+
+### 1. Simpler is better than clever
+
+A function that a tired engineer can understand in thirty seconds is worth more than a function that demonstrates the author's taste in type systems. Prefer plain data structures over clever abstractions, plain control flow over meta-programming, plain naming over in-joke naming. When "clever" and "clear" conflict, clear wins.
+
+The trap is mistaking *simple* for *familiar*. Rich Hickey's distinction is the one that matters: simple is the opposite of *complex* (one concern, not braided together), while easy is the opposite of *hard* (close at hand, familiar). Cleverness is bad precisely when it complects — when it braids state with time, policy with mechanism, identity with behaviour to buy terseness. But an unfamiliar construct that *untangles* those concerns is not cleverness; it is simplicity wearing a new face, and familiarity will catch up. The decision rule: prefer the option with the fewest interleaved concerns, even when it is the less familiar one — and reject the option that is compact only because it has tangled things you will later need to pull apart.
+
+### 2. No speculative abstraction
+
+Do not build a generalisation until you have at least three concrete use cases driving the same shape. Premature abstractions are harder to change than the duplication they replace — because now you have to understand the abstraction, the use cases, and the compatibility between them before you can change any of them.
+
+The asymmetry is the whole argument, and Sandi Metz states it best: duplication is far cheaper than the wrong abstraction. Unwinding a wrong abstraction means re-inlining it into every caller and then deleting what each one does not need — strictly more work than the duplication you were trying to avoid, often done under deadline by someone who did not write it. When you are unsure, duplicate: you can always extract later with more information, but you cannot cheaply un-extract.
+
+DRY is a rule about knowledge, not characters. Two fragments that look identical but change for different reasons are *not* duplication, and coupling them is the mistake; one business rule expressed in two places *is* duplication even when the code differs. The decision rule: extract only when you have seen the same shape change for the same reason three times, or you have a hard, already-funded requirement (not a guess) for the second case. Until then, keep the copies and watch them — if they drift apart, they were never the same thing; if they move together, you have found the real abstraction and earned the right to name it.
+
+### 3. Deletion is a virtue
+
+The code you delete cannot break, cannot require maintenance, cannot confuse the next reader, and cannot leak a vulnerability. When a feature is removed, the code should go with it — including the tests, the config flags, and the docs. Leaving dead code "just in case" is a bet that is almost always wrong: if we need it back, we will write a clearer version with the benefit of hindsight.
+
+### 4. Names are the interface
+
+A badly named function is a broken interface even if its behaviour is correct, because every caller has to read the implementation to know what it does. We spend time on names. We rename aggressively when a better name becomes clear. Variables, functions, types, files, directories — all of them communicate, and a mismatch between name and behaviour is a bug.
+
+### 5. Comments explain the "why"
+
+Code explains the "what" of its own mechanics; restating that in prose is noise. The comment's job is the "why" — the non-obvious constraint, the invariant that must hold, the bug that drove an odd choice, the reference to an ADR. If a comment would be obvious to anyone who read the next two lines, delete it.
+
+There is one "what" worth writing, and it is not redundant: the comment that states what a unit *does, assumes, and costs* so that a caller never has to read its body. That comment is the abstraction. John Ousterhout's point holds — "good code is self-documenting" is the excuse that produces a hundred shallow methods nobody can compose, because if a caller must read your implementation to use it, you have no abstraction at all. The decision rule splits cleanly by location: comment the *contract* at the boundary of a module (what it guarantees, what it requires, what it will cost you); do not narrate the line-by-line mechanics *inside* it. A comment that saves a reader from opening the file is leverage; a comment that repeats the line beneath it is debt.
+
+### 6. Error handling is design, not decoration
+
+Errors are a first-class part of the interface, not an afterthought. We decide — explicitly — which errors a function can return, how callers are expected to respond, and where the boundary between recoverable and fatal is. `err != nil` sprinkled through a codebase without a model behind it is a failure of design.
+
+Make the failure modes visible in the signature. Model expected, recoverable failures as values in the return type (Go's `error` return, Rust's `Result`) so a caller cannot forget that they exist; reserve exceptions and panics for programmer error and states you genuinely cannot continue from. Wrap foreign errors at the boundary where you cross into another system's vocabulary, so a third party's failure taxonomy does not leak into yours. The test of a good error design is simple: from the signature alone, a caller can tell what can go wrong and what they are expected to do about it.
+
+### 7. Trust the boundary; distrust the internal
+
+We validate at system boundaries — user input, external APIs, message payloads — where the data is untrusted. We do not re-validate between internal callers in the same service; if an internal contract is wrong, the right fix is the contract, not a runtime check in every consumer. Defensive programming inside the trust boundary is a form of noise.
+
+The mechanism that makes this safe is *parsing*, not checking. At the boundary, turn untrusted input into a type that cannot represent the illegal state — a parsed `Email` or `NonEmptyList<Order>`, not a raw string you re-inspect everywhere (Alexis King, "Parse, don't validate"). Once the data carries its guarantee in its type, internal code receives it for free and re-validation is genuinely dead code. If you find yourself re-checking a value deep inside the system, that is the signal: the boundary handed you a type too weak to trust, so strengthen the type rather than scattering the check.
+
+The honest exception is the security boundary that runs *inside* the process — a multi-tenant query, an authorization decision, a privilege-escalation path. There, defense in depth is not noise: the second check guards against a different failure mode (a bug, not malformed input), and the cost of being wrong is a breach rather than a stack trace. Distrust the internal everywhere except where the threat model says a single point of failure is itself the vulnerability.
+
+### 8. Dead code is a bug
+
+Commented-out code, `_unused` variables, orphan functions, legacy configuration — all of it decays the signal-to-noise ratio of the codebase. When we find it, we delete it. `git` preserves anything we lose; the working tree should contain only code that is alive today.
+
+## How we apply this
+
+- [How We Structure Code](../system-design/code-structure.md) — the structural discipline that makes simplicity scalable.
+- [Testing](testing.md) — tests that exercise behaviour keep refactoring cheap.
+- [Decisions](../../decisions/) — the ADRs that capture the "why" our comments do not.
+
+## Anti-patterns we reject
+
+- **Defensive programming without a threat model.** Guarding every internal call against nil is not robustness — it is distrust of our own type system.
+- **"Might need it later" scaffolding.** Config flags for scenarios that do not exist, plugin systems with one plugin, interfaces with one implementation. Delete.
+- **Fashion-driven refactors.** Rewriting working code to match a new pattern the team read about this week is debt, not progress.
+- **Multi-paragraph docstrings.** If the function needs a multi-paragraph docstring to be understood, the function is wrong. Split it, rename it, or simplify it — then the docstring is not needed.
+- **Backwards-compatibility shims for internal APIs.** If it is fully internal, changing it is allowed and expected; compatibility layers are debt we impose on ourselves for no benefit.
+
+## Further reading
+
+- *A Philosophy of Software Design*, John Ousterhout — deep modules, the cost of shallow abstractions, and why interface comments are part of the design, not decoration.
+- *The Wrong Abstraction*, Sandi Metz — why duplication is far cheaper than the wrong abstraction, and how to unwind one.
+- *Parse, Don't Validate*, Alexis King — pushing validation to the boundary by making illegal states unrepresentable in the type.
+- *Simple Made Easy*, Rich Hickey — simple is not easy; complexity is entanglement, not volume.
+- *Tidy First?*, Kent Beck — the economics of refactoring as a separable activity.
+- *The Pragmatic Programmer*, Hunt & Thomas — the canonical treatment of names, duplication, and orthogonality.

package/src/docs/principles/foundations/continuous-discovery.md

@@ -0,0 +1,75 @@
+---
+title: Continuous Discovery
+description: Discovery as a continuous habit, not a phase — mapping the problem space with an opportunity-solution tree before committing to a solution, while keeping vision in the lead.
+status: active
+last_reviewed: 2026-06-19
+---
+# Continuous Discovery
+
+## TL;DR
+
+Discovery is not the phase before delivery — it is a habit that runs alongside it. We stay in regular contact with the people we build for, we map the **problem space** before we choose a solution, and we connect every solution we consider back to a desired outcome through an opportunity-solution tree. The goal is not more research; it is a shorter loop between a decision and the evidence that should inform it.
+
+## Why this matters
+
+The most expensive mistake in software is building the wrong thing well, and it is almost always made at the moment a team jumps from a vague problem straight to a specific solution. Discovery done as a one-time upfront phase cannot prevent this: the assumptions it validated go stale the moment the world moves, and by the time delivery reveals the gap, the cost of the miss is a shipped feature instead of a discarded sketch. Teams that ship the right thing repeatedly are not the ones who research hardest once — they are the ones who keep a continuous, low-friction connection to the people they build for and let it steer decisions while those decisions are still cheap to change. Discovery is continuous because the problem space is never finished revealing itself.
+
+Be precise about what discovery is for. It is the discipline that stops you building the wrong thing; it is not, by itself, the thing that produces the breakthrough. Direction comes from vision and technical insight — discovery's job is to tell you whether the ground under that direction is real before you commit the team to it. A team that treats every user signal as a referendum on where to go will polish what exists and never invent what does not; a team that runs on vision alone will ship confident, expensive wrong bets. The two are partners, and the rest of this document is about holding both.
+
+## Our principles
+
+### 1. Discovery is a continuous habit, not a gate
+
+We treat customer contact as a recurring rhythm, not a quarterly study. The unit is small and frequent: one conversation, one observed session, one assumption tested. Continuous contact keeps the team's mental model of the user current, surfaces problems while they are still cheap to act on, and means no live decision rests on research that is months old. A team that only talks to users at the start of a project is navigating by a map it drew once and never updated.
+
+The weekly touchpoint is the canonical prescription, and it is a good default — but the cadence is not the principle. The invariant is that no decision in flight rests on stale or absent evidence; the calendar is just a forcing function. Where users are abundant and reachable, weekly is easy and right. Where they are scarce, gated, or expensive to reach — enterprise buyers, regulated domains, infrastructure and developer tooling where the user is a busy engineer — a fixed weekly slot fails in the opposite direction: it fills with whoever happened to be reachable, and the same small panel hardens into an echo chamber that confirms what you already believe. **Decision rule:** set cadence to the rate at which you are making real decisions, not to the calendar, and recruit a representative rolling panel rather than re-interviewing the same convenient few. Use automated recruiting so the touchpoint never depends on a weekly scramble. In 2026, the working pattern is asynchronous and AI-moderated sessions for breadth, with live conversations reserved for depth, contradiction, and high-stakes accounts.
+
+### 2. Map the problem space before choosing a solution
+
+The first move is never "what should we build?" — it is "what is the user actually trying to accomplish, and where does that break down?" We hold the problem space open deliberately, naming the distinct opportunities (unmet needs, pain points, desires) before collapsing toward any one solution. A solution chosen before the problem space is understood is a guess dressed as a plan; the discipline is to resist the collapse until the opportunities are explicit.
+
+### 3. The opportunity-solution tree keeps work connected to outcomes
+
+We structure discovery as a tree: a desired **outcome** at the root, branching into the **opportunities** that could move it, branching into candidate **solutions**, branching into the **assumptions** each solution rests on. The tree makes the reasoning visible — every solution traces back to an opportunity and an outcome, and any solution that cannot is a feature looking for a justification. The tree is living: it evolves as evidence comes in, not a diagram drawn once for a kickoff.
+
+The tree is a tool, not a tollgate. Not every problem needs one: when the opportunity is obvious and the solution is essentially the only sane one, building a tree to "discover" it is theatre — skip it and execute. When you do build one, build it to the 80/20: map the few most promising opportunities, not an exhaustive taxonomy of everything a user might ever feel. An over-built tree becomes the feature factory's backlog in disguise, a sprawling diagram nobody prunes that quietly turns into a list of solutions to chase. **Decision rule:** build the tree only when it will change a decision — when there are genuinely competing opportunities or non-obvious solutions to reason between — and keep it only as large as the decision in front of you requires.
+
+### 4. Compare opportunities instead of debating solutions
+
+When a team argues about which feature to build, it is usually arguing about solutions to different problems without realising it. The tree reframes the debate: decide which *opportunity* is most worth pursuing first, and the solution conversation becomes tractable. Prioritising at the opportunity level — by the size of the unmet need, how many users feel it, and how well it serves the target outcome — beats prioritising a backlog of solutions whose value is asserted rather than reasoned.
+
+### 5. Seek evidence, and guard against the loudest voice
+
+Discovery grounds decisions in evidence, but evidence is easy to skew: the loudest customer, the most recent complaint, the most senior stakeholder's hunch. We weight signal by how representative it is of the target users and the target outcome, not by how forcefully it arrived. Structured contact across the user base — rather than reacting to whoever escalated last — is what keeps the opportunity space honest. The discipline cuts the other way too: a loud outlier is sometimes the canary, a leading signal the representative middle has not felt yet. **Decision rule:** an escalation is triaged *into* the opportunity space, not promoted straight onto the roadmap and not reflexively dismissed as noise — it earns weight only when it maps to a real opportunity for a target user.
+
+### 6. The team discovers together
+
+The people who will build the thing hear the problem firsthand. When product, design, and engineering all sit in (or watch) customer contact, the team shares one mental model and the handoff loss between "what the user said" and "what we built" collapses. Discovery filtered through a single person and relayed as a requirements document loses exactly the texture that would have changed the design. Firsthand exposure is a force multiplier on every downstream decision.
+
+The invariant is shared exposure, not synchronized calendars. **Decision rule:** the product trio — the people deciding what to build and how — is present live for synthesis, where the interpretation actually happens; everyone else gets the recording and the highlights asynchronously. Mandating that the whole team attend every session is its own waste, and it is the fastest way to get the cadence abandoned the first time delivery gets tight.
+
+### 7. Vision leads; the customer is not always the source
+
+Customers are reliable about their problems and unreliable about solutions. They will tell you, vividly, where their day breaks down; they cannot ask for the thing they have never seen. The defining products of the last two decades were not waiting in an interview transcript — they came from a vision of what had become possible and the technical insight to build it, and were then de-risked against real users. Marty Cagan makes this case directly: customers are not the source of innovation. **Decision rule:** let customer evidence be decisive for two questions — *is this problem real?* and *does this solution actually land?* — and overrule opinion there without apology. But for category-creating or technology-enabled bets, vision and technical insight choose the direction, and discovery's job shifts from "find the opportunity" to "prove the leap is real before we bet the team on it." This matters most for foundational tooling, where the user often cannot describe the better way until they are holding it.
+
+## How we apply this
+
+- The desired outcome at the root of the tree is a [success metric](success-metrics.md), not a feature count — discovery steers toward a measurable change in behaviour.
+- Each candidate solution carries the [product risks](product-risks.md) it must clear; discovery is where we test the riskiest assumption before delivery, not after.
+- When discovery converges on a bet, its problem, hypothesis, and no-gos are framed against [prioritization and appetite](prioritization-and-appetite.md) — the opportunity chosen sets the appetite.
+
+## Anti-patterns we reject
+
+- **Big-bang discovery.** A single upfront research phase that produces a backlog and then ends. The map goes stale and nothing updates it.
+- **Solution-first thinking.** Jumping to "let's build X" before the opportunity X serves is named. The problem space never gets mapped, so the solution can never be wrong — which means it can never be right either.
+- **The feature factory's roadmap.** A prioritised list of solutions with no visible link to outcomes. Without the tree, "why this and not that?" has no defensible answer.
+- **Loudest-customer steering.** Letting the most recent escalation set the agenda. Reactive discovery optimises for the squeakiest wheel, not the target user.
+- **Discovery by proxy.** One person talks to users and relays a document to the team. The texture that would have changed the design is lost in translation.
+- **Discovery theater.** Interviews and trees run on schedule but never change a decision — research as ritual, the insight filed and the roadmap untouched. Activity is not discovery; a habit that never kills or reshapes a bet is overhead in costume.
+
+## Further reading
+
+- *Continuous Discovery Habits*, Teresa Torres — the canonical treatment of the weekly habit and the opportunity-solution tree.
+- *Inspired* and *Empowered*, Marty Cagan — discovery as the core competency of a product team.
+- *The Mom Test*, Rob Fitzpatrick — how to talk to users without leading them toward the answer you want to hear.
+- *Customers Are Not the Source of Innovation*, Marty Cagan (Business of Software talk) — why vision and technical insight, not interview transcripts, produce category-defining products — the counterweight to taking discovery as the source of direction.

package/src/docs/principles/foundations/documentation.md

@@ -0,0 +1,102 @@
+---
+title: Documentation
+description: Docs as an active product surface for humans and AI agents — canonical knowledge, machine-readable interfaces, automation-first governance, and drift control.
+status: active
+last_reviewed: 2026-06-19
+---
+# Documentation
+
+## TL;DR
+
+Documentation is an active product surface. The docs are the canonical source for durable engineering knowledge; agent skills are the execution layer that selects, loads, and applies that knowledge safely. We design documentation for humans and AI agents at the same time, organise it with Diátaxis as the default frame, expose it through clean Markdown exports, a curated `llms.txt` index, and MCP resources, and enforce freshness with automation wherever a human would drift.
+
+## Why this matters
+
+In 2026, documentation is part of the runtime environment for engineering work. A human reads the site through navigation and search; an agent reads the same knowledge through MCP resources, `llms.txt`, and per-page Markdown exports. If those surfaces disagree, the system teaches different readers different truths. That is not a documentation problem; it is an engineering defect.
+
+The operating model is simple: **docs hold the knowledge, skills control the agent behaviour**. Durable guidance belongs in the docs where humans and agents can inspect it. Skill files stay concise and directive: they define when to trigger, what context to load, which tools to use, and which safety checks must run. This keeps prompts lean, reduces duplicated policy, and gives us one canonical place to correct factual drift.
+
+## Our principles
+
+### 1. Documentation is canonical knowledge
+
+Architecture principles, service handbooks, workflow guides, glossary terms, ADRs, API references, and generated schemas belong in the docs. A skill may point to these pages, but it does not become the source of truth for material that humans also need to understand.
+
+### 2. Skills are the agent execution layer
+
+Agent skills are a control surface, not a second documentation site. A skill owns triggering, task routing, tool use, safety constraints, verification steps, and context-loading instructions. It should reference the relevant doc pages, not duplicate them in full.
+
+### 3. AI-native documentation is first class
+
+Every important documentation surface must survive machine consumption. Three surfaces carry the load, and they are not interchangeable:
+
+- **Clean per-page Markdown exports and semantic HTML** are the floor. Any agent, crawler, or RAG pipeline can read them today with no special support. This is non-negotiable.
+- **`llms.txt`** is a curated index that helps a client *route* to the right pages instead of scraping the whole site. Be honest about its reach: no major model provider treats it as a crawl signal — Google's public position is that it behaves like the long-dead `keywords` meta tag, and AI-bot logs show near-zero direct requests for it. Its real value is business-to-agent: an agent you control, or an opted-in client (an IDE assistant, an MCP doc server such as `mcpdoc`), reads the index and pulls only the pages it needs. Publish it for that audience; do not assume an external crawler will honour it.
+- **MCP resources** are the path when retrieval must be scoped and auditable. MCP gives the agent explicit, token-efficient fetches and gives us a log of what was actually read, instead of hoping a crawler lands on the right page.
+
+Decision rule: ship the Markdown/HTML floor for everyone; add `llms.txt` as a routing index for agents you or your users control; reach for MCP when retrieval must be governed and inspectable. Agent-readiness is a quality attribute of the docs system, not an SEO play.
+
+### 4. Diátaxis is the structural frame
+
+We organise by reader intent, not by our internal org chart. Tutorials teach, how-to guides solve, reference pages support lookup, and explanation pages build understanding. A page that mixes these jobs forces both humans and agents to infer the purpose from context, which makes retrieval weaker and maintenance harder.
+
+Diátaxis is the default partition, not a cage. It was designed for *tools* with shallow conceptual models; dense domains — a framework, a language, a protocol — need forms it does not name. The two it most often misses: a **conceptual overview** for the reader still deciding whether to adopt at all (different from an explanation aimed at someone already learning), and **annotated examples and recipes** that teach a way of thinking rather than one procedure. Allow those page types explicitly. The failure mode is dogma: refusing to write the page a reader needs because no quadrant fits, or forcing a genuinely sequential lesson into random-access reference. Use the four types to keep each page honest about its job; add a fifth when the domain demands it.
+
+### 5. Active docs replace passive docs
+
+A page is not "done" when it is written. Active docs declare ownership, review cadence, freshness status, and source-of-truth boundaries. Pages that age past their review window are visibly flagged and reviewed as part of normal engineering work, not as a cleanup project.
+
+### 6. Automation is the first reviewer
+
+Automated checks enforce the cheap, high-signal rules: required frontmatter, broken internal links, stale review dates, and known version mismatches. Humans review accuracy, judgment, and usefulness. Automation handles the facts it can verify without fatigue.
+
+### 7. Prefer generated reference over prose
+
+API specs, event contracts, database schemas, CLI command tables, and error catalogues have machine-readable sources. We render them from those sources instead of hand-writing reference pages. Hand-written reference drifts; generated reference rebuilds and validates.
+
+Generation covers the *facts*, not the *orientation*. A raw OpenAPI dump is accurate and nearly unusable — readers still need hand-written narrative explaining what the API is for, the common flows, and the constraints a schema cannot express. Decision rule: generate every fact that has a machine source; hand-write the connective tissue around it; never paraphrase a generated fact back into prose, where it will silently rot out of sync with the source.
+
+### 8. Decisions are append-only
+
+Hard-to-reverse decisions live in ADRs. Accepted ADRs are not edited to match current preference; they are superseded. Each ADR carries enough consequence and debt context for a future reader to understand why the decision existed, what it cost, and when to revisit it.
+
+### 9. Metadata interoperability matters
+
+Precise metadata, stable identifiers, and explicit relationships between documentation objects sharpen interoperability. For agent discovery specifically, use `llms.txt`, Markdown exports, MCP resources, and HTTP `Link` headers.
+
+### 10. Drift is corrected at the source
+
+When code, docs, skills, specs, and design records disagree, we identify the source of truth before editing. Code and generated contracts win for shipped runtime behaviour. ADRs win for historical decisions. Active design docs win for current delivery intent until the shipped system proves otherwise. Skills win for agent execution behaviour only.
+
+## Freshness model
+
+| Surface | Review window | Freshness rule |
+|---|---:|---|
+| Principles | 6 months | Review when operating model or engineering policy changes. |
+| Service handbooks | 3 months | Review when code structure, stack versions, commands, or service boundaries change. |
+| API and event reference | Every contract change | Generated from OpenAPI and AsyncAPI sources. |
+| Runbooks | 3 months | Review after incidents, operational changes, or ownership changes. |
+| Active bet and TDD docs | Every material implementation change | Keep design intent aligned with delivery reality. |
+| Delivered bet docs | Historical | Freeze except for explicit correction notes. |
+| ADRs | Historical | Supersede instead of rewriting accepted records. |
+| Agent skills | Every skill or mapped docs change | Validate trigger logic, context routing, and verification steps. |
+
+## Anti-patterns we reject
+
+- **Skill files as shadow docs.** A skill that duplicates durable engineering policy becomes stale faster than the canonical docs page.
+- **Docs pages as prompts.** Documentation should explain systems and decisions; skills should instruct agents how to act.
+- **Documentation as an afterthought.** Docs ship with the feature or the feature is incomplete.
+- **Manual reference tables.** If a table can be generated from code, contracts, or schemas, generate it.
+- **Unowned pages.** A page without owner and review cadence has no maintenance path.
+- **Stale diagrams.** A diagram that does not match the system is worse than no diagram because it creates false confidence.
+- **Screenshots as reference.** Screenshots are acceptable as evidence in incidents, not as canonical UI or architecture documentation.
+- **Marketing-flavoured engineering docs.** Assertions need evidence, examples, or source-of-truth links.
+- **Overstated standards claims.** Distinguish formal standards from emerging conventions. Name the standard, its scope, and why it applies.
+
+## Further reading
+
+- [Diátaxis](https://diataxis.fr) — the structural model for tutorials, how-to guides, reference, and explanation.
+- [llms.txt](https://llmstxt.org) — the curated-index convention behind our AI-readable docs; adopted by developer-doc tooling and MCP clients, not honoured by major web crawlers.
+- [Model Context Protocol](https://modelcontextprotocol.io) — the protocol for structured agent access to docs resources and tools.
+- *Docs for Developers*, Bhatti et al. — practical guidance for engineering documentation.
+- *Living Documentation*, Cyrille Martraire — using code and automation to reduce documentation drift.

package/src/docs/principles/foundations/prioritization-and-appetite.md

@@ -0,0 +1,78 @@
+---
+title: Prioritization & Appetite
+description: Choosing and sizing across the portfolio — appetite as worth, stakes as the size that survives AI, and where scoring frameworks help and mislead.
+status: active
+last_reviewed: 2026-06-19
+---
+# Prioritization & Appetite
+
+## TL;DR
+
+Prioritization is the portfolio decision: of all the things worth doing, which do we commit to next, how much is each worth, and how much is at risk if we get it wrong? We size work on two axes that survive AI — **worth** (an *appetite*: how much the problem deserves, judged by opportunity cost) and **stakes** (blast radius × reversibility × the human review the work demands). The third historical axis, **effort/complexity**, is the one AI destabilized: agents change how long execution takes unpredictably — and distort our felt sense of it — so an effort estimate no longer sizes anything reliably. The unit of commitment is the **bet**: a shaped wager carrying both an appetite and a stakes read. Scoring frameworks inform that judgement; they do not replace it.
+
+## Why this matters
+
+Work used to be sized on three axes that travelled together — how much it is worth, how much is at risk if it goes wrong, and how much effort it takes — and effort became the proxy for all three. Bigger estimate, bigger thing. AI broke that correlation. Agents change *execution effort* unpredictably and in both directions: the boilerplate slog and the load-bearing change can now cost the same wall-clock, and which one an agent accelerates is rarely knowable up front. Worse, the signal can no longer be read from the inside — in a 2025 randomized trial, experienced open-source developers completed familiar tasks 19% *slower* with AI tooling while believing they had worked faster (METR). So the team that still sizes by effort — or by its cousin, complexity — is anchoring on the one axis that became both noisy and untrustworthy to the gut.
+
+Two axes survive, because they are bound by human judgement and consequence rather than by how fast the code gets written. **Worth** is what *appetite* has always measured — and appetite was never an estimate, so AI did not weaken it; if anything, when the cost of execution becomes unreadable, worth becomes the most stable thing left to argue about. **Stakes** is what is at risk if we are wrong, and a fast agent makes a wrong thing faster, not safer. Sizing by these two — and naming effort as the deflated axis it now is — is what keeps planning honest once the old proxy stops working.
+
+## Our principles
+
+### 1. Appetite, not estimate — worth, not effort
+
+We set an **appetite** first — a statement of how much a problem is worth solving, fixed before the solution exists to bias it — and then design the largest version of a good solution that fits inside it. This inverts the usual flow: instead of estimating the cost of a fixed solution, we fix the worth and negotiate the solution. The question becomes "what is the best outcome we can deliver for what this is worth?" rather than "how long will this take?"
+
+Appetite is denominated in **worth, judged by opportunity cost** — not in effort. But worth is squishy, and an appetite that stays an abstraction never bites: scope creeps to fill "worth a lot." So worth must resolve to a *hard ceiling* — one fixed, unforgeable budget the work may not exceed without an explicit re-bet. The distinction that matters is **ceiling versus estimate**, not time versus worth: a budget you design *within* is a circuit breaker (this is exactly why Shape Up caps its appetites in time — time is unforgeable), while a budget *derived from* an effort estimate is the trap AI sprung. Convert worth into whatever the binding constraint actually is — a cycle count, a headcount, a spend, or calendar time where human coordination dominates (heavy review, cross-team work) — then let that ceiling, not the solution, win every argument. If a solution cannot fit the appetite, cut scope or reject the work — never stretch the appetite to fit the solution.
+
+### 2. Size is stakes, not effort
+
+The size of a bet that matters is its **stakes**: how much is at risk if we get it wrong. Three things set it, and none of them shrink when the agent speeds up:
+
+- **Blast radius** — how much surface the change touches, and how many users or systems feel it if it is wrong.
+- **Reversibility** — how cheaply a wrong call can be undone (Bezos's one-way versus two-way doors). A one-way door — a published API, a data migration, a pricing change — is high-stakes at any size; a feature flag behind which we can iterate is low, and the real cost there is treating it as if it were one-way and moving too slowly.
+- **Review and judgement load** — how much a human must hold in their head to *vouch* for the work. This is the axis most specific to the AI-native shift: an agent can produce more correct-looking code than a human can actually verify, so the trust ceiling, not the typing speed, is the real bottleneck.
+
+Stakes is what earns rigour — a high-stakes bet earns deeper discovery, tighter review, and a smaller validating increment, regardless of how little effort it takes to build. Effort and complexity are explicitly *not* the measure of size: they are the axis AI deflated, and a small-effort change to a payment path is high-stakes precisely where effort would have called it trivial. Worth says how much to invest; stakes says how carefully.
+
+### 3. The bet is the unit of commitment
+
+We commit in **bets**: a shaped problem, an appetite (its worth), a stakes read, a sketch of the solution, a success signal, and explicit no-gos. The bet is deliberately small and reversible so that a wrong call costs one cycle, not a quarter — and so that we re-decide frequently with fresh information rather than locking a long plan. Between bets we are free to change direction entirely; that freedom is the point. Big up-front roadmaps trade this optionality away for a false sense of certainty.
+
+### 4. Prioritise the opportunity, then bound the solution
+
+The first decision is *which opportunity* is most worth pursuing — by the size of the unmet need, how many target users feel it, and how well it serves the desired outcome. The second is how much appetite it earns. Separating these keeps the conversation honest: a large opportunity with a small appetite is a deliberate first slice; a small opportunity with a large appetite is a mistake the framing makes visible. Prioritising solutions directly skips the opportunity decision and smuggles the value question past review.
+
+### 5. Opportunity cost is the real currency
+
+Saying yes to a bet is saying no to everything else that cycle could have held. We judge each candidate against that alternative, not against an absolute bar — the question is never "is this worth doing?" (almost everything is) but "is this the *best* thing to do next?" Naming the opportunity cost out loud is what turns a backlog of good ideas into a sequence of defensible choices.
+
+### 6. No-gos and the parking lot keep scope honest
+
+A bet names what it is explicitly *not* building — the natural extensions a user would expect, each excluded for a stated reason and routed somewhere (a later bet, a permanent boundary, the parking lot). No-gos are how a fixed appetite stays fixed under pressure: the scope-cutting decision is made once, in the open, instead of relitigated every time the work gets hard. Parked ideas and prior sequencing instincts are inputs to the next prioritization, not commitments — appetite math that ignores them re-discovers decisions already made.
+
+### 7. Scoring frameworks inform; they do not decide
+
+Frameworks like RICE, weighted scoring, or opportunity scoring are useful for *structuring* a comparison — making the inputs explicit, exposing a wildly mis-ranked item, forcing a reach-vs-impact conversation. They mislead when their output is treated as the decision: the scores are estimates dressed as arithmetic, they flatten strategy into a single number, and they reward whatever is easy to quantify over whatever matters. We use them to inform judgement and surface disagreement, then decide with judgement. The payoff is real where the inputs are real: many comparable candidates, a mature product with usage data to ground reach and impact, and stakes low enough that a mis-rank is cheap to correct. It inverts in early-stage or data-poor work, where reach and impact are guesses, and on a short slate of high-stakes bets, where ranking 1.7 against 1.3 lends false precision to a call that turns on judgement anyway. A roadmap that is the literal sort order of a scoring spreadsheet has outsourced the hardest product decision to a formula.
+
+## How we apply this
+
+- The opportunity a bet pursues comes from the [continuous-discovery](continuous-discovery.md) tree — prioritization chooses among its branches; appetite bounds the chosen one.
+- Stakes set how much [product risk](product-risks.md) work a bet earns: a high-stakes bet earns a discovery spike before its appetite is fixed, so we are not betting worth on an untested assumption — and `product-risks.md` §6 ("low stakes earn a lighter pass") is the same axis, governing discovery depth.
+- Appetite and the bet are how [product engineering](product-engineering.md) schedules shaped work — this page is the portfolio view (choosing and sizing bets); product engineering is the per-bet view (shaping one piece of work well).
+
+## Anti-patterns we reject
+
+- **Estimate-driven planning.** Fix the scope, estimate the cost, watch it balloon. Appetite exists because estimates anchor on effort, not on what the work is worth — and AI made effort the least stable thing to anchor on.
+- **Sizing by complexity.** Treating "how hard is this to build" as the measure of how big a thing is. Complexity is the axis AI destabilized; it now mis-sizes high-stakes/low-effort work as trivial and low-stakes/high-effort work as major.
+- **The backlog as autopilot.** A ranked list executed top-down with no fresh judgement about whether the top item is still the right bet.
+- **Scoring-formula governance.** Treating a RICE or weighted-score sort as the decision rather than an input to it. The formula rewards the quantifiable, not the important.
+- **Scope that expands to fill time.** No fixed appetite, so work grows until the deadline forces a messy cut nobody planned.
+- **Ignoring the parking lot.** Re-deciding sequencing the user already settled because prior instincts and parked ideas were not carried into the prioritization.
+
+## Further reading
+
+- *Shape Up*, Ryan Singer — appetite, betting, and the fixed-worth/variable-scope inversion (here re-denominated from time to worth, and paired with stakes).
+- *Escaping the Build Trap*, Melissa Perri — why the feature-backlog-as-strategy fails and what replaces it.
+- *Continuous Discovery Habits*, Teresa Torres — prioritising at the opportunity level rather than the solution level.
+- *Amazon 1997 Letter to Shareholders*, Jeff Bezos — one-way vs. two-way door decisions: reserve heavyweight rigour for the irreversible.
+- *Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity*, METR (2025) — the randomized trial behind the claim that the effort signal is now both noisy and badly mis-perceived.