cad-context: ADR-worthiness test as a decision-promotion filter #26

New issue

Closed

opened 2026-07-19 00:25:19 +00:00 by crenshawdev · 1 comment

crenshawdev commented

2026-07-19 00:25:19 +00:00

(Migrated from github.com)

Source: skills-analysis session, 2026-07-18 (comparison against Matt Pocock's domain-modeling).

cad-context records phase decisions (D-01, D-02, …) and carries them forward / resurfaces them via builtin recall. But every decision is treated equally — there's no filter separating load-bearing decisions from throwaway ones, so recall competes trivial and durable decisions for attention.

Borrow the sharp three-part ADR-worthiness test as a promotion criterion (NOT a new ADR artifact tree):

A decision is durable when all three hold:

Hard to reverse — the cost of changing your mind later is meaningful
Surprising without context — a future reader will wonder "why did they do it this way?"
The result of a real trade-off — genuine alternatives existed and one was picked for specific reasons

Approach:

One paragraph in cadence-core/workflows/context.md: mark decisions that pass all three as durable/carried-forward; the rest stay phase-local.
No docs/adr/ tree, no glossary/ubiquitous-language import (Cadence's CONTEXT.md is already a decisions+criteria doc, not a glossary — different artifact, same filename; don't collide).

Benefit: the decisions worth remembering resurface when relevant; trivial ones don't clutter recall. Cheapest item in the v1.2.0 scope.

Scoped for v1.2.0.

**Source:** skills-analysis session, 2026-07-18 (comparison against Matt Pocock's `domain-modeling`). `cad-context` records phase decisions (`D-01`, `D-02`, …) and carries them forward / resurfaces them via builtin recall. But every decision is treated equally — there's no filter separating load-bearing decisions from throwaway ones, so recall competes trivial and durable decisions for attention. Borrow the sharp **three-part ADR-worthiness test** as a *promotion* criterion (NOT a new ADR artifact tree): A decision is **durable** when all three hold: 1. **Hard to reverse** — the cost of changing your mind later is meaningful 2. **Surprising without context** — a future reader will wonder "why did they do it this way?" 3. **The result of a real trade-off** — genuine alternatives existed and one was picked for specific reasons **Approach:** - One paragraph in `cadence-core/workflows/context.md`: mark decisions that pass all three as durable/carried-forward; the rest stay phase-local. - **No** `docs/adr/` tree, **no** glossary/ubiquitous-language import (Cadence's `CONTEXT.md` is already a decisions+criteria doc, not a glossary — different artifact, same filename; don't collide). **Benefit:** the decisions worth remembering resurface when relevant; trivial ones don't clutter recall. Cheapest item in the v1.2.0 scope. _Scoped for v1.2.0._

crenshawdev commented

2026-07-23 13:35:56 +00:00

(Migrated from github.com)

Delivered in v1.2.0 (DEC-01). cad-context now marks a decision durable only when it passes a three-part filter (hard-to-reverse, surprising-without-context, and the result of a real trade-off). Durable decisions are written under a ## Durable decisions heading and resurface via recall; phase-local decisions stay under ## Decisions, and legacy CONTEXT.md files resurface unchanged. Shipped in #34, tag v1.2.0.

Delivered in v1.2.0 (DEC-01). `cad-context` now marks a decision durable only when it passes a three-part filter (hard-to-reverse, surprising-without-context, and the result of a real trade-off). Durable decisions are written under a `## Durable decisions` heading and resurface via recall; phase-local decisions stay under `## Decisions`, and legacy CONTEXT.md files resurface unchanged. Shipped in #34, tag v1.2.0.