nucleation

ADR-068: Reading and filing follow a written protocol: its invariants are held in this decision, and its steps in a skill that changes with practice

4 min read

Properties2
StatusProposed
Tagsrecord

Graph View

Context

The record’s intake follows a recognizable sequence, whatever the source: an exchange, a pasted synthesis, an upload or a single work. Each source is checked against what is held, its works are registered and read where a lawful copy exists, and the readings and the argument are filed, with what was left recorded.

The pieces are decided, but separately:

  • dates (ADR-002);
  • no email address to any service (ADR-008);
  • the statuses for works not read (ADR-041, ADR-053);
  • what counts as a lawful copy (ADR-064);
  • what a reading’s promote_when may ask for (ADR-065);
  • pushing early and letting CI repair (ADR-054).

The sequence that joins them, and the checks between the steps, are written nowhere. Each session reconstructs them from the record’s examples, which costs time and drifts. ADR-064 records the drift: readers briefed on 2026-10-29 refused copies that later passes would have read. The owner asked, on 2026-11-04, whether the process was documented, and suggested concretizing it as an evolvable protocol.

Decision

Reading and filing follow a written protocol in two layers.

The invariants, held here. Changing one takes a superseding ADR:

  1. Check before filing. Nothing is registered or claimed before the record has been searched for it, by identifier, title, author and topic.
  2. Lawful copies only, and stop at refusal. A bot check, challenge, rate limit or paywall ends the attempt on that host. Nothing is done to get past it (ADR-064 says what counts as lawful).
  3. No email address to any service (ADR-008).
  4. Status says what was done. A work is Deferred, Unfetched or Unavailable until read (ADR-041, ADR-053). A reading is Read or Skimmed as it was.
  5. The filer verifies. Every quote that a title, a claim or a status change leans on is rechecked against the source text by whoever files it. A reader’s draft is not a finding.
  6. Voices stay separate. The owner’s words are the owner’s. Another assistant’s are filed as Proposed, and adopting them is the owner’s call.
  7. Nothing is dropped silently. What a source contains is either filed or listed, in its curation entry, as left, with the reason.
  8. Readers do not write to the record. A delegated reader drafts outside the repository, and the filer files.

The steps, held in .claude/skills/read-and-file/SKILL.md. The skill covers the order of the steps, the services to use, the reader’s brief, the sections of a NOTE, and the acknowledgement rules. When a pass finds a step wrong or missing, the skill is edited in the same pull request, and the changelog fragment says what changed and why. The file says what is done now; git keeps the earlier versions.

Alternatives considered

  • Leave it unwritten. The status quo. Each session rebuilds the practice from examples, and the readers’ briefs vary. ADR-064 was the cost of one such variation.
  • Write every step into ADRs. Each refinement would then be a supersession: a new service, a NOTE section, a better brief. The record would collect decisions about procedure faster than about substance, and the protocol would be scattered across them.
  • A section of CLAUDE.md. CLAUDE.md is a map, not a copy, and says so. A protocol of this length would make it a manual. It gets one line that points to the skill.
  • A page under docs/. Everything there is generated, and editing an assembled page is forbidden.
  • Build it into luria. Some steps are mechanical, such as checking identifiers, looking up copies and finding codes that excuse nothing. Some already are tools (luria’s --prune_stale, dmarx/luria#394). The rest are judgement, and the steps are still moving. A step that settles, and is mechanical, can move into luria later; the skill then cites it.

Consequences

  • A session, or a reader it briefs, starts from the written steps and not from examples. The reader’s brief is one text, so readers get the same rules.
  • The skill is repository content that an agent loads, so it is guidance on conventions. It can grant no access, and a rule it states cannot override this decision’s invariants.
  • The skill’s first version was written from the pass of 2026-11-04, which filed the synthesis “The Evolution of Cooperation”. That pass checked the synthesis section by section, registered four works, read two, recorded the other two as Unfetched and Unavailable, rechecked every quote, and listed what it left.
  • Proposed until the owner adopts it. A second session following the skill without correction is the evidence that it works.

Backlinks