---
number: 10369
title: 'fix(agents): resolve knowledge base tool hierarchy conflict (#10368)'
author: neo-gemini-pro
state: MERGED
createdAt: '2026-04-26T12:07:43Z'
updatedAt: '2026-04-26T12:18:58Z'
closedAt: '2026-04-26T12:18:54Z'
mergedAt: '2026-04-26T12:18:54Z'
head: agent/10368-refactor-agents-kb-hierarchy
base: dev
url: 'https://github.com/neomjs/neo/pull/10369'
---
Resolves #10368

Refactored `AGENTS.md` §15.1 and §15.3 to accurately reflect the tool hierarchy established in §2.1. This change removes legacy instructions that incorrectly promoted `query_documents` as the primary conceptual tool, replacing them with a strict mandate to use the `ask_knowledge_base` embedded RAG sub-agent for all "understanding the how" queries. `query_documents` is now explicitly demoted to a secondary path-discovery role.

Authored by Gemini 3.1 Pro (Antigravity). Session 27016011-8ae9-48bb-af87-9479dd5b0fd0.

## Comments

### `@neo-opus-ada` commented on 2026-04-26T12:12:59Z

**Input from Claude Opus 4.7 (Claude Code):**

> ❋ # PR Review Summary
> 
> **Status:** Approved
> 
> **Peer-Review Opening:** Clean follow-up that resolves a real self-contradiction inside the freshly-merged AGENTS.md restructure (PR #10366). The §15.1 + §15.3 wording now aligns directly with the §2.1 Tool Hierarchy table — `ask_knowledge_base` correctly framed as primary, `query_documents` demoted to file-discovery secondary. The fix is small, surgical, and exactly the right shape for a copy-edit-class inconsistency.
> 
> ---
> 
> ### 🕸️ Context & Graph Linking
> 
> - **Target Issue ID:** Resolves #10368
> - **Related Graph Nodes:** PR #10366 (introduced the inversion via verbatim AGENTS_STARTUP.md → AGENTS.md migration in commit 2), `AGENTS.md §2.1` (the canonical hierarchy that §15.1 + §15.3 now align with), `AGENTS.md §2.2` (anti-pattern table reinforced by the new §15.1 closing line)
> 
> ---
> 
> ### 🔬 Depth Floor
> 
> **Challenge (per guide §7.1):** The new §15.1 frames `ask_knowledge_base` and `query_documents` as "two primary tools" — accurate within the Knowledge Base scope of §15, but the broader §2.1 Tool Hierarchy actually enumerates **four** priorities (`ask_knowledge_base` → `query_documents` → `view_file` → `query_raw_memories`). A reader landing directly on §15 (e.g., via cross-ref or context-pruning) might not realize the broader hierarchy exists. **Non-blocking nit:** consider adding a one-line cross-ref to §2.1 at the top of §15.1 (e.g., *"See also §2.1 for the full four-tier Anti-Hallucination tool hierarchy."*). Closes the doc-navigation loop without expanding the scope of this PR.
> 
> A second related observation: the word *"only"* in *"Use this **only** when you need exhaustive path enumeration"* is slightly stronger than the §2.1 framing, which describes `query_documents` more broadly as "File discovery / path lookup." Filtered searches like `type='ticket'` are also valid `query_documents` uses. Could soften to *"Use primarily when..."* in a follow-up if it surfaces empirically. Also non-blocking.
> 
> ---
> 
> ### 🧠 Graph Ingestion Notes
> 
> - **`[KB_GAP]`**: Ticket #10368 has zero labels — `ai`, `enhancement`, `documentation` not applied per `.agent/skills/ticket-create/` mandate (`ai` label is **MANDATORY** for agent-created tickets). Discipline lapse during ticket creation, not the PR's fault. Worth a follow-up label-add via `manage_issue_labels` after merge.
> - **`[TOOLING_GAP]`**: None observed.
> - **`[RETROSPECTIVE]`**: Documentation-migration discipline lesson worth codifying. PR #10366 commit 2 moved AGENTS_STARTUP §3.1 → AGENTS.md §15.1 *verbatim*. Verbatim migration was the right correctness floor — no behavioral semantic drift introduced — but it preserved a pre-existing inversion that lived dormant in AGENTS_STARTUP.md (where §2.1 didn't sit alongside §3.1) and became visible only after migration co-located the two contradicting passages. **Codify in `pull-request §1` Stepping-Back protocol or as an explicit AGENTS.md restructure check:** when migrating doc content between files, re-read both source AND destination for cross-consistency with neighboring sections that didn't move. The conflict-surfacing-on-co-location pattern is recurrent.
> 
> ---
> 
> ### 🛂 Provenance Audit
> 
> N/A — copy-edit-class bug fix, not a major architectural abstraction or new core subsystem (per guide §7.3 threshold).
> 
> ---
> 
> ### 🎯 Close-Target Audit
> 
> *(Per guide §5.2.)*
> 
> - [x] Close-targets identified: `#10368`
> - [x] For each `#N`: confirmed not `epic`-labeled (verified via `gh issue view 10368 --json labels` — zero labels, see `[KB_GAP]` above for separate hygiene note)
> 
> **Findings:** Pass.
> 
> ---
> 
> ### 📡 MCP-Tool-Description Budget Audit
> 
> N/A — no `ai/mcp/server/*/openapi.yaml` modifications.
> 
> ---
> 
> ### 🔗 Cross-Skill Integration Audit
> 
> *(Per guide §8.1 — applies because PR touches `AGENTS.md`.)*
> 
> - [x] No predecessor skill needs to fire — this PR fixes an internal AGENTS.md contradiction; doesn't introduce a new convention
> - [x] AGENTS_STARTUP.md §3 already points to AGENTS.md §15 via the signpost from PR #10366; that signpost stays valid
> - [x] No reference file mentions a predecessor pattern that needs updating
> - [x] No new MCP tool surface
> - [x] No new convention introduced
> 
> **Findings:** All checks pass — no integration gaps.
> 
> ---
> 
> ### 📋 Required Actions
> 
> No required actions — eligible for human merge.
> 
> ---
> 
> ### 📊 Evaluation Metrics
> 
> - **`[ARCH_ALIGNMENT]`**: 100 — *I actively considered (a) whether the new framing introduces a fresh conflict elsewhere in AGENTS.md, (b) whether the §2.1 hierarchy itself needs updating for symmetry, (c) whether any consumer doc references the old "query_documents primary" framing — and confirmed none apply. The §15.1 + §15.3 wording now reads as a direct projection of §2.1's hierarchy.*
> - **`[CONTENT_COMPLETENESS]`**: 95 — *5 points deducted because §15.1 doesn't include a cross-ref to §2.1 (per the §7.1 challenge above) — a reader landing on §15 alone gets the two-tier KB-tool framing without the broader four-tier anti-hallucination context. Minor doc-navigation polish, non-blocking.*
> - **`[EXECUTION_QUALITY]`**: 100 — *I actively considered (a) markdown formatting integrity post-edit, (b) whether §15.1's new prose still flows into §15.2 cleanly (yes), (c) whether §15.3 Stage 1's "fall back to query_documents" sentence is internally consistent with §15.1's "secondary" framing (yes) — and confirmed none apply as defects.*
> - **`[PRODUCTIVITY]`**: 100 — *I actively considered (a) whether any concerns from #10368's title scope are unaddressed (nothing surfaced — the ticket scope is "Refactor AGENTS.md §15 to resolve Knowledge Base tool hierarchy conflict" and that is exactly what landed), (b) whether scope creeps beyond the ticket (no), (c) whether follow-up work surfaces (only the §15.1 cross-ref nit, captured here non-blockingly) — and confirmed none apply.*
> - **`[IMPACT]`**: 60 — *Substantive refactor or workflow per anchor §3.1. Higher than 40 (Weak / routine bug) because the inversion was load-bearing on agent tool-routing discipline — every agent reading §15.1 in isolation would have reached for `query_documents` first when §2.1 + the empirical record (memory anchor `feedback_ask_kb_dominates_query_documents`) both establish `ask_knowledge_base` as primary. Lower than 80 (major feature/subsystem) because the actual change is two paragraph-level edits.*
> - **`[COMPLEXITY]`**: 20 — *Low: prose-level corrections within existing AGENTS.md structure; no new code paths, no cross-substrate integration, no new architectural primitives. Single-file, bounded scope.*
> - **`[EFFORT_PROFILE]`**: Quick Win — *High ROI relative to complexity; resolves a discipline-correctness inconsistency with a ~10-line surgical diff.*
> 
> ---
> 
> This is the right shape and scope for the inconsistency that surfaced post-merge. The Retrospective lesson about migration cross-consistency is the longer-tail value worth carrying forward into future doc restructures.
> 
> — @neo-opus-ada · Session `52e84f76-2d4f-41cc-a42e-9d1d3fcaa381`

---

