Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Scope AGENTS.md specification-document sibling reading rule to avoid whole-repo doc reading on localized edits

Open
  • Is something wrong?
#283 2 comments 2 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@cplegendre is already working on this.

Since Oct 13, 2026.

  • #286 by @cplegendre — open

Assessment

This issue has not been assessed yet.

Description

documentation ready-for-triage ready-to-code

What happened

On Issue #255 (run 37953012856), the code agent was tasked with adding a verification check in ears-manager check and updating related documentation.

In AGENTS.md, the "Rules for creating or modifying sibling entries" defines sibling entries for "Specification documents under docs/" as "every other governed Markdown document under docs/", and commands: "Read all sibling entries first. Before drafting or revising an entry, read every other entry in the same list or governed collection."

With 20 Markdown files currently under docs/, the agent spent the first 31 turns (27 minutes, 45% of its entire 60-minute budget) exhaustively reading nearly all 20 specification documents before writing any code.

This accumulated over 200,000 tokens in the conversation context. With xai/grok-4.6 deep reasoning, inference latency reached 40–120+ seconds per turn. Over the 78-turn session, 96.0% of the wall-clock time (3,457s out of 3,600s) was spent waiting for model inference, while tool execution took only 142s total. The agent completed the Go implementation, unit tests, linters (scripts/lint.py), and test suites by Turn 75 (minute 58), but was force-terminated by the 3,600s budget timeout during Step 10 seconds before running git commit, resulting in 100% of the work being discarded.

What could go better

While reading sibling entries is effective for discrete, compact lists (such as numbered rules in AGENTS.md or tools in a directory), defining the sibling set of any document under docs/ as "every other governed Markdown document under docs/" forces agents to read the entire repository documentation upfront.

This violates the core scaffolding principles of minimal hand-written context and progressive disclosure (Principle 3 and 4 in agent-scaffolding). As docs/ grew from a few initial files to 20 documents, this rule turned into an escalating token and latency trap.

Cross-document consistency is already governed by "Rules for creating or modifying specification documents", which specifically directs agents to check components.md and overview.md for enumerated interfaces and constraints.

Confidence: High. The transcript shows 27 consecutive minutes spent reading 20 files in docs/ before any implementation began, directly cited by the agent as complying with Rule 1 of sibling entries.

Proposed change

In AGENTS.md under "Rules for creating or modifying sibling entries":

  1. Refine the sibling scope for specification documents under docs/ to be scoped to the immediate directory/collection (e.g., other documents in docs/architecture/agent-harness/, or ADRs in docs/decisions/), rather than the entire docs/ tree.
  2. Clarify that cross-cutting architecture and component coverage is handled through the directed checks in "Rules for creating or modifying specification documents" (checking docs/architecture/components.md and docs/architecture/overview.md), rather than requiring an unconditional upfront read of all Markdown documents across the entire repository.

Validation criteria

On the next 5 code or fix agent runs on redhat-et/ProtoBot that modify a specification document under docs/, the exploration phase before implementation takes fewer than 10 turns and under 50,000 input tokens for document reading, avoiding timeout failures caused by context-inflated inference latency.

Generated by retro agent from https://github.com/redhat-et/ProtoBot/issues/255

Dominant language
Go
Stars
6
Forks
8
Avg merge
1d 3h
Merged PRs (30d)
93

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from redhat-et/ProtoBot

All issues in redhat-et/ProtoBot

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.