Fix system

The fix system is the complement to the review system. Reviews identify problems; the fix system applies corrections. It consumes warn findings from the review DB and produces auditable fix reports.

This system is experimental and opt-in, like the review system it depends on.

Concepts

Warn finding. An actionable finding extracted from a review pair whose canonical outcome is warn. The commonplace-warn-selector command parses these from the ### Findings or ### Summary sections of stored review text.

Fix strategy. A named pattern of review warning + appropriate fix, catalogued in kb/instructions/fix-warnings/fix-strategy-taxonomy.md. Agents classify each fix by strategy name to make fixes auditable and to grow the taxonomy over time.

Fix report. A per-note markdown file in kb/reports/fixes/{note-stem}.fix-report.md that maps each warning to its disposition, the strategy used when a fix is applied, and the status (fixed, rejected, or deferred). Rejected means the finding was judged spurious or inapplicable and the note was deliberately left unchanged; it is distinct from postponing a finding that may be valid.

Pipeline

The fix system sits downstream of the review system:

review gates → review pairs (DB) → warn_selector → fix instruction → edited note + fix report

Reviews are never modified by fixes. The review system owns the assessment; the fix system owns the correction. After fixes land, the next review sweep re-evaluates the note against the same gates.

Components

Warn selector

commonplace-warn-selector builds the fix queue from the review DB.

  • Reads current baseline-backed reviews across all models
  • Selects findings from reviews whose canonical outcome is warn
  • Extracts actionable items from ### Findings sections (lines starting with - warn:)
  • When a warn review has no - warn: items, falls back in order to the ### Summary section, then the whole ### Findings block, then the result-stripped review body
  • Collapses model partitions to one current entry per (note_path, criterion_id), choosing the latest baseline-backed warn review

CLI:

# Grouped summary
commonplace-warn-selector

# Full JSON with review text
commonplace-warn-selector --json

# Filter to specific notes
commonplace-warn-selector --json kb/notes/linking-theory.md

Fix strategy taxonomy

kb/instructions/fix-warnings/fix-strategy-taxonomy.md — a living codebook of named fix patterns. Strategies are organized by the review check they most commonly address but can apply across checks. Current categories:

  • Source residue — stale paths, unframed domain examples, single-source vocabulary, temporal residue
  • Confidence miscalibration — hedge own framework, hedge strength mismatch
  • Grounding — qualifier dropped, scope narrowed, unsourced addition
  • Completeness — boundary case acknowledged

New strategies are added when new-pattern reports from fix sweeps show recurring patterns (3+ instances).

Instructions

Fix one note

Instruction: kb/instructions/fix-warnings/fix-review-warnings.md

  1. commonplace-warn-selector --json {note-path} — get actionable findings
  2. Read the target note in full
  3. For each finding: read the recommendation and context, then decide whether to fix, reject, or defer it
  4. Apply minimal edits to fixed findings and record evidence for rejected findings
  5. Write fix report to kb/reports/fixes/{note-stem}.fix-report.md

Fix descriptions

Instruction: kb/instructions/fix-warnings/fix-descriptions.md

A specialized sub-procedure for description-field warnings from commonplace-validate. Called standalone or by the general fix instruction when it encounters description issues.

Fix sweep

Instruction: kb/instructions/fix-warnings/fix-review-warnings-sweep.md

  1. commonplace-warn-selector --json — build priority queue (sorted by finding count descending)
  2. Delegate per-note fixes to single-use sub-agents (can run in parallel); after verifying each worker's edits and report, close, terminate, or release it before dispatching more work
  3. Report: fixed by strategy, rejected findings, deferred items, new patterns
  4. If new patterns recur (3+ instances), propose adding to the taxonomy

Constraints

  • Minimal edits — fix the warning, not the surrounding prose
  • Don't change arguments — fixes change framing, accuracy, and attribution, not claims or structure
  • Don't remove examples — frame them instead
  • Don't update stored reviews — reviews are regenerated separately
  • Verify before assuming staleness — check whether a flagged path/mechanism actually exists before removing it

Outputs

Fix reports land in kb/reports/fixes/. Each report contains:

  • A table mapping each finding to a strategy, summary, and status
  • A warning-to-fix mapping for auditability
  • Rejected findings with the evidence or reasoning that made the warning inapplicable
  • Deferred items with reasons
  • New patterns not yet in the taxonomy