Prompt Atom Extraction & Formalization
Convert loose operator prose into atoms: minimal, classified, machine-readable units of intent that registries can store, pipelines can route, and future sessions can execute without re-interpreting the original wall of text.
Why this exists
Operator intent arrives packed — one dense paragraph can carry a standing law, two directives, a constraint, and an open question. Left as prose, that intent is executable only by whoever re-reads and re-derives it. Atomized, each unit gets an ID, a class, a lifecycle state, and provenance — it becomes governable. The doctrine: atoms are permanent; extraction is additive; nothing in the source is destroyed by being formalized.
The atom classes
| Class |
Nature |
Lifetime |
Example |
| law |
standing rule; governs all future behavior |
permanent until amended |
"nothing local-only — every artifact git-tracked AND pushed" |
| value |
weighting/preference; shapes choices without mandating one |
durable |
"prefer user coinages over standard vocabulary" |
| directive |
one concrete executable action |
until DONE |
"register the 5 bench agents in fleet.yaml" |
| constraint |
boundary on how any action may be done |
scoped or permanent |
"never chezmoi add over existing source without diffing" |
| question |
open decision owned by a human |
until answered |
"GCP_SA_KEY provisioning — enable CI deploys?" |
| branch-vector |
a fork in possible futures; options held in superposition |
until collapsed |
"skills live in domus OR a-i--skills — decide before next install" |
The three states
- RAW — verbatim source span, untouched. Always preserved (quoted or referenced by span), never edited.
- CLEANED / FORMALIZED — the intent restated minimally in normalized language, classified, given frontmatter.
- ELEVATED — the atom generalized to its standing form: stripped of incident-specific detail, linked to related atoms, ready for constitutional or registry placement. Only laws, values, and constraints elevate; directives and questions resolve instead.
Every atom records which state it is in; an extraction pass may legitimately stop at CLEANED.
Workflow
1. Segment the source
- Split the text at intent boundaries, not sentence boundaries — an intent is one irreducible "do/never/prefer/decide" unit.
- Dense prompts pack abstractions: expect 3–10 atoms per operator paragraph. Under-segmentation (one atom per message) is the dominant failure.
- Assign each segment a provenance span:
{file, line-range} or {session-id, message-index}.
2. Classify
- Apply the class table. Disambiguation tests:
- Would it still bind next month? → law/value/constraint, not directive.
- Does it command an action or bound an action? → directive vs constraint.
- Can the agent resolve it alone? If no → question.
- Are multiple mutually-exclusive futures named without choosing? → branch-vector.
- When torn between law and value: laws are violated, values are traded off. If you can imagine a sanctioned trade-off, it's a value.
3. Formalize into frontmatter
- id: ATM-NNNNNN # mint from the registry's counter — never invent ranges
class: constraint
state: CLEANED
text: "Never `chezmoi add` over existing source without `chezmoi diff` first."
raw: "…also for god's sake diff before you chezmoi add anything again…"
provenance: {session: 8bb8f846, message: 41}
captured: 2026-06-07
status: OPEN # OPEN | DONE | ANSWERED | COLLAPSED | SUPERSEDED-BY:{id}
links: [ATM-013811] # related atoms; liberal linking
tags: [chezmoi, destructive-ops]
Rules:
- Mint IDs from the registry's own counter surface — read it, claim the range, write back; never guess the next ID.
raw is mandatory: the verbatim or span-referenced source. Formalization without provenance is paraphrase, not extraction.- One intent per atom. If the
text field needs "and", split it.
4. Elevate (when warranted)
For laws/values/constraints that recur across ≥2 independent sources:
- Strip incident detail ("in the limen repo" → gone, unless scope-bound).
- Link the supporting atoms as evidence.
- Mark
state: ELEVATED and route to the appropriate standing surface (constitution tier, reliquary, registry) by pointer — the atom stays in the registry; the surface cites it.
5. Append and report
- Append atoms to the registry surface (append-only; existing atoms are never edited by an extraction pass — supersession is a new atom with
SUPERSEDED-BY back-link).
- Emit the provenance map and counts: atoms by class, by state, plus the segments deliberately not atomized (conversational filler) so reviewers can audit the discard decisions.
Anti-patterns
- Atomizing the assistant's restatement instead of the operator's words. Extract from source turns only.
- Editing RAW. The verbatim layer is evidence; all normalization happens in CLEANED.
- Minting IDs by pattern-matching the last seen ID. Registry counters exist precisely because parallel sessions race; read-claim-write.
- Eliding the boring atoms. Constraints embedded in rants ("never do X again") are the highest-value extractions and the most commonly skipped.
- Elevating from a single occurrence. One strong statement is a CLEANED constraint; elevation requires recurrence.
1---2name: prompt-atom-formalization3description: Scan rough markdown, session exports, or pasted prose and isolate each core intent into a structured prompt atom — classified as law, value, directive, constraint, question, or branch-vector — then rewrite it into machine-readable YAML frontmatter per the RAW → CLEANED/FORMALIZED → ELEVATED doctrine. Triggers on "prompt atom extraction pass", "atomize this", "formalize these prompts", or converting loose operator text into registry-grade atoms.4license: MIT5---6
7# Prompt Atom Extraction & Formalization
8
9Convert loose operator prose into atoms: minimal, classified, machine-readable units of intent that registries can store, pipelines can route, and future sessions can execute without re-interpreting the original wall of text.
10
11## Why this exists
12
13Operator intent arrives packed — one dense paragraph can carry a standing law, two directives, a constraint, and an open question. Left as prose, that intent is executable only by whoever re-reads and re-derives it. Atomized, each unit gets an ID, a class, a lifecycle state, and provenance — it becomes governable. The doctrine: **atoms are permanent**; extraction is additive; nothing in the source is destroyed by being formalized.
14
15## The atom classes
16
17| Class | Nature | Lifetime | Example |
18|-------|--------|----------|---------|
19| **law** | standing rule; governs all future behavior | permanent until amended | "nothing local-only — every artifact git-tracked AND pushed" |
20| **value** | weighting/preference; shapes choices without mandating one | durable | "prefer user coinages over standard vocabulary" |
21| **directive** | one concrete executable action | until DONE | "register the 5 bench agents in fleet.yaml" |
22| **constraint** | boundary on how any action may be done | scoped or permanent | "never chezmoi add over existing source without diffing" |
23| **question** | open decision owned by a human | until answered | "GCP_SA_KEY provisioning — enable CI deploys?" |
24| **branch-vector** | a fork in possible futures; options held in superposition | until collapsed | "skills live in domus OR a-i--skills — decide before next install" |
25
26## The three states
27
28- **RAW** — verbatim source span, untouched. Always preserved (quoted or referenced by span), never edited.
29- **CLEANED / FORMALIZED** — the intent restated minimally in normalized language, classified, given frontmatter.
30- **ELEVATED** — the atom generalized to its standing form: stripped of incident-specific detail, linked to related atoms, ready for constitutional or registry placement. Only laws, values, and constraints elevate; directives and questions resolve instead.
31
32Every atom records which state it is in; an extraction pass may legitimately stop at CLEANED.
33
34## Workflow
35
36### 1. Segment the source
37- Split the text at intent boundaries, not sentence boundaries — an intent is one irreducible "do/never/prefer/decide" unit.
38- Dense prompts pack abstractions: expect 3–10 atoms per operator paragraph. Under-segmentation (one atom per message) is the dominant failure.
39- Assign each segment a provenance span: `{file, line-range}` or `{session-id, message-index}`.
40
41### 2. Classify
42- Apply the class table. Disambiguation tests:
43 - Would it still bind next month? → law/value/constraint, not directive.
44 - Does it command an action or bound an action? → directive vs constraint.
45 - Can the agent resolve it alone? If no → question.
46 - Are multiple mutually-exclusive futures named without choosing? → branch-vector.
47- When torn between law and value: laws are violated, values are traded off. If you can imagine a sanctioned trade-off, it's a value.
48
49### 3. Formalize into frontmatter
50
51```yaml
52- id: ATM-NNNNNN # mint from the registry's counter — never invent ranges
53 class: constraint
54 state: CLEANED
55 text: "Never `chezmoi add` over existing source without `chezmoi diff` first."
56 raw: "…also for god's sake diff before you chezmoi add anything again…"
57 provenance: {session: 8bb8f846, message: 41}
58 captured: 2026-06-07
59 status: OPEN # OPEN | DONE | ANSWERED | COLLAPSED | SUPERSEDED-BY:{id}
60 links: [ATM-013811] # related atoms; liberal linking
61 tags: [chezmoi, destructive-ops]
62```
63
64Rules:
65- **Mint IDs from the registry's own counter surface** — read it, claim the range, write back; never guess the next ID.
66- `raw` is mandatory: the verbatim or span-referenced source. Formalization without provenance is paraphrase, not extraction.
67- One intent per atom. If the `text` field needs "and", split it.
68
69### 4. Elevate (when warranted)
70For laws/values/constraints that recur across ≥2 independent sources:
71- Strip incident detail ("in the limen repo" → gone, unless scope-bound).
72- Link the supporting atoms as evidence.
73- Mark `state: ELEVATED` and route to the appropriate standing surface (constitution tier, reliquary, registry) **by pointer** — the atom stays in the registry; the surface cites it.
74
75### 5. Append and report
76- Append atoms to the registry surface (append-only; existing atoms are never edited by an extraction pass — supersession is a new atom with `SUPERSEDED-BY` back-link).
77- Emit the provenance map and counts: atoms by class, by state, plus the segments deliberately *not* atomized (conversational filler) so reviewers can audit the discard decisions.
78
79## Anti-patterns
80
81- **Atomizing the assistant's restatement instead of the operator's words.** Extract from source turns only.
82- **Editing RAW.** The verbatim layer is evidence; all normalization happens in CLEANED.
83- **Minting IDs by pattern-matching the last seen ID.** Registry counters exist precisely because parallel sessions race; read-claim-write.
84- **Eliding the boring atoms.** Constraints embedded in rants ("never do X again") are the highest-value extractions and the most commonly skipped.
85- **Elevating from a single occurrence.** One strong statement is a CLEANED constraint; elevation requires recurrence.
organvm-iv-taxis