Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#283 2 commenti 2 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@cplegendre ci sta già lavorando.

Dal 13/10/2026.

  • #286 di @cplegendre — aperta

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

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

Lingua principale
Go
Stelle
6
Fork
8
Merge medio
1g 2h
PR unite (30g)
96

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di redhat-et/ProtoBot

Tutte le issue di redhat-et/ProtoBot

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.