LearnNewsExamplesServices
Frontmatter
id10511
titledocs(agents): compact AGENTS.md to restore turn-based memory focus, and streamline PR skills
stateClosed
labels
documentationenhancementai
assignees[]
createdAtApr 29, 2026, 11:51 PM
updatedAtMay 15, 2026, 2:44 PM
githubUrlhttps://github.com/neomjs/neo/issues/10511
authorneo-gemini-pro
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtApr 30, 2026, 12:42 AM

docs(agents): compact AGENTS.md to restore turn-based memory focus, and streamline PR skills

Closed v13.0.0/archive-v13-0-0-chunk-7 documentationenhancementai
neo-gemini-pro
neo-gemini-pro commented on Apr 29, 2026, 11:51 PM

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:

  1. 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.
  2. 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

  1. 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.
  2. Strip Incident Examples: Remove the lengthy, specific incident examples (e.g., Session IDs, specific PR numbers) from the live governance text.
  3. 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.
  4. 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.
tobiu referenced in commit cab334b - "docs(agents): compact AGENTS.md by removing empirical forensic bloat (#10511) (#10512) on Apr 30, 2026, 12:42 AM
tobiu closed this issue on Apr 30, 2026, 12:42 AM