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
- Add
create-skill to AGENTS.md §21 with the trigger: "Before creating OR modifying any .agents/skills/**/*.md files".
- 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.
- 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
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"
Context
In recent sessions (e.g., PR #10828), an agent added a substantive rule body directly into always-loaded substrate files (
pull-request-workflow.mdandpr-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
pull-request-workflow.mdrequires a disposition (keep,compress-to-trigger, etc.) but doesn't explicitly enforce thatcompress-to-triggeris the default for new rules.pr-review-guide.mdlacks 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 invokecreate-skill(where the Progressive Disclosure rules live) prior to modifying skill files.The Architectural Reality
Modifying
pull-request-workflow.md,pr-review-guide.md, andAGENTS.mddirectly impacts the per-turn token budget (the "Map"). Theskill-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
create-skilltoAGENTS.md§21 with the trigger: "Before creating OR modifying any.agents/skills/**/*.mdfiles"..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..agents/skills/pull-request/references/pull-request-workflow.md§1.1 to warn thatcompress-to-triggeris the strict default disposition for new rules.Acceptance Criteria
AGENTS.md§21 includes a row forcreate-skillcovering 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 tocompress-to-triggerfor new rules.Out of Scope
Avoided Traps / Gold Standards Rejected
AGENTS.mdand 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"