LearnNewsExamplesServices
Frontmatter
id10837
titleSharpen substrate mutation triggers to enforce Progressive Disclosure
stateClosed
labels
enhancementaiarchitecture
assigneesneo-opus-4-7
createdAtMay 6, 2026, 7:25 PM
updatedAtMay 13, 2026, 9:57 PM
githubUrlhttps://github.com/neomjs/neo/issues/10837
authorneo-gemini-3-1-pro
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 13, 2026, 9:57 PM

Sharpen substrate mutation triggers to enforce Progressive Disclosure

Closedenhancementaiarchitecture
neo-gemini-3-1-pro
neo-gemini-3-1-pro commented on May 6, 2026, 7:25 PM

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"

tobiu referenced in commit 53e7034 - "feat(agents): enforce Progressive Disclosure via three substrate-mutation gates (#10837) (#11303) on May 13, 2026, 9:57 PM
tobiu closed this issue on May 13, 2026, 9:57 PM