---
id: 10837
title: Sharpen substrate mutation triggers to enforce Progressive Disclosure
state: CLOSED
labels:
  - enhancement
  - ai
  - architecture
assignees:
  - neo-opus-ada
createdAt: '2026-05-06T17:25:33Z'
updatedAt: '2026-05-13T19:57:54Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10837'
author: neo-gemini-pro
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-13T19:57:54Z'
---
# Sharpen substrate mutation triggers to enforce Progressive Disclosure

### Context
In recent sessions (e.g., PR #10828), an agent added a substantive rule body directly into always-loaded substrate files (`pull-request-workflow.md` and `pr-review-guide.md`). The PR passed review because our current triggers are not sharp enough to explicitly catch violations of Progressive Disclosure (Map vs World Atlas architecture).

### The Problem
- The `pull-request-workflow.md` requires a disposition (`keep`, `compress-to-trigger`, etc.) but doesn't explicitly enforce that `compress-to-trigger` is the default for new rules. 
- The `pr-review-guide.md` lacks an Anti-Pattern entry for "bloated skill rules added to always-loaded substrate", allowing reviewers to miss the regression. 
- `AGENTS.md` §21 lacks a trigger to invoke `create-skill` (where the Progressive Disclosure rules live) prior to modifying skill files.

### The Architectural Reality
Modifying `pull-request-workflow.md`, `pr-review-guide.md`, and `AGENTS.md` directly impacts the per-turn token budget (the "Map"). The `skill-authoring-guide.md` (the "World Atlas") is only loaded conditionally, but currently, no strict upstream gate forces the agent to read it when modifying existing skills.

### The Fix
1. Add `create-skill` to `AGENTS.md` §21 with the trigger: "Before creating OR modifying any `.agents/skills/**/*.md` files".
2. Add an explicit Anti-Pattern to `.agents/skills/pr-review/references/pr-review-guide.md` §7.6 to reject PRs that add substantive rule bodies to always-loaded skill files instead of conditionally loaded references.
3. Sharpen `.agents/skills/pull-request/references/pull-request-workflow.md` §1.1 to warn that `compress-to-trigger` is the strict default disposition for new rules.

### Acceptance Criteria
- [ ] `AGENTS.md` §21 includes a row for `create-skill` covering both creation and modification.
- [ ] `pr-review-guide.md` §7.6 contains the new Progressive Disclosure violation anti-pattern.
- [ ] `pull-request-workflow.md` §1.1 explicitly defaults to `compress-to-trigger` for new rules.

### Out of Scope
- Refactoring existing skill references beyond adding these three gates.

### Avoided Traps / Gold Standards Rejected
- **Simply reminding the agent via A2A:** Rejected because memory is volatile; structural gates in `AGENTS.md` and review guides are permanent and mechanically enforceable.

Origin Session ID: a82084a1-4ce1-4a50-b78d-68b3e60a473f
Retrieval Hint: "Progressive Disclosure Map vs World Atlas trigger for modifying skill files"

## Timeline

- 2026-05-06T17:25:34Z @neo-gemini-pro added the `enhancement` label
- 2026-05-06T17:25:35Z @neo-gemini-pro added the `ai` label
- 2026-05-06T17:25:35Z @neo-gemini-pro added the `architecture` label
- 2026-05-10T01:34:53Z @neo-gpt cross-referenced by #11090
- 2026-05-10T02:55:42Z @neo-opus-ada cross-referenced by PR #11097
- 2026-05-12T09:17:04Z @neo-gemini-pro cross-referenced by #11254
- 2026-05-12T09:18:58Z @neo-opus-ada cross-referenced by #11256
- 2026-05-12T09:51:36Z @neo-gpt cross-referenced by PR #11255
- 2026-05-13T11:48:58Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-13T11:52:18Z @neo-opus-ada cross-referenced by PR #11303
- 2026-05-13T19:57:54Z @tobiu referenced in commit `53e7034` - "feat(agents): enforce Progressive Disclosure via three substrate-mutation gates (#10837) (#11303)

Adds three mechanical gates against bloated skill rules in always-loaded substrate:

- AGENTS.md §21: new `create-skill` row (trigger: before creating OR modifying
  any `.agents/skills/**/*.md` files). Sits alongside `turn-memory-pre-flight`
  (load-runtime-effect dimension); `create-skill` covers skill-shape dimension
  (Map vs World Atlas, frontmatter, structure).
- pull-request-workflow.md §1.1: adds explicit default-disposition sentence.
  `compress-to-trigger` is now the strict default for new rules; `keep` slot
  requires per-turn-frequency + irreversibility justification (§0 / §22 class).
- pr-review-guide.md §7.7: new anti-pattern row rejecting substantive rule
  bodies added directly to always-loaded skill substrate (Progressive
  Disclosure violation; proactive companion `/create-skill`).

Substrate-accretion math: ~+1.7KB total (4 net new lines), of which ~330B lands
in always-loaded AGENTS.md and the rest in skill-conditional `references/`
payloads. Net-expansion now is preventive against linear bloat across future
substrate iterations — each gate mechanically rejects rule-body-in-Map regressions.

Note on AC interpretation: ticket AC #2 specifies pr-review-guide.md §7.6 but
§7.6 is the CI/Security Checks Audit pointer (mechanical, one sentence). The
canonical anti-pattern table is §7.7. Placed the new row in §7.7 to match the
existing structure and adjacent anti-patterns.

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-13T19:57:54Z @tobiu closed this issue

