Context
AGENTS.md is our turn-based memory — it is loaded into the focus window on every single turn for all three agents.
Conversely, the pr-review skill files are NOT turn-based memory, but they are invoked frequently during the Definition of Done phase.
Over the past 20+ PRs, whenever a workflow failure occurred, agents have appended detailed empirical examples, incident numbers, and lengthy rationale to these documents to anchor the new protocols.
The Problem
The progressive accumulation of these empirical examples has caused two distinct performance degradations:
- Turn-Based Bloat (
AGENTS.md): This file is now so large that it consumes a significant portion of the focus window with examples that are irrelevant to 99% of daily tasks. It dilutes agent focus continuously across all operations.
- Skill-Invocation Bloat (
pr-review): The PR review templates and guides have become excessively long, bloating the context window specifically during the PR review phase, increasing token consumption and reducing analytical sharpness.
The Fix
- Audit and Condense: Audit
AGENTS.md, .agents/skills/pr-review/assets/pr-review-template.md, and .agents/skills/pr-review/references/pr-review-guide.md.
- Strip Incident Examples: Remove the lengthy, specific incident examples (e.g., Session IDs, specific PR numbers) from the live governance text.
- Migrate to Knowledge Base: If the incident history is valuable for forensics, migrate it to static Knowledge Base artifacts or dedicated reference markdown files outside of the immediate agent prompt loop.
- Enforce Brevity: Refine the core mandates to state the rule clearly and concisely without narrative baggage.
Architectural Return on Investment (ROI)
- Focus Window Preservation: Dramatically reduces the baseline token cost per turn by stripping
AGENTS.md.
- Targeted Efficiency: Lowers the token spike and cognitive load when the
pr-review skill is triggered.
- Maintainability: Leaner governance documents are easier to update and scale as the framework evolves.
Context
AGENTS.mdis our turn-based memory — it is loaded into the focus window on every single turn for all three agents. Conversely, thepr-reviewskill files are NOT turn-based memory, but they are invoked frequently during the Definition of Done phase.Over the past 20+ PRs, whenever a workflow failure occurred, agents have appended detailed empirical examples, incident numbers, and lengthy rationale to these documents to anchor the new protocols.
The Problem
The progressive accumulation of these empirical examples has caused two distinct performance degradations:
AGENTS.md): This file is now so large that it consumes a significant portion of the focus window with examples that are irrelevant to 99% of daily tasks. It dilutes agent focus continuously across all operations.pr-review): The PR review templates and guides have become excessively long, bloating the context window specifically during the PR review phase, increasing token consumption and reducing analytical sharpness.The Fix
AGENTS.md,.agents/skills/pr-review/assets/pr-review-template.md, and.agents/skills/pr-review/references/pr-review-guide.md.Architectural Return on Investment (ROI)
AGENTS.md.pr-reviewskill is triggered.