Repository navigation
docs(#178): consolidate sibling-consistency rules in AGENTS.md - #181
Conversation
Replace the three near-duplicate read-siblings / reuse-terminology / review-check instruction sets with one canonical section that applies to numbered rules in AGENTS.md, specification documents under docs/, skill files under .agents/skills/, and any future surface added later. Surface-specific guidance is nested as examples under that section: AGENTS.md siblings are the other rules in the same list; docs/ siblings are every other governed Markdown document under docs/; skill-file siblings keep the backtick-quoting and structural-vs-behavioral distinction from the former skill-file rules. Specification-document coverage, topology, and staleness rules, and the skill-to-spec alignment rules, are unchanged aside from renumbering. Note: pre-commit could not fetch remote hook repositories (HTTP 403). Equivalent hooks were run via python scripts/lint.py --files AGENTS.md and passed. Closes #178
|
Important Review skippedBot user detected. To trigger a single review, invoke the ⚙️ Run configurationConfiguration used: Repository: redhat-et/ProtoBot/.coderabbit.yaml Review profile: CHILL Plan: Advanced Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Comment |
|
🤖 Review · Commit: |
|
Risk Assessment: moderate (2/5) DetailsTier 1 signals unchanged from the prior assessment (1 file, small blast radius, 1 protected path, no dependency/CI touch, bot author); Tier 2 remains elevated due to AGENTS.md high churn and multi-author history; Tier 3 stays low since the PR cleanly satisfies a well-scoped issue. Prior composite score of 2 (moderate) preserved per re-review anchoring. Previous runRisk Assessment: moderate (2/5) DetailsA bot-authored, single-file docs consolidation (90 lines, no CI/dependency/security touch) keeps Tier 1 low, but AGENTS.md is a high-churn, multi-author file with frequent fix commits and strong coupling to unmodified architecture docs, elevating Tier 2; Tier 3 is low since the PR precisely satisfies a fresh, unambiguous, unlabeled issue, yielding a composite of ~1.7 rounded to 2 (moderate). |
ReviewFindingsMedium
Prior review resolution: Both low-severity findings from the prior review round (the undefined two-level "governed scope" / "list or governed collection" vocabulary, and the intro's grammatical parallelism at the old A candidate new finding was investigated and rejected on evidence: the pre-existing "governed hierarchy member" / "governed Markdown document" phrasing ( Labels: AGENTS.md is a protected governance path modified in this PR; human approval is required before merge and this is not yet reflected in the PR labels. Previous runReviewFindingsMedium
Low
Prior review resolution: Both prior findings (the "surface" terminology overload at the old Next steps:
Previous run (2)ReviewFindingsMedium
Low
Labels: Docs-only governance change (AGENTS.md) with no code/CI/security surface touched; the documentation label is not currently applied. Next steps:
|
|
🤖 Finished Review · ✅ Success · Started 5:40 PM UTC · Completed 5:59 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $3.88 |
Address review findings regarding sibling entry scoping, terminology, and normative skill-file obligations in AGENTS.md: - Replace overloaded bare 'surface' with 'governed scope' and 'list or governed collection'. - Clarify sibling scope in rules 1-3 to explicitly bind to the same list or governed collection, resolving tension with per-list rules. - Revise rule 3 review-check clause to reference specification-hierarchy keyword checks so it reads accurately across all governed scopes. - Move normative skill formatting and structural-vs-behavioral rules back into a numbered 'agents must follow' list under Agent skills, leaving the examples list purely definitional. - Acknowledge protected-path notification; AGENTS.md modification is the PR scope and awaits required human approval before merge. Note: pre-commit could not fetch remote hook repositories (HTTP 403). Equivalent hooks were run via python scripts/lint.py and passed. Addresses #181
🔧 Fix agent — iteration 1 (bot-triggered)Addressed review findings by replacing overloaded bare 'surface' with 'governed scope' / 'list or governed collection', clarifying sibling scope to list-level in AGENTS.md, generalizing rule 3's review check clause, and restoring skill-file formatting and structural-vs-behavioral rules as an enforceable numbered list under Agent skills. Acknowledged the protected-path notification for AGENTS.md. Fixed (3):
Disagreed (1):
Tests: passed Decision points
Next steps:
|
|
🤖 Finished Fix · ✅ Success · Started 6:00 PM UTC · Completed 6:11 PM UTC Commit: Runtime: pi · Model: google-vertex/gemini-3.8-flash → gemini-3.8-flash · Effort: high · Cost: $0.65 |
|
🤖 Finished Review · ✅ Success · Started 6:12 PM UTC · Completed 6:25 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $2.33 |
Address review feedback on PR #181: - Define the two-level vocabulary in "Rules for creating or modifying sibling entries": governed scope defines the domain of applicability, while list or governed collection defines the sibling set within that domain. - Fix intro grammatical parallelism to reference an entry in any future governed scope. - Note disagreement on protected-path notification: AGENTS.md modification is within the intended scope of PR #181 and requires human approval before merge. Note: pre-commit could not fetch remote hook repositories (HTTP 403). Equivalent hooks were run via python scripts/lint.py and passed. Addresses #181
🔧 Fix agent — iteration 2 (bot-triggered)Addressed terminology coherence finding by explicitly defining governed scope and list or governed collection, and fixing grammatical parallelism in the intro sentence. Acknowledged protected-path finding for AGENTS.md awaiting human approval. Fixed (1):
Disagreed (1):
Tests: passed Decision points
Next steps:
|
|
🤖 Finished Fix · ✅ Success · Started 6:27 PM UTC · Completed 6:37 PM UTC Commit: Runtime: pi · Model: google-vertex/gemini-3.8-flash → gemini-3.8-flash · Effort: high · Cost: $0.33 |
Superseded by updated review
|
🤖 Finished Review · ✅ Success · Started 6:38 PM UTC · Completed 6:52 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $2.76 |
|
PR #181 (redhat-et/ProtoBot) consolidated three duplicated "sibling-consistency" rule blocks in AGENTS.md (originally added piecemeal by #58, #86, #169) into one canonical section, closing #178 (itself auto-filed by a prior retro off PR #177). Pipeline: triage → one-shot code agent → 3 review rounds + 2 fix iterations → human approval → merge, all within ~1h36m (17:37–19:14 UTC on 2026-09-23). Review quality was strong on substance: round 1 caught a genuine self-contradiction (the new rule bound sibling scope to "the same surface" while its own worked example scoped siblings per-list, not per-file), a normative-rule demotion (skill-file MUST rules had been moved into a non-normative "Examples" bullet, weakening enforceability), and an overloaded term ("surface" collided with the architecture docs' existing API/CLI/control-surface meaning). All three were real defects, correctly identified and fixed. Round 2 then caught a defect introduced by the round-1 fix itself: the fix replaced "surface" with two new related terms ("governed scope" and "list or governed collection") but never stated their relationship — an undefined co-reference, fixed in iteration 2 and confirmed clean in round 3. Notably, this PR's own subject matter is the very sibling-terminology-consistency rule that the fix agent momentarily violated while implementing it — a fitting self-referential near-miss, caught correctly by review. The only human touchpoint was a single content-free Separately, fullsend-ai/agents#1448 (open) already tracks the broader meta-pattern visible in the #58→#86→#169→#178 lineage (repeated narrow point-fixes instead of earlier generalization); PR #181 is the generalization that resulted, so no new proposal is needed there either. One new proposal below addresses the round-1→round-2 rework: the fix agent should self-check newly introduced terminology for definedness before resubmitting, to avoid a preventable second review round. Proposals filed |
|
🤖 Finished Retro · ✅ Success · Started 7:15 PM UTC · Completed 7:24 PM UTC Commit: Runtime: claude · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $1.64 |
Summary
Consolidate AGENTS.md's three duplicated sibling-consistency instruction sets into one canonical section.
Issues #58, #86, and #169 each added the same read-siblings / reuse-terminology / review-check pattern for a different surface (
docs/,.agents/skills/, and AGENTS.md's own numbered lists). A later refinement to that pattern would have to be copied in three places.The new section, "Rules for creating or modifying sibling entries", states the pattern once and applies it to those three surfaces plus any future surface added later. Surface-specific guidance is nested as examples (same-list numbered rules; governed Markdown documents under
docs/; skill-file formatting and the structural-vs-behavioral distinction).Specification-document coverage, topology, and staleness rules, and the skill-to-spec alignment rules, are unchanged aside from renumbering after the duplicated "read siblings first" items were removed.
CLAUDE.mdis a symlink toAGENTS.mdand inherits the change.AGENTS.mdis listed inREVIEW_PROTECTED_PATHS; extra review scrutiny is expected.Testing
python scripts/lint.py --files AGENTS.md(offline pre-commit equivalent;pre-commititself could not fetch hook repos in this sandbox — HTTP 403)AGENTS.mdand of staged contentgrepfor "Read all sibling" and "Reuse established terminology" each returns a single matchCloses #178
Post-script verification
agent/178-sibling-consistency-principle)2b1875b7556ed09e84803c0af786728716b925a9..HEAD)