Decisions

Workspace → Decisions.

A record of the important choices your team has already made and why. Every approved decision is included in agent context, so future work follows those choices instead of accidentally undoing or reopening them.

The reason this exists, in the code's own words: chat history is a terrible long-term memory.

What a decision holds

Field	Notes
Title	Stated as a rule. "Claims APIs never return raw database entities."
Rationale	Why. Required.
What was considered instead	Optional.
Category	architecture, security, data, process, product, dependency, convention.
Reach	workspace or organization.
Status	active, proposed, superseded or revoked.
Decided on	The real date, not the row's. Defaults to today.
Decided with	"the customer architect", "the pod".
Applies to	Up to 20 scopes.
Confidence	Only on mined proposals.

Scopes

A scope decides which briefs the decision appears in.

Kind	Matches when
path_prefix	A file named in the brief starts with the value.
symbol	A symbol matches exactly, or starts with the value plus a dot.
category	Always.
everywhere	Always.

A decision with no scopes at all is included everywhere.

In the record dialog, the Applies to field is comma-separated: a value containing a / becomes a path prefix, anything else a symbol.

Recording one

Record a decision. The dialog asks for:

Field	Placeholder
Decision (stated as a rule)	Claims APIs never return raw database entities
Why	Contract stability: every column rename would be a breaking API change, and entities leak columns callers have no business seeing.
What was considered instead
Category
Decided with	the customer architect
Applies to (paths or symbols, comma-separated)	src/Controllers, ClaimsRepository

The buttons for recording and mining are shown only to people holding decision.write — owner and organization admin.

The proposed state

A decision can arrive as proposed rather than active. Two things create one:

1. An agent, through the MCP's decisions_made parameter on a change report. It lands with decided_with reading "{session label} (agent session)".
2. Mining, below.

A proposed decision is never injected into any brief. It carries a badge reading "proposed — not yet in any briefing" and a banner sits above the list:

{n} proposed decisions waiting for a person. Nothing proposed reaches any agent until it is approved — approve the real ones, edit what is almost right, dismiss the rest.

Approving one makes it active. Dismissing one deletes it outright — a proposal never bound anyone, so there is no history to keep.

A proposed decision also raises an attention item at disposition decide, urgency 45.

Mining

Find decisions reads the reasons already living in your tickets, constraints and stack, and proposes decisions from them.

It runs as a background job. Leave the page, refresh, come back: the page finds the run still in flight and keeps following it, and the proposals land in the list when it finishes.

Runs in the background — leaving the page does not stop it, and whatever it finds arrives below as proposals for you to approve or dismiss.

It reads at most 25 source items, and produces at most 6 proposals, best-supported first. Each carries a confidence, and the prompt's own calibration guidance is explicit: a ticket or constraint that states the reason scores 80 or more; a pattern that merely implies one scores below 50.

Every mined row is stamped decided_with: "Madebook — mined from the workspace record".

With nothing to read:

There is nothing to mine yet. Decisions are read out of the workspace record — index a repository or import work items first, then run this.

With no provider:

No AI provider is configured, so nothing was mined: decision mining needs a model to read the reasons out of tickets and context.

The proposals show a confidence badge: high confidence at 70 or above, medium at 40 or above, low below.

How a decision reaches an agent

Decisions are section four of eight in a brief, under the heading:

# Decisions already made — do not relitigate

Only active decisions, oldest first, each rendered as the title, the date, and the rationale trimmed to 300 characters.

The matching is the part worth understanding:

• No scopes → always included.
• The caller named no files and no symbols → every active decision is included, with the reason "no files named yet — all active decisions included." An agent opening a session before it knows what it will touch gets everything.
• Otherwise → a scope must match one of the files or symbols involved.

There is no cap on the number of decisions. The section as a whole is capped at 8,000 characters.

Decisions and context health

A session is scored on how many decisions were recorded after it was briefed. Each missed decision costs 40 points on that dimension — weighted per decision, deliberately, because one missed decision out of fifty is not 98% healthy.

The comparison uses when Madebook learned the decision, not the human date on it. Judging by the human date would silently excuse exactly the decisions most likely to be missed: the ones recorded late.

A session that was never briefed scores zero on that dimension.

This is the drift case the landing page describes: a person settles something mid-flight, a session briefed twenty minutes earlier keeps building against the old answer, no file overlaps, no signature moves, and every other check reports a healthy session that is now wrong.

Revoking and superseding

Revoke a decision that no longer holds. It stays in the ledger with its history.

Delete is for entries that were a mistake:

For entries that were a mistake — it disappears from the ledger and from every briefing. A real decision that no longer holds should be revoked instead, so the history says why.

Note. A superseded status and a link to the replacing decision exist in the data, but no page offers a supersede action and nothing reads the link. Revoke the old decision and record the new one.

Questions waiting on you

A sibling page, Workspace → Attention → Questions waiting, holds a different thing: questions an agent stopped at rather than answer for you.

It keeps working on everything the decision does not block — so a short list here is the system working, and a long one means the constitution is not saying enough. Answers you save as workspace decisions land in the Decisions ledger.

Answering one takes a resolution (Approve, Reject, or Answer — the default) and an instruction:

Written for the agent to act on. Name the approved pattern or the answer, not just the verdict.

A switch, Save as a workspace decision, writes the answer into this ledger:

Writes it into the decision ledger so the next session is told before it asks. This is how a queue like this gets shorter.

Approving an architecture question carries a warning, because it is a different permission:

Approving an architecture exception changes what this workspace is held to. It needs permission to amend the constitution, not just to clear the queue.

Each row shows whether the answer has been picked up: read by the agent, or not read yet.

Related

• The execution protocol — how a decision gate is answered.
• Architecture rules
• The brief