Part VI · Running development

Decisions & ideas: the knowledge registers¶

The registers are the product's institutional memory. Decisions, tech debt, bugs, ideas, screens — typed, numbered, product-scoped records that both humans and agents write and both humans and agents read. Their purpose is blunt: in agent-driven development, a great deal gets decided per hour, and anything decided only in a chat scroll is lost. The registers make "why is it like this?" answerable a year later, with a citable id.

Product shell · Registers

Records, deliberately not artifacts¶

Registers hold records, and records are intentionally not PDLC artifacts. Artifacts are governed documents — phased, schema-sectioned, approved, version-pinned. A record is one atomic statement of fact or intent: we chose X over Y, this shortcut costs us Z, this broke, what if we…. Filing one takes seconds and no ceremony — because a decision-capture mechanism heavier than the decision itself simply doesn't get used, and an unused register is worse than none.

Each record kind carries its own small content schema (validated on write): a decision holds context / decision / consequences; a tech-debt record holds description / impact / remediation; an idea is just a body. One service is the sole writer for all record persistence, so numbering, validation, and provenance can never be bypassed — not by the UI, and not by an agent tool.

Identity: numbered, citable, permanent¶

Every record receives a per-product, per-kind sequence at creation, displayed as AD-7 (an Architecture Decision Record), TD-3 (a Tech-Debt Record), BUG-12, SCR-4. Sequences are assigned transactionally and never reused. This is what makes records citable: an artifact section, a review finding, or an agent's reasoning can reference AD-7 and mean exactly one thing forever. Ideas display without a prefix on purpose — the ideas list is a chronological backlog ("capture first, judge later"), not a numbered register.

Capture: two doors, one register¶

Humans, in the UI¶

Each register page has its own capture affordance, sized to its friction budget:

• Decisions — a Record decision dialog: title plus the three ADR fields (context, decision, consequences).
• Ideas — one inline input; type, press ⏎, captured. No dialog, no fields.
• Tech debt, bugs, screens — structured create dialogs matching their content schemas.

Agents, through tools¶

Agents file records through a dedicated records tool server — an internal, loopback MCP server exposing create_record, update_record, delete_record, and list_records. Two properties make agent capture trustworthy:

• Provenance is auto-filled, never self-declared. When an agent creates a record, the system resolves which agent, in which phase, for which feature and product from the agent's bound session — the agent cannot claim to be someone else or attach its record to the wrong feature. The record lands with authorKind: agent and the authoring agent's identity, and register tables show it: the "By" column distinguishes agent-filed from human-filed rows.
• Authoring is phase-gated. Which record kinds an agent may file depends on which phase it is working in:

The gate encodes a simple governance idea: decision-making phases file decisions. Architectural and tech-debt calls are genuinely made during IT spec and planning, not only while code is being written — an early execute-only gate rejected a perfectly correct ADR filed by the IT-spec tech lead, and the gate was widened. UX decisions, conversely, belong inside the UX artifact's own design-decisions section, so the UX phase files design-system gaps but not ADRs. Epic-level phases cannot file records yet — record provenance is feature-scoped today, and an epic-scoped provenance model is a known follow-up.

Lifecycle: agents propose, humans decide¶

Records move through explicit, per-kind statuses — decisions and debt through open → accepted / rejected / superseded / resolved, bugs through their fix cycle, ideas through open → … → promoted.

Two mechanisms carry the governance weight:

• Human sign-off. Settling a record stamps decidedBy and decidedAt — a named human and a timestamp. An agent can put a decision on the table; only a person moves it to accepted or rejected. When you look at a register, every settled row answers "who signed this?".
• Supersession, not deletion. When a decision is replaced, the new record points at the old one (supersedes), and the old one flips to superseded. The chain of reasoning survives — you can walk from today's decision back through everything it replaced, which is precisely the question ("didn't we try this before?") that erasing history makes unanswerable.

How agents consume the registers¶

Capture is half the value; the other half is that agents read the registers back:

• During any record-authoring phase, agents can list_records — so a dev lead deviating from plan sees the accepted decisions before it deviates, and an engineer meeting an odd constraint can find the ADR that explains it.
• Stable ids make agent citations checkable: when an agent's output says "per AD-7", you can open AD-7 and verify the claim.
• The dev lead's mid-run decisions (including forks forced by findings that collide with frozen acceptance criteria — see the execution workbench) land as decision records with agent provenance, awaiting your sign-off like any other.

From register to roadmap: promotion¶

Ideas and tech-debt records feed delivery directly. The Add-feature flow offers From Idea and From TDR sources: the record's content seeds the feature, the feature permanently stores the record's id as its source record, and the record flips to promoted — stamped with who and when — in the same transaction. Provenance is bidirectional and unbroken: from a shipped feature back to the one-line idea that started it, and from a promoted idea forward to the code it became.

Where to go next¶

• The registers in the product shell: Mission Control.
• Where agent decisions are made: the design workbench and the execution workbench.