# Design notes

Why the prompt is shaped this way, and which alternatives were rejected. Read this before changing a
module: most "improvements" to prompts are the removal of a constraint that was doing work.

## The problem statement

A reusable agent prompt has to satisfy four requirements that pull in different directions:

| Requirement | Tension |
|---|---|
| Universal — works for any subject | a universal prompt drifts into vagueness |
| Specialized — answers like a practitioner | a specialized prompt cannot be reused |
| Verifiable — a reviewer can check it | verification costs tokens and patience |
| Portable — no tool names | portability removes the hooks that make a prompt concrete |

The design resolves the tension by **splitting the prompt into invariants and a variable part**: what
must be true in every domain lives in M3–M8, and what changes per domain lives in M2, M10 and the
examples. A new domain edits only the variable part.

## The two-card decision

Everything begins with two cards:

- **Task Card (M1)** — what is being asked, for whom, with which constraints, and explicitly what is
  out of scope.
- **Domain Card (M2)** — who the practitioner is, which vocabulary and skills the job needs, which
  facts must be verified, and what "done" means.

Rejected alternatives:

| Alternative | Why it was rejected |
|---|---|
| A single long checklist | the agent skips it; a checklist without a decision point is decoration |
| "Think step by step" | improves fluency, not correctness; it produces confident errors faster |
| A role paragraph ("you are a world-class engineer") | changes tone, not behaviour; unverifiable |
| A domain router with a fixed list of domains | the list is wrong the moment a new subject appears |
| Few-shot examples only | examples teach the surface; the cards teach the decision |

The cards work because they are **outputs the agent must produce before acting**, not instructions it
must remember. A written card can be reviewed, contradicted and versioned; an internal intention
cannot.

## Why three evidence labels

Two labels (`fact` / `guess`) collapse under pressure: everything becomes a fact with a hedge. Three
labels force a decision, because `[assumption]` must name its consequence and `[inference]` must name
its premises.

The labelling also fixes a real failure seen in practice: an agent reports "tests pass, therefore the
feature works" — an inference whose premise (that the tests cover the feature) is untested. Under M4
that sentence is `[inference]`, and the premise becomes visible.

## Why a Context Ledger instead of "use the context"

"Use all available context" produces two failure modes at once: unbounded ingestion and unsourced
claims. A ledger with five columns — source, type, claim, confidence — makes both visible. It is
small enough to maintain inside an answer and precise enough that a reviewer can spot a claim whose
source does not support it.

Priority order (current message > attachments > earlier turns > other threads > tree > public web)
encodes one rule: **intent comes only from the user, evidence may come from anywhere**.

## Why the operating loop ends in "record"

Plans are cheap; unrecorded changes are expensive. Requiring the agent to state what changed, where,
and how to undo it turns every step into an auditable unit and makes rollback a first-class outcome
rather than an afterthought.

## Why the gate is twelve items and not forty

A gate longer than twelve items is not run. Twelve is what still fits on one screen and can be reported as a
single line (`gate 12/12`). The two items that fail most often — evidence coverage and verification —
are the reason the other ten are not enough on their own.

## Why the failure-mode table exists

The table in M9 is the only part of the prompt that names the agent's own tricks. Each row pairs a
recognizable symptom with a specific counter, so a reviewer can say "this is failure mode 4" instead
of arguing about taste. A prompt that does not name its failure modes is optimised for the cases
where it already works.

## Why tool names are absent

Naming a tool couples the prompt to a runtime and to a version. Naming a **capability class** lets the
runtime map it, and forces the prompt to specify what happens when the capability is missing — which
is the case that actually breaks agent workflows. M6's degradation column is the direct consequence.

## What this design does not solve

| Limit | Why it remains |
|---|---|
| A determined agent can still skip the gate | the prompt makes skipping visible, not impossible |
| Judgement about "what matters to the user" is not mechanized | M1's `Deliverable` field narrows it, nothing removes it |
| Long tasks drift over many turns | M5's stop conditions catch some drift; a task-level state file would be needed for the rest |
| Quality of a domain card depends on the author | M10's fifteen-minute budget sets a floor, not a ceiling |

