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
- 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:
- 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.mdline pointing at the parent ADR by id (e.g.… within DEC-00NN's frame). Still record automatically — never ask permission. - Enforce the true one-line log. Each
log.mdentry 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)). - Lighten
log:audit(scripts/log-audit.mjs). Deterministic by default (fast, offline); theclaude -preconciliation 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 (atrace:prunerotation) resets to a full re-read. The opt-in LLM timeout is raised 180 s → 600 s. - 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-reviewer ↔ verify-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:auditstops timing out: the common case is a sub-second deterministic brief, and even the opt-in--llmpass sees only new traces, not the whole 33 MB buffer.- The
qa-reviewer/verify-kbde-dup removes the one place the team duplicated a procedure across an agent prompt and a skill (the documented anti-pattern), matching thedocumentation-engineer↔github-markdownpattern. - 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:checkclean.
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.