Revise an article or note

Type: kb/types/instruction.md

Make the artifact serve the operator's stated purpose without changing what it claims, by assessing first and then running only the passes the assessment recommends.

Prerequisites

  • A purpose in one line: who the reader is and what they should notice or be able to do. If the operator named only the artifact, propose the purpose at the top of the assessment and proceed under it; the operator corrects it if it is wrong.
  • The artifact's claims are settled. A claim in dispute goes to the operator as a question, not into a pass.

Steps

  1. Assess before editing. Read the whole artifact. Report a ranked list of changes, highest value against the purpose first, each with its cost in one phrase and the pass from this directory that would make it. Name the sentence a hostile reviewer would attack first. Say what reads well in one sentence. Recommend only passes whose value against the purpose is clear; an item you would not defend is not recommended. Do not edit.

Two things the passes cannot own belong in the assessment too. For each candidate overclaim, propose whether the sentence is support (may be narrowed) or divergence (defend); the divergence items become the packets' Defend: line unless the operator objects. And list qualifications that have gone stale against the body: a scope bullet qualifying words the body no longer uses, a table cell filed under the wrong row, a cross-note ordinal pointing at the wrong list. These are claim questions for the operator, applied as their own commits after approval, not passes.

  1. Dispatch each recommended pass as a packet. Proceed without waiting; the report gives the operator the chance to interrupt. Run passes one at a time, since they share one write scope. Each pass file carries an effort field: simple passes run in a fresh worker on a cheaper model or lower effort; judgment passes run on the session model, in the current context or a fresh worker. Use a fresh worker when the pass benefits from not having seen the conversation, as the plain-wording and readability passes do; run narrow-overclaims in the parent context, where the conversation is the evidence. Apply one-word swaps and two-sentence narrowings in the parent context rather than as packets. Small scoped edits from different passes may share one packet when its scope is enumerated. The packet is:

Purpose: {the operator's one line} Artifact: {path} Pass: kb/instructions/simplification-passes/{pass}.md Defend: {claims the operator has marked as divergence; a pass may not narrow them} Write scope: {the artifact only | none, return proposals} Return: the pass's report, plus items noticed but not applied, nothing committed

The worker chooses means within the pass. It does not widen the write scope, add claims, or remove evidence.

  1. Integrate. After each pass read the diff, and read every replaced phrase in its full sentence, not in the diff summary; a literal replacement can supply a referent the original left implicit and supply the wrong one. Run commonplace-validate on the artifact, and commit the pass alone with a body saying what it was meant to make true. If the operator reverts part of a pass, record the threshold they applied in the pass file or a memory, so the next run starts from it.

  2. Stop when the recommended passes are done. Report what each pass changed. Items you assessed but did not recommend, and the not-applied items the workers returned, are listed once, not run.

Budget

  • The assessment is one full read. Each pass is one more. Do not re-read linked notes unless a pass names them.
  • A worker gets the artifact path and the packet, never the conversation.
  • Propose-only work (the assessment, the plain-wording list, title proposals) may run in parallel; edits to the artifact run in sequence.
  • Stop when the recommended passes are done. An item not recommended costs nothing; recommending a pass of unclear value costs a read and a diff.

Verify

  • Every applied change traces to a recommended pass.
  • No claim, evidence, or qualification changed unless the operator asked.
  • Each pass has its own commit and validation passed before it.
  • Operator reverts have been recorded as thresholds.

Relevant Notes: