# The deliberation method

How sessions run in this workspace. What gets written is [artifacts.md](artifacts.md).

## Workspace layout

- **Topic folders** — one folder = one long-running topic. Kebab-case noun phrase naming the **inquiry, not the deliverable** (`pricing-research`, not `pricing-report`). Every topic has a `README.md` (the record), a `metadata.md` (the map), and a `TOPICS.md` entry.
- **`metadata/`** — all workspace state: `TOPICS.md` (topic index), `SESSIONS.md` (session ledger), `method-changelog.md` (workspace-local method notes; the harness itself versions via `.claude/harness.json`), `lessons/` (the operator layer: append-only log + always-loaded digest + forecasts), `ops/` (maintenance-agent run-logs), `writing-styles/` (the operator's style registry — one file per register, `reading.md` the default for operator-facing documents). State lives here and nowhere else.
- **External instruments** — code/data a topic depends on (scraper, corpus, pipeline) lives **outside the workspace**, never at the root: this folder holds only topics and the harness. Record the dependency on the depending topic's README (external path + ratification status); exclusions are recorded on the excluder's side.
- **Git** — the workspace **is a git repository** (the `discussion-baseline` agent initializes one). The SessionEnd hook auto-commits each session's changes as one `📝 session close` batch — never per-file commits. Milestone commits by hand are still welcome: `✨` content, `🔧` workspace/method. Root `.gitignore` stays minimal.
- **Grandfathering** — when the method changes, never reshuffle existing artifacts to match. New artifacts follow current rules; old layouts stay, flagged where confusing.
- **Archiving** — a topic whose inquiry is *closed by outside reality* — its design **realized**, its understanding **superseded** — is retired, not deleted: `git mv` its folder into `archived/<topic>/` (history preserved; the folder frozen, kept as record), add a dated archive banner to its README (`📦 ARCHIVED (YYYY-MM-DD) — realized/superseded`: state · reason · pointer to the live source of truth), and move its `TOPICS.md` entry into the **Archived topics** section. Archiving records that a topic is done; live work stops there and nothing valuable is lost.

## Session protocol

A session is one sitting; the durable unit is the topic. Route before substantive work:

1. Read `metadata/TOPICS.md`, the last entry of `metadata/SESSIONS.md`, and the operator digest `metadata/lessons/DIGEST.md` (fallback: list folders, read the first ~15 lines of each README).
2. Match the opening message against the topics. Likely continuation → recommend **that topic only** ("sounds like `<topic>/` — pick it up there?"). Unambiguous → skip the ask, just confirm the folder.
3. No plausible match → ask: continue an existing topic or start new (one-line summaries + open threads).
4. Existing topic → read its `metadata.md`, then its README **fully** before anything substantive. Never re-litigate settled decisions.
5. New topic → create the folder, seed a README (definition + empty Open threads) and a `metadata.md`, add its `TOPICS.md` entry (missing `metadata/` files or git repo → run the `discussion-baseline` agent, don't hand-seed).

Stale index? The README wins — reconcile. Check `.claude/topics-sync.log`; the hook fails silently.

Update the topic README, its `metadata.md`, and `metadata/` **inline, the moment a material change happens** — the hook is the safety net, not the mechanism. At close: provenance entry appended, TL;DR rewritten, Open threads reconciled, `TOPICS.md` matched, the session's `SESSIONS.md` entry updated, touched folders' maps reconciled.

## Context doctrine

Claude thinks best with an empty context and a good map.

- **Map first** — read `metadata.md` before (usually instead of) the files it describes; never load what the map answers.
- **Delegate bulk reading** — sub-agents read the heavy material and return summaries; the main line holds conclusions, not corpora.
- **File early** — disk gets everything valuable the moment it exists; context is never the only copy.
- **Maps stay small** — one line per file; bulk directories get one line total.

## The discussion loop

1. **Dump** — the user lectures, brain-dumps, or asks. Their framing is the raw material.
2. **Sweep** — fan out sub-agents for breadth (expert panels, web research, codebase surveys). Every fan-out sweep **ends with a completeness critic**.
3. **File the raw** — losslessly, per [artifacts.md](artifacts.md); web finds clipped to `references/`.
4. **Synthesize** — verdict first, in chat **and filed**, ending in numbered open questions.
5. **The user narrows** — dispositions are exactly: **accepted / reframed / excluded / deferred**. Reframings override everything prior, including sweep conclusions and your own arguments; concede precisely, not wholesale. Record every disposition in provenance, quoting the ruling verbatim.
6. **Canonize** — only after explicit ratification ("agree / hit it / put it in the document"); run the canonization checklist. Discussion turns get discussion answers, not canon files.

Exclusion grades:

| Label | Strength |
| --- | --- |
| **Excluded by decision** | user ruling, dated — never re-litigate |
| **Excluded by framing** | definitional consequence of a ratified framing |
| **Excluded pending objection** | agent-proposed, stands until the user objects |

## `metadata/` — the state layer

Method lives in the rules (timeless); state lives in `metadata/` (current); topic READMEs stay the deep record.

### `TOPICS.md` — topic index

- YAML frontmatter carries `harness-version:` — the baseline sentinel; **always preserve it**.
- H1 + blockquote preamble (division of responsibility, update triggers).
- Per topic: `` ## `topic-folder/` — <state phrase> `` — the suffix encodes **who it's waiting on** ("synthesis filed, awaiting user reaction").
- One dense routing paragraph: what it is, which artifacts exist (files, dates), headline findings — enough to route without opening the folder.
- Bullets: `**Open:**` (typically "user disposition on the N questions closing `<file>`") · exclusion grades, dated when user rulings · `**Note:**` caveats.
- Retired topics move to an `## Archived topics` section at the bottom — one condensed entry each (why archived: realized/superseded · the live source of truth); a one-line archiving note sits in the preamble. The active list holds only live topics.

### `SESSIONS.md` — session ledger

One entry per session, appended at the bottom. An entry is the session's **summary**, rewritten in place when the session resumes — never a resume-log. Format: `## YYYY-MM-DD — <goal headline>` + bullets: `**Goal:**` (the user's stated aim; update it if it shifts mid-session) · `**Touched:**` · `**Filed:**` (linked) · `**Close state:**` (where it stopped, what it awaits). Entries point into topics; content never lives here.

### `writing-styles/` — the style registry

One operator-owned file per writing register (`reading.md` — the default for documents presented to the operator; `blog.md`, `email.md`, … as the operator introduces them). A style file is instructions to the writer — register, voice, form; the artifact rules' two-audience doctrine is the floor it refines. Style named but file missing → draft it from the operator's instructions in the moment, file it marked unratified, apply it. Machine-facing writing is never styled from here.

### `lessons/` + `ops/` — the operator layer

- `metadata/lessons/` is two-tier: an append-only occurrence **`log/`** (one dated file per maintenance run, never edited, never loaded by default) distilled into **`DIGEST.md`** — the operator profile read at session start (**prior, not canon**; its reading-protocol block governs). Beside them: `forecasts.md` (the operator's falsifiable claims, captured in the moment; resolutions mined for calibration) and `distillation.md` (the maintenance instruction set + admission bar).
- `metadata/ops/` holds maintenance run-logs — cursor + run entries — so abrupt session ends resume cleanly next session.
- The **`lessons-maintenance` agent** does the writing here, with one carve-out: the main agent appends to `forecasts.md` in the moment a falsifiable claim is made. The agent mines the delta of raw session transcripts and the workspace record, appends to the log, and re-distills the digest. It runs **only during user sessions**: at routing, glance at the ops cursor — a session or more behind (or empty) → spawn it in the background; when its run closes, relay its "inferred entries awaiting disposition" line to the operator. Lessons are evidence-linked occurrences in task grammar, never psychological verdicts; AI-inferred entries stand as *observed pending objection* until the operator disposes; capture-only dimensions never enter the digest.

### The SessionEnd hook

Safety net only: `settings.json` → script in `.claude/hooks/`, `$CLAUDE_PROJECT_DIR`-relative. Script: recursion-guard env sentinel · stdin JSON → `transcript_path`, silent exit-0 on anything missing · headless `claude -p`, tool-allowlisted to write **only the two `metadata/` state files**, told to read this rule for the grammars · then **one batched auto-commit** of the session's changes · `nohup … & disown` to outlive the timeout · appends `.claude/topics-sync.log`. Needs `jq` + `claude` on PATH (missing → logged). Failures are logged, never surfaced: stale index → check the log, reconcile by hand.

## Working with the operator

The operator profile lives in `metadata/lessons/DIGEST.md` — maintained by the `lessons-maintenance` agent, loaded at session start, evidence-linked into the layer's log: taste, decision patterns, the blind-spot register, collaboration lessons. It is a **prior, not canon** — it calibrates communication and briefing, never forecloses pushback. Personal content lives there and nowhere else; these rules stay portable and impersonal.

**Sub-agents validate, the main agent judges** (standing rule): agents gather, cross-check, attack; the main agent assembles the deliverable and adjudicates every finding itself. Every validation round is adjudicated on the record — N findings → accepted (reason each) / **rejected as intentional** (reason each); never auto-apply. Overrules carry citations into the raw corpus. Record sweep telemetry in provenance: agents, model, lanes, sources.