Naming the limits is part of the design: a prompt that claims to solve everything above is itself an
example of failure mode 11 (authority theatre).

## Why a module exists for repeated work

The first version of this prompt had twelve modules and no answer to a specific waste: the same task,
done before, being derived again from zero. The usual fix — "remember things" — fails for a measurable
reason: a retrieval rule that costs a directory walk gets skipped under time pressure, and a rule that
is skipped is worse than absent, because the agent believes it complied.

M13 is therefore built on an asymmetry: **retrieval must cost one command, recording must be validated
by a machine, and reuse must be justified by six questions.**

| Decision | Alternative rejected | Why |
|---|---|---|
| A store of Markdown records plus a CLI | a vector database, or "the model remembers" | inspectable, diffable, works offline, no index to maintain |
| Retrieval prints the reason for each rank | a bare top-5 list | a ranking without reasons cannot be rejected on evidence |
| Applicability is six questions | "check that it applies" | an unstated check is a skipped check |
| Records are deprecated, never deleted | delete the outdated | the audit trail is the reason to trust the store at all |
| One store, one schema | per-agent notes | two stores means two truths, one of them stale |
| Experience ranks below the repository | experience as first-class evidence | a stale recipe applied confidently is the most expensive failure in the set |

## Why the deliverable is an environment, not a persona

The first version of this kit said "work as a senior specialist for the rest of the session". That
sentence is true and nearly useless: it changes how the agent talks, not what survives the window.
The measured consequence: a finished piece of work left nothing behind, so the next round of the same
class started from zero in a fresh session with an agent that knew nothing about it.

Version 1.2.0 moves the output. Specialization now produces an artefact — a registered workspace or a
saved agent — with five parts: rules, a domain card carrying a testable acceptance criterion, worked
examples including a failure, a store of prior work, and a handoff prompt. The persona is a side mode,
and the prompt says so explicitly (M10, failure mode 18).

The gate gained its twelfth item for the same reason. Items 1–11 check the answer; item 12 checks
whether the answer was *delivered*: a directory at a named path, a registration step stated truthfully,
a starting prompt included. Item 12 exists because the failure we produced ourselves was a perfect
workspace nobody had registered.

| Decision | Alternative rejected | Why |
|---|---|---|
| the artefact is a directory the runtime registers | "the agent remembers being a specialist" | the registry is the only thing the next session can see |
| the registration step is named, never assumed | "created — done!" | runtimes differ, and a human click is often unavoidable |
| the handoff prompt is a required output | "now go and work" | the next window has no memory of this one |
| sessions are read through the runtime's index | "analyse your own context only" | the same class of work usually left traces in other sessions |

## Why the gate grew to twelve

Ten tests checked the answer. The eleventh checks the *provenance* of the answer — whether prior work
was retrieved and judged. The twelfth checks *delivery* — whether the reusable environment exists at a
named path and its registration step is stated. Both questions are different from "is this correct",
and both are the ones that vanish when an answer looks finished.

## What this design does not solve

| Limit | Why it remains |
|---|---|
| Retrieval is lexical, not semantic | a synonym mismatch misses a good record; the store says so by returning nothing rather than guessing |
| A record can be wrong and validated | only re-running its check catches that; the 180-day warning is a nudge, not a proof |
| Nothing forces the agent to record | the gate checks reuse, not recording; recording is checked only when a record is created |
| Cross-project experience is not merged | one store per project by design; merging requires a human decision about scope |

## Verification of the design

The structural contracts are checked by `tools/prompt_lint.py`: module completeness, self-check lines,
invariant count, translation pairing, reference integrity, version agreement. The behavioural claims —
that the cards reduce drift, that labels reduce invented facts — are not machine-verifiable from a
document, and `docs/VALIDATION.md` states which of them remain assumptions.