Context
This session's #13390 friction→gold: a 1-line local-model config-default change was mis-built as a resolveLocalModelChatContextBand resolver wired through the AiConfig state provider (ADR 0019 violation), rubber-stamp-reviewed, ~20 turns of negative-ROI churn — because the cheap prior-art research was skipped (designed-from-priors). Operator diagnosis (@tobiu): V-B-A is the tool calls before designing, and skills + turn-memory have hit a ceiling enforcing it as vague discipline (~20-50 tickets tried). A live test confirmed query_raw_memories is fast + cheap + high-signal (10 calls mapped the whole context-window/graph/summaries problem space). Operator-directed this turn: "a 1-liner AGENTS.md strengthening and skills updates feels worth it; pr-review is the last line of defense."
The Problem
V-B-A's cheapest, highest-ROI, most-skipped form is the prior-art sweep (query_raw_memories / memory-mining). The memory-mining skill exists but only triggers on regressions / architectural-claims — NOT before implementations or PR-reviews, the two highest-leverage gates. So the sweep is opt-in discipline, skipped under velocity bias → re-derivation + the #13390 waste class.
The Architectural Reality
turn-memory-pre-flight Step 2 = lifecycle event → Skill. .claude/CLAUDE.md is a symlink mirror of AGENTS.md (edit AGENTS.md only). Precedents: the §0 Prio-0 gate (#12276/#12277) added a judgment-first gate to these same review skills; the MX flywheel (#12488→#12493→#12497) mechanized a class via a lint.
The Fix (3 minimal edits)
AGENTS.md §verify_before_assert (core-value sharpening, 1-liner): name the prior-art sweep as V-B-A's cheapest/most-skipped form; mandatory before any implementation or PR-review; #13390 anchor; PR-review = last line of defense..agents/skills/memory-mining/SKILL.md: extend the trigger (frontmatter + body) to add "(3) before beginning an implementation OR a PR-review.".agents/skills/pr-review/SKILL.md: a line at the gate — run the sweep before reviewing.
Decision Record impact
aligned-with the §verify_before_assert core value + the §0-gate precedent (#12277). No ADR.
Out of Scope (the mechanical follow-up)
The stronger enforcer is a mechanical body-lint anchor (a ## Prior-art sweep section required in PR + review bodies, like lint-pr-body's existing anchors) — the §0→lint progression (cf. #12276→#12277→skill-manifest-lint). Deferred to a follow-up; this ticket is the discipline-layer strengthening (the operator-directed shape). Also out: editing ticket-intake/pull-request (covered by the memory-mining trigger extension + the AGENTS.md mandate). A .codex/CODEX.md line is optional extra reinforcement only — NOT required parity: the AGENTS.md paragraph already reaches Codex always-loaded via Codex's native root-AGENTS.md project-doc discovery (.codex/CODEX.md is a separate additive UserPromptSubmit hook, not the AGENTS.md load path). See the PR's load-effect audit.
Acceptance Criteria
Contract Ledger (consumed-surface contract — T3)
| Consumed surface |
Contract (what it now mandates) |
Consumer |
Load mechanism |
AGENTS.md §verify_before_assert |
a 3–10-call query_raw_memories/query_summaries prior-art sweep before the first design sentence OR review verdict |
every Claude and Codex agent |
always-loaded by both harnesses — Claude via .claude/CLAUDE.md → ../AGENTS.md; Codex via native root-AGENTS.md project-doc discovery (AGENTS.md is Codex's native agent-instructions file) |
memory-mining/SKILL.md trigger (3) (frontmatter + body) |
the skill fires before an implementation OR a PR-review |
both-harness skill routers |
on-demand, shared (.claude/skills/* → ../../.agents/skills/*) |
pr-review/SKILL.md gate line |
sweep the PR's decision space before scoring (last line of defense) |
reviewers |
on-demand, shared |
skills.manifest.json description mirror |
exact mirror of the memory-mining frontmatter description |
lint-skill-manifest CI |
CI-only (no agent-context load) |
ProgressiveDisclosureSkills.md + CodebaseOverview.md |
reflect the new trigger in the human-facing skill docs |
doc readers + lint-skill-manifest downstream-docs gate |
human docs (no agent-context load) |
Implemented PR diff (PR #13399) matches this ledger 1:1 — six surfaces, the three discipline edits + the three mechanical lint-sync surfaces.
Slot-rationale (Substrate-Accretion-Defense)
Keep: high frequency (every implementation + review) × high severity (#13390 = ~20 wasted turns) × now-enforceable (a concrete tool, not vague). Mechanizes the V-B-A-before-implement class the prior ~20-50 discipline tickets couldn't bind. Net ≈ +4 lines across 3 always-loaded/shared files; operator-directed shape.
Related
Operator friction→gold (this session). Precedents: §0 gate #12276/#12277; MX flywheel #12488→#12493→#12497; #12555 sweep-before-create_issue. Sibling: Discussion #13397 (the post-v13.1 harness auto-version). Empirical anchor: #13390.
Release classification: substrate/process (NOT v13-release-blocking) → boardless.
Origin Session ID: c69a7a2e-d2dd-4e73-bacd-005f3e3f7d43
Context
This session's #13390 friction→gold: a 1-line local-model config-default change was mis-built as a
resolveLocalModelChatContextBandresolver wired through the AiConfig state provider (ADR 0019 violation), rubber-stamp-reviewed, ~20 turns of negative-ROI churn — because the cheap prior-art research was skipped (designed-from-priors). Operator diagnosis (@tobiu): V-B-A is the tool calls before designing, and skills + turn-memory have hit a ceiling enforcing it as vague discipline (~20-50 tickets tried). A live test confirmedquery_raw_memoriesis fast + cheap + high-signal (10 calls mapped the whole context-window/graph/summaries problem space). Operator-directed this turn: "a 1-liner AGENTS.md strengthening and skills updates feels worth it; pr-review is the last line of defense."The Problem
V-B-A's cheapest, highest-ROI, most-skipped form is the prior-art sweep (
query_raw_memories/memory-mining). Thememory-miningskill exists but only triggers on regressions / architectural-claims — NOT before implementations or PR-reviews, the two highest-leverage gates. So the sweep is opt-in discipline, skipped under velocity bias → re-derivation + the #13390 waste class.The Architectural Reality
turn-memory-pre-flightStep 2 = lifecycle event → Skill..claude/CLAUDE.mdis a symlink mirror ofAGENTS.md(editAGENTS.mdonly). Precedents: the §0 Prio-0 gate (#12276/#12277) added a judgment-first gate to these same review skills; the MX flywheel (#12488→#12493→#12497) mechanized a class via a lint.The Fix (3 minimal edits)
AGENTS.md§verify_before_assert(core-value sharpening, 1-liner): name the prior-art sweep as V-B-A's cheapest/most-skipped form; mandatory before any implementation or PR-review; #13390 anchor; PR-review = last line of defense..agents/skills/memory-mining/SKILL.md: extend the trigger (frontmatter + body) to add "(3) before beginning an implementation OR a PR-review.".agents/skills/pr-review/SKILL.md: a line at the gate — run the sweep before reviewing.Decision Record impact
aligned-withthe§verify_before_assertcore value + the §0-gate precedent (#12277). No ADR.Out of Scope (the mechanical follow-up)
The stronger enforcer is a mechanical body-lint anchor (a
## Prior-art sweepsection required in PR + review bodies, likelint-pr-body's existing anchors) — the §0→lint progression (cf. #12276→#12277→skill-manifest-lint). Deferred to a follow-up; this ticket is the discipline-layer strengthening (the operator-directed shape). Also out: editingticket-intake/pull-request(covered by thememory-miningtrigger extension + the AGENTS.md mandate). A.codex/CODEX.mdline is optional extra reinforcement only — NOT required parity: theAGENTS.mdparagraph already reaches Codex always-loaded via Codex's native root-AGENTS.mdproject-doc discovery (.codex/CODEX.mdis a separate additiveUserPromptSubmithook, not the AGENTS.md load path). See the PR's load-effect audit.Acceptance Criteria
AGENTS.md §verify_before_assertnames the prior-art sweep as mandatory before implementation + PR-review (1-liner; #13390 anchor; pr-review = last line of defense).memory-miningSKILL.md trigger extended to the implementation + PR-review gates (frontmatter + body).pr-reviewSKILL.md gate mandates the sweep before reviewing.skill-manifest-lint+lint-pr-bodygreen; net accretion minimal (~1-liners).Contract Ledger (consumed-surface contract — T3)
AGENTS.md §verify_before_assertquery_raw_memories/query_summariesprior-art sweep before the first design sentence OR review verdict.claude/CLAUDE.md→../AGENTS.md; Codex via native root-AGENTS.mdproject-doc discovery (AGENTS.mdis Codex's native agent-instructions file)memory-mining/SKILL.mdtrigger (3) (frontmatter + body).claude/skills/* → ../../.agents/skills/*)pr-review/SKILL.mdgate lineskills.manifest.jsondescription mirrormemory-miningfrontmatter descriptionlint-skill-manifestCIProgressiveDisclosureSkills.md+CodebaseOverview.mdlint-skill-manifestdownstream-docs gateImplemented PR diff (PR #13399) matches this ledger 1:1 — six surfaces, the three discipline edits + the three mechanical lint-sync surfaces.
Slot-rationale (Substrate-Accretion-Defense)
Keep: high frequency (every implementation + review) × high severity (#13390 = ~20 wasted turns) × now-enforceable (a concrete tool, not vague). Mechanizes the V-B-A-before-implement class the prior ~20-50 discipline tickets couldn't bind. Net ≈ +4 lines across 3 always-loaded/shared files; operator-directed shape.
Related
Operator friction→gold (this session). Precedents: §0 gate #12276/#12277; MX flywheel #12488→#12493→#12497; #12555 sweep-before-
create_issue. Sibling: Discussion #13397 (the post-v13.1 harness auto-version). Empirical anchor: #13390.Release classification: substrate/process (NOT v13-release-blocking) → boardless.
Origin Session ID: c69a7a2e-d2dd-4e73-bacd-005f3e3f7d43