---
id: 10511
title: 'docs(agents): compact AGENTS.md to restore turn-based memory focus, and streamline PR skills'
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees: []
createdAt: '2026-04-29T21:51:53Z'
updatedAt: '2026-05-15T12:44:52Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10511'
author: neo-gemini-pro
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-29T22:42:12Z'
---
# docs(agents): compact AGENTS.md to restore turn-based memory focus, and streamline PR skills

## 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.

## Timeline

- 2026-04-29T21:51:53Z @neo-gemini-pro added the `documentation` label
- 2026-04-29T21:51:54Z @neo-gemini-pro added the `enhancement` label
- 2026-04-29T21:51:54Z @neo-gemini-pro added the `ai` label
- 2026-04-29T21:53:17Z @neo-gemini-pro changed title from **docs(agents): compact AGENTS.md and PR templates to prevent focus window bloat** to **docs(agents): compact AGENTS.md to restore turn-based memory focus, and streamline PR skills**
- 2026-04-29T22:02:07Z @neo-gemini-pro cross-referenced by PR #10512
- 2026-04-29T22:10:26Z @neo-gemini-pro referenced in commit `be15e6c` - "docs(agents): compact AGENTS.md by removing empirical forensic bloat (#10511)"
- 2026-04-29T22:13:14Z @neo-gemini-pro referenced in commit `d64b948` - "docs(agents): compact AGENTS.md by removing empirical forensic bloat (#10511)"
- 2026-04-29T22:42:12Z @tobiu referenced in commit `cab334b` - "docs(agents): compact AGENTS.md by removing empirical forensic bloat (#10511) (#10512)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-04-29T22:42:12Z @tobiu closed this issue
- 2026-04-29T22:51:12Z @neo-gpt cross-referenced by #10513
- 2026-04-30T21:18:59Z @neo-opus-ada cross-referenced by #10537
- 2026-05-04T21:32:17Z @neo-opus-ada cross-referenced by PR #10720
- 2026-05-05T09:04:09Z @neo-opus-ada cross-referenced by #10733
- 2026-05-05T09:05:27Z @neo-opus-ada cross-referenced by #10735
- 2026-05-05T09:31:01Z @neo-opus-ada cross-referenced by PR #10739
- 2026-05-05T15:12:03Z @neo-gpt cross-referenced by #10736

