Lighten the curation tier and right-size execution — raise the ADR bar, enforce true one-line log entries, deterministic-by-default incremental log:audit

0070-lighten-curation-and-right-size-execution

decision read as Explain confidence verified status active 2026-06-20 owner forward-deployed-engineer
Reversibility
two-way door

DEC-0070 — Lighten the curation tier and right-size execution

Reversibility: two-way door — four CLAUDE.md rule changes plus a log-audit.mjs default flip, an incremental watermark, and one agent/skill de-dup. Revert any piece and the prior discipline returns. The durable commitment is the principle (curation ceremony must stay proportional to its payoff), not this exact wiring.

Context

After a session that shipped several verified slices (DEC-0059/0068/0069), the operator flagged that the discipline had grown heavy: "we really need to reduce the amount of logging we are doing or speed up the way we work." Ground-truth check confirmed it. Defer the heavy curation pass off the hot path — terse log stub + kb:check now, pnpm log:audit later had already moved the heavy judgment pass off the hot path and mandated a true one-line log.md entry — but practice had drifted: log entries had re-bloated into 300–600-word paragraphs that duplicate the linked ADR's rationale (the same SSOT violation DEC-0061 set out to end), the ADR count had reached ~69 with some entries recording implementation choices inside an already-decided frame rather than new direction, and pnpm log:audit's LLM pass was timing out at 180 s over an unbounded 33 MB trace buffer (journal/traces/_pending.jsonl) it re-read in full every run.

Decision

Four tightenings to CLAUDE.md's How we work / Decision-logging discipline, none abandoning DEC-0061's principle:

  1. Raise the ADR bar. A full atomic ADR only when a decision sets or changes direction — a one-way door, a cross-cutting/topology choice, a new principle, or a trade-off a future reader would otherwise re-litigate. Implementation choices within an already-decided ADR's frame do not get their own ADR; they get one log.md line pointing at the parent ADR by id (e.g. … within DEC-00NN's frame). Still record automatically — never ask permission.
  2. Enforce the true one-line log. Each log.md entry is a terse pointer + [[id]], never a second copy of the rationale (one line — a paragraph belongs in the ADR). The legacy essays are retro-shrunk this session (the optional follow-up DEC-0061 filed, Retro-shrink the legacy knowledge/log.md essays to true one-liners (terse line + wiki-link)).
  3. Lighten log:audit (scripts/log-audit.mjs). Deterministic by default (fast, offline); the claude -p reconciliation pass is opt-in behind --llm. Incremental via a per-file byte-offset watermark (journal/audits/.watermark.json) — it reduces only trace bytes appended since the last audit, and a file shorter than its mark (a trace:prune rotation) resets to a full re-read. The opt-in LLM timeout is raised 180 s → 600 s.
  4. Right-size the work to the tool. Make small, well-scoped changes directly (inline edits, a focused script run); reserve subagents for context isolation / parallel fan-out / specialist personas, and multi-agent workflows for genuinely cross-cutting builds. Fewer, better-targeted moves over ceremony.

Also applied (the only casting fix a full agent/skill audit surfaced — the roster is otherwise correctly cast): de-dup qa-reviewerverify-kb. The integrity checklist now lives once in the verify-kb skill; the qa-reviewer agent points at it and adds the adversarial judgment, and both defer the mechanical link/parse checks to pnpm kb:check (DEC-0060).

Consequences

  • Hot-path logging gets cheaper twice over: fewer ADRs authored (only direction-setting ones) and genuinely one-line log entries — the SSOT index DEC-0061 intended, now enforced.
  • log:audit stops timing out: the common case is a sub-second deterministic brief, and even the opt-in --llm pass sees only new traces, not the whole 33 MB buffer.
  • The qa-reviewer/verify-kb de-dup removes the one place the team duplicated a procedure across an agent prompt and a skill (the documented anti-pattern), matching the documentation-engineergithub-markdown pattern.
  • This ADR + its single log line are the dogfood proof: authored under the new bar (a direction change to the discipline → it earns an ADR), one true one-line log entry, kb:check clean.

Review

confidence: verified — built and reproduced this session: CLAUDE.md updated (all four rules); log-audit.mjs deterministic-default + --llm opt-in confirmed, and the byte-offset watermark verified end-to-end (a baseline run reduced 3506 events and wrote .watermark.json; the next run reported 0 new events — incremental, not the full journal); the legacy log.md essays retro-shrunk (see Retro-shrink the legacy knowledge/log.md essays to true one-liners (terse line + wiki-link)); qa-reviewer/verify-kb de-duped and the plugin bundle re-synced (plugin:check OK); pnpm kb:check clean after the pass. The agent/skill audit's two load-bearing hypotheses (starlight-engineer dormant; sitecore-architect should be an agent) were both refuted by the files — no other re-casting done.