LearnNewsExamplesServices
Frontmatter
id11604
titleSubstrate governance: skill bloat from premature codification — codify-deferral discipline
stateClosed
labels
documentationenhancementdiscussionaiarchitectureneeds-re-triagemodel-experience
assignees[]
createdAtMay 19, 2026, 12:40 AM
updatedAtJun 3, 2026, 9:36 AM
githubUrlhttps://github.com/neomjs/neo/issues/11604
authorneo-opus-ada
commentsCount4
parentIssue11605
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtJun 3, 2026, 9:36 AM

Substrate governance: skill bloat from premature codification — codify-deferral discipline

Closed v13.0.0/archive-v13-0-0-chunk-12 documentationenhancementdiscussionaiarchitectureneeds-re-triagemodel-experience
neo-opus-ada
neo-opus-ada commented on May 19, 2026, 12:40 AM

Context

Operator framing earlier in 2026-05-18 session (#11598 META): observable pattern of new lessons immediately codifying as skill substrate vs. accumulating into single bigger lesson. Symptoms surfaced as recurring "skill bloat" friction.

V-B-A this turn against last 200 merged PRs: at least 43 gate-additions in 9 days (feat(ci) / feat(hygiene) / feat(agents) / feat(skills) / feat(agentos) with gate/guard/invariant keywords). Many are skill-substrate accretions on top of skill-substrate accretions.

Friction

  • Each lesson immediately becomes its own skill / its own SKILL.md section / its own §X subsection
  • Skill substrate accretes faster than it consolidates (no Lessons → Skill aggregation cadence)
  • Loaded-byte cost compounds; skill discovery becomes harder; routing rules become more numerous
  • Distinct from monkey-patching (symptom-vs-root); this is the granularity failure: right diagnosis, wrong codification scale
  • Example shapes from recent merged PRs (see V-B-A): feat(ci): CI lint for agent PR review bodies + feat(ci): enforce agent PR body template adherence + feat(ci): two-layer body-shape validation + feat(github-workflow/mcp): mechanical body-shape validation — four separate substrate-amendments for what is one underlying lesson (agents produce malformed bodies)

Scope

Codify a codify-deferral discipline:

  1. Accumulation period — new lesson held in scratch substrate (private memory / Discussion comment) for K weeks before promotion to skill substrate
  2. Promotion criteria — promotion requires N independent recurrences across multiple agents/sessions, not single-incident reactive promotion
  3. Consolidation cadence — quarterly (or per-N-skill-additions) audit that groups related lessons into single substrate section vs. parallel sections
  4. Anti-pattern detector — same lesson scope codified in M places = consolidation trigger

Acceptance criteria (stub)

  • Codify-deferral discipline named in ADR or workflow doc (likely ADR 0008 SKILL anatomy amendment, since it owns skill-shape rules)
  • Accumulation period K + promotion criteria N defined (empirical-anchored, not arbitrary)
  • Consolidation cadence + detector signature
  • First-cycle dry-run identifying N current-substrate consolidation candidates
  • Cross-reference with sibling friction tickets (monkey-patch, substrate-bandwidth)

Empirical anchor

  • Operator framing 2026-05-18 session (Discussion #11598)
  • V-B-A: 43 gate-additions / 195 META in 9 days; body-shape-validation cluster (4 separate PRs for one lesson) as concrete consolidation case
  • Companion: ADR 0007 compaction taxonomy is the substrate-side mechanism; this ticket addresses the before-substrate side (don't codify yet)

Cross-refs

  • Refs #11598 META — friction item NOT previously captured as ticket (operator-correction)
  • Related substrate: ADR 0008 SKILL anatomy + authoring contract, ADR 0007 compaction taxonomy, AGENTS.md §friction_to_gold (which can be misread to mean "codify immediately" — this ticket clarifies)
  • Sibling tickets: monkey-patch vs root-cause; substrate-bandwidth-saturation

Priority

Team to triage. Related to substrate-bandwidth ticket but addresses a distinct mechanism (granularity vs. surface-symptom).