Knowledge · Rules · Process

Decision Lifecycle

Govern the lifecycle of decision records — retrieval before deciding, cheap same-turn marking, a born-ratified corpus, and an enforced integrity lint — so we stop re-deciding live rulings and re-proposing rejected ones.

Tags

rule

Overview

Purpose

Govern the lifecycle of decision records — retrieval before deciding, cheap same-turn marking, a born-ratified corpus, and an enforced integrity lint — so we stop re-deciding live rulings and re-proposing rejected ones.

Rules

DL-001: Before any new decision — and before a plan's decision phase — run BOTH pre-gate scans: `sbx decision related "<terms>"` (active rulings) and `sbx decision related "<terms>" --deprecated` (recall: already rejected/parked?). Reading both is mandatory, not optional.

DL-002: If an ACTIVE record already answers the question, do NOT create a new one — point to it. Changing it is a supersession, not a fresh decision.

DL-003: When a new decision conflicts with an active record: if the conflict is 100%-clear from obvious context (both cannot stand; the winner is unambiguous), auto-supersede and mark the old record the SAME turn. If it is anything less than 100%-clear, AskUserQuestion, then deprecate the losing record instantly on the answer. Never leave a known conflict unmarked.

DL-004: Mark superseded/deprecated records the SAME turn via `sbx decision update <id> --status superseded --by <new>` (or `--status deprecated`). The writer is surgical (only status/superseded_by/status_history change; every other byte preserved), so marking is cheap and lossless — deferral to 'next session' is the failure this rule prevents.

DL-005: Decisions are born ratified: a researched, recommended decision is saved with `status: decided`, not `proposed`. There is no proposed tier in normal operation. Legacy proposals were archived; reactivate one with `update <id> --status decided` only when it becomes live again.

DL-006: Never hand-mint an id or `mkdir` a decision dir. `sbx decision create "<title>"` mints a collision-free id (shared git-common-dir counter) and scaffolds a born-`decided` record. Resolve a duplicate id with `sbx decision renumber <id>` (older-by-date keeps it; newer renumbers + records renamed_from).

DL-007: Canonical statuses only: proposed | decided | deprecated | superseded | archived. `superseded` REQUIRES a resolvable `superseded_by` id; `deprecated` is retirement without a replacement. Allowed transitions: proposed→{decided,deprecated,archived}; decided→{deprecated,superseded,archived}; deprecated→archived; superseded→archived.

DL-008: Archiving parks a record (`status: archived`) out of the active pre-gate + list/search, but it stays recallable via `get` and `related --deprecated` and reviewable via `list --status archived`. Archiving is reversible and in-place by default (no dir move).

DL-009: `sbx decision scan --lint` is the integrity guard: parse-failure, duplicate-id, non-canonical-status, missing-pointer, dangling-pointer, location-inconsistent. It runs `--strict` (exit non-zero on any finding) as a merge-gate pre-flight. A decision-touching PR whose diff introduces a finding is blocked with the offending record named.

DL-010: The corpus is read and mutated ONLY through `sbx decision …`. Raw ls/grep on <workspace>/decisions/ (ambiguous ids, cold tiers, and unparseable files make it unreliable) and hand-editing status/pointers outside the surgical writer are both prohibited.