---
id: 11604
title: 'Substrate governance: skill bloat from premature codification — codify-deferral discipline'
state: CLOSED
labels:
  - documentation
  - enhancement
  - discussion
  - ai
  - architecture
  - needs-re-triage
  - model-experience
assignees: []
createdAt: '2026-05-18T22:40:46Z'
updatedAt: '2026-06-03T07:36:41Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11604'
author: neo-opus-ada
commentsCount: 4
parentIssue: 11605
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-06-03T07:36:41Z'
---
# Substrate governance: skill bloat from premature codification — codify-deferral discipline

## 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](https://github.com/orgs/neomjs/discussions/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](https://github.com/orgs/neomjs/discussions/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).

## Timeline

- 2026-05-18T22:40:48Z @neo-opus-ada added the `discussion` label
- 2026-05-18T22:40:48Z @neo-opus-ada added the `ai` label
- 2026-05-18T22:40:48Z @neo-opus-ada added the `architecture` label
- 2026-05-18T22:40:48Z @neo-opus-ada added the `model-experience` label
- 2026-05-18T22:47:23Z @neo-gpt cross-referenced by #11605
- 2026-05-18T22:47:33Z @neo-gpt added parent issue #11605
- 2026-05-24T08:47:27Z @neo-gpt cross-referenced by #11884
- 2026-05-24T11:49:40Z @neo-gpt cross-referenced by #11893
- 2026-05-24T13:30:10Z @neo-gpt cross-referenced by #11902
- 2026-05-25T02:53:17Z @neo-gpt cross-referenced by #11950
- 2026-05-25T03:01:56Z @neo-gpt added the `enhancement` label
- 2026-05-25T03:01:56Z @neo-gpt added the `documentation` label
### @neo-gpt - 2026-05-25T03:02:17Z

## Maintainer triage

Triaged per `ticket-triage` skill.

Applied labels: `enhancement`, `documentation`.

Retrospective six-stage challenge:
- Premise: passed. #11605 and the 2026-05-18 operator/MX framing preserve this as a real skill-substrate friction lane.
- Prescription: passed for label triage. Codify-deferral is distinct from #11884: #11884 covers the `Bias -> Rule -> Rationale -> Trigger` lesson-promotion atom, while this ticket covers the before-substrate timing / recurrence / consolidation discipline.
- Substrate: passed. ADR 0008 / skill-authoring workflow is the likely owning substrate; no AGENTS.md expansion should be assumed.
- Consumer: passed. Primary consumers are agent maintainers and future skill authors.
- Service boundary: passed. This is Agent OS documentation / skill-authoring substrate, not runtime Memory Core or framework Body behavior.
- Decision Record impact: likely `amends ADR 0008` or a compact companion, aligned with ADR 0007.

Assignment disposition: leaving unassigned. This is now label-triaged, but not automatically intake-ready. Before implementation, the pickup agent should run `ticket-intake` and verify whether the body needs narrowing / Contract Ledger coverage for the exact ADR or workflow surface being changed.

### @neo-gpt - 2026-05-25T03:11:58Z

## Ticket-intake blocker: needs contract + narrowing before implementation

Verdict: `needs-narrowing` + `needs-contract-alignment`; do not claim or branch yet.

Evidence checked:
- Live #11604 body and comments.
- Parent #11605 prior GPT epic review: https://github.com/neomjs/neo/issues/11605#issuecomment-4527912627
- Current ADR 0008 / `/create-skill` substrate already contains the #11884 lesson-promotion atom (`Bias`, `Rule`, `Rationale`, `Trigger`) and Lesson Promotion Path routing.
- Exact repo search found no current `codify-deferral` / accumulation-period / recurrence-threshold substrate beyond this ticket, so the premise is not already resolved.
- KB ticket query was attempted and failed service-side with `Error finding id`; Memory Core surfaced related review-substrate compression context, not a duplicate.

Blockers:
1. Contract Ledger is required before implementation. This ticket proposes modifying agent-consumed governance / skill-authoring / ADR surfaces. Please add a Contract Ledger for at least:
   - ADR 0008 or companion decision surface
   - `/create-skill` Lesson Promotion Path, if touched
   - any lint / manifest / CI guardrail surface, if proposed
   - dry-run output surface for first-cycle consolidation candidates
   - fallback semantics when K/N/cadence are not yet empirically defensible
2. Scope still needs narrowing. `K weeks`, `N recurrences`, cadence, and detector signature are placeholders. The next author should either define the exact first slice or split this into bounded children.
3. Existing-enforcement sufficiency still needs an explicit audit. The body should explain why ADR 0007, ADR 0008 §2.7, the `/create-skill` Lesson Promotion Path, and `lint-skill-manifest` are insufficient before adding another rule.

Age state: created 2026-05-18, updated 2026-05-25; pre-stale by `.github/workflows/close-inactive-issues.yml` (90 days stale / 14 days close); no `stale` or `no auto close` label observed.

ADR successor-risk: `adr-amendment-required` before implementation if the chosen slice amends ADR 0008; otherwise name the compact companion decision path explicitly.

Implementation remains halted until the ticket is narrowed and the Contract Ledger exists.

- 2026-05-25T03:12:12Z @neo-gpt added the `agent-task:blocked` label
- 2026-05-25T03:33:45Z @neo-gpt cross-referenced by #11602
- 2026-05-26T06:34:39Z @neo-gpt removed the `agent-task:blocked` label
- 2026-05-26T06:34:52Z @neo-gpt added the `needs-re-triage` label
### @neo-gpt - 2026-05-26T06:35:16Z

## Board routing update - needs re-triage against current substrate

Live watchdog intake rechecked #11604 after #11605 was removed from Project 12 and this child became the top unassigned board candidate.

Verdict: intent remains valid as substrate-governance concern, but #11604 is not ready v13 implementation work as written.

Evidence:
- The previous intake already halted implementation on `needs-narrowing` + `needs-contract-alignment`.
- Current substrate now covers much of the original prescription: AGENTS.md has Substrate Accretion Defense and Rule Friction Capture; ADR 0008 §2.6/§2.7 codifies the slot-rule discriminator and Lesson Promotion Atom; `/create-skill` routes Lesson Promotion through compact decision atoms and smallest-surface updates; `skills.manifest.json` / `lint-skill-manifest.mjs` enforce router and payload budgets.
- The remaining #11604 placeholders (`K weeks`, `N recurrences`, cadence, detector signature) are not empirically specified and would be negative-ROI to implement directly as another governance rule without a fresh sufficiency/contract pass.
- The issue is a discussion/architecture substrate item under parent #11605, so preserving it for re-triage is better than closing the governance concern outright.

Action taken:
- Removed the legacy `agent-task:blocked` label.
- Added `needs-re-triage`.
- Removed #11604 from Project 12 Todo so the current-release board does not present it as claimable ready work.

Re-entry condition: before any implementation, update the ticket with a current Contract Ledger and an existing-enforcement sufficiency audit that explains what is still missing after ADR 0008, `/create-skill`, AGENTS.md substrate-accretion guidance, and skill-manifest lint enforcement. If the only remaining proposal is fixed K/N/cadence policy without that audit, retire it rather than adding more loaded governance.

### @neo-gpt - 2026-06-03T07:36:34Z

**Input from GPT-5 (Codex Desktop):**

> ● ## Re-triage closeout — superseded as written
> 
> Live V-B-A before closing:
> 
> - #11604 is still open, unassigned, off Project 12, and already marked `needs-re-triage`.
> - Current `AGENTS.md` now carries Substrate Accretion Defense, runtime rule disposition (`keep` / `compress-to-trigger` / `move` / `rewrite` / `retire`), and Rule Friction Capture.
> - ADR 0008 now carries the Slot-Rule Discriminator plus the Lesson Promotion Atom: `Bias`, `Rule`, `Rationale`, `Trigger`.
> - `/create-skill` now routes new lessons through the same atom-vs-atlas decision instead of blind runtime-payload append.
> - `ai/scripts/lint/lint-skill-manifest.mjs` now enforces payload budgets and rare-trigger extraction to sub-rule atlas files.
> 
> Disposition: closing #11604 as `not planned` / superseded as written.
> 
> The original concern was real, but its durable behavior is now represented by the current substrate. The remaining proposal in this ticket is the placeholder policy layer (`K weeks`, `N recurrences`, cadence, detector signature). Adding fixed thresholds now would be another governance gate without fresh empirical threshold evidence, which is the failure mode this ticket was meant to prevent.
> 
> Reopen or create a narrow successor only if a fresh measured recurrence shows the current AGENTS + ADR 0008 + `/create-skill` + manifest-lint substrate is insufficient, and the successor includes a Contract Ledger for the exact rule or lint surface being changed.
> 
> Parent impact: #11605 can now be re-evaluated with #11604 no longer blocking AC8 by open-child state.

- 2026-06-03T07:36:41Z @neo-gpt closed this issue

