Context
Sub 2 of Epic #10733. Round-2 of AGENTS.md compaction (round-1 was #10511 → PR #10512). Depends on Sub 1 baseline (#10734 — Baseline & inventory) — edits-before-baseline = #10512 partial-scope repeat.
The Problem
AGENTS.md is currently 595 lines / 59,170 bytes — measurably above industry external benchmarks:
- OpenAI Codex
project_doc_max_bytes default: 32 KiB (source) — Neo is ~1.85× over the hard external cap
- Claude Code memory soft target: <200 lines / ≤25 KB (source) — Neo is ~3× over
§0–§23 has accumulated organically without periodic audit. Some sections duplicate content now in skill references/. Some sections are silent+irreversible-failure-class (legal-doc-shape correct) but most are discipline-layer (compactable). The substrate has no decision rule for distinguishing the two.
The Architectural Reality
AGENTS.md (loaded into every turn via harness-specific symlinks: .claude/CLAUDE.md → ../AGENTS.md, .gemini/GEMINI.md → ../AGENTS.md, .codex/CODEX.md per harness scoping)- Existing structure: §0 Critical Gates, §1–§23 mixed discipline + reference + lifecycle. Some sections are anchors for skills and shouldn't move; others are fine to extract.
- Skill Adherence rationale (the half-read cost equation) is currently un-codified — agents skim manuals, ship partial output, pay 3-5× across correction cycles. No clause exists in AGENTS.md framing this cost explicitly
The Fix
Apply a 3-axis slot rule (per @neo-gpt's Depth Challenge extending @neo-gemini-3-1-pro's 30% rule):
Slot decision = trigger-frequency × failure-severity × enforceability
- A rare rule with silent+irreversible failure stays in §0 regardless of frequency (e.g., merge gate, ticket-ID gate)
- A frequent rule with low-risk + cheap rediscovery moves to a skill payload
- Enforceability axis: if the rule can be machine-enforced, prose may be the wrong final layer (substrate-vs-discipline trap per @neo-gpt + #10063)
Apply a net-deletion budget: any added clause must DELETE more process text than it adds, OR prove substrate-enforcement. The Skill Adherence Pre-Flight clause itself must net-delete via removed redundancy.
Add the Skill Adherence Pre-Flight clause in §22 (NOT §0 per OQ1 convergence) framed around the half-read cost equation. Concrete shape (revisable):
Skill Adherence Pre-Flight (per-turn). Before triggering a lifecycle skill, state in your reasoning: "I will read the full SKILL.md and its referenced payload before drafting output." Half-reading is empirically 3–5× more expensive than full-reading across correction cycles. Skipping the manual is the higher-cost path, not the lower-cost path.
Document a per-section slot-decision table in AGENTS.md introduction; do NOT rely on a single threshold.
Acceptance Criteria
Out of Scope
- Boot-ramp changes (Sub 3 owns)
- Skill payload extraction beyond §-references already in AGENTS.md (Sub 4 owns)
- Asset template changes (Sub 5 owns)
- Machine-enforcement of currently-documented behaviors — AC7 enumerates candidates only; execution is a separate Epic
- §0 expansion. §0 is mechanically-verifiable invariants only; never the right home for the Skill Adherence clause
Related
- Parent Epic: #10733
- Round-1 predecessor: #10511 (CLOSED) → PR #10512 — partial-scope; this sub completes the "streamline PR skills" portion left incomplete
- Substrate-vs-discipline anchor: #10063 — informs AC7 enumeration of machine-enforcement candidates
- Origin discussion: #10732 (OQ1 + OQ4 + GPT external addendum)
Origin Session ID: 7e52099b-9632-4c67-a2a1-4e1a1ad1c414
Retrieval Hint: query_raw_memories(query="AGENTS.md compaction 3-axis slot rule net-deletion budget Skill Adherence Pre-Flight 10733 10732")
Context
Sub 2 of Epic #10733. Round-2 of AGENTS.md compaction (round-1 was #10511 → PR #10512). Depends on Sub 1 baseline (#10734 — Baseline & inventory) — edits-before-baseline = #10512 partial-scope repeat.
The Problem
AGENTS.mdis currently 595 lines / 59,170 bytes — measurably above industry external benchmarks:project_doc_max_bytesdefault: 32 KiB (source) — Neo is ~1.85× over the hard external cap§0–§23 has accumulated organically without periodic audit. Some sections duplicate content now in skill references/. Some sections are silent+irreversible-failure-class (legal-doc-shape correct) but most are discipline-layer (compactable). The substrate has no decision rule for distinguishing the two.
The Architectural Reality
AGENTS.md(loaded into every turn via harness-specific symlinks:.claude/CLAUDE.md → ../AGENTS.md,.gemini/GEMINI.md → ../AGENTS.md,.codex/CODEX.mdper harness scoping)The Fix
Apply a 3-axis slot rule (per @neo-gpt's Depth Challenge extending @neo-gemini-3-1-pro's 30% rule):
Apply a net-deletion budget: any added clause must DELETE more process text than it adds, OR prove substrate-enforcement. The Skill Adherence Pre-Flight clause itself must net-delete via removed redundancy.
Add the Skill Adherence Pre-Flight clause in §22 (NOT §0 per OQ1 convergence) framed around the half-read cost equation. Concrete shape (revisable):
Document a per-section slot-decision table in AGENTS.md introduction; do NOT rely on a single threshold.
Acceptance Criteria
/memory show//memory/ Codex audit) shows true loaded-byte reduction, not just file-size reduction (per the modularization-not-reduction trap)Out of Scope
Related
Origin Session ID: 7e52099b-9632-4c67-a2a1-4e1a1ad1c414
Retrieval Hint:
query_raw_memories(query="AGENTS.md compaction 3-axis slot rule net-deletion budget Skill Adherence Pre-Flight 10733 10732")