---
id: 10368
title: Refactor AGENTS.md §15 to resolve Knowledge Base tool hierarchy conflict
state: CLOSED
labels:
  - bug
  - documentation
  - ai
assignees:
  - neo-gemini-pro
createdAt: '2026-04-26T12:05:38Z'
updatedAt: '2026-04-26T12:18:55Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10368'
author: neo-gemini-pro
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-26T12:18:55Z'
---
# Refactor AGENTS.md §15 to resolve Knowledge Base tool hierarchy conflict

### Context
The swarm architecture documentation was recently consolidated, moving the startup workflow into `AGENTS.md`. A core mandate is the "Anti-Hallucination Policy", which dictates the usage of Knowledge Base tools.

### Problem
There is a split-brain conflict within `AGENTS.md` regarding the primary Knowledge Base tool. 
- §2.1 correctly establishes `ask_knowledge_base` as the primary Anti-Hallucination tool for conceptual understanding (acting as an embedded zero-cost RAG agent) and demotes `query_documents` to file discovery.
- However, §15.1 ("The Query Command") and §15.3 ("The Two-Stage Query Protocol") still contain legacy instructions that incorrectly promote `query_documents` as the "most important tool" and mandate its use for Stage 1 (understanding the technical "how").

This conflict creates cognitive friction for agents, as they receive contradictory instructions on how to acquire context, leading to inefficient `query_documents` -> `view_file` chains instead of utilizing the superior `ask_knowledge_base` synthesis.

### Architectural Reality
`ask_knowledge_base` is strictly superior for conceptual queries. It performs the same underlying vector search as `query_documents` but adds an LLM synthesis step, returning both the answer and the same top-5 ranked references. Using `query_documents` for conceptual understanding wastes context window and turns.

### Fix
Refactor `AGENTS.md` to establish a unified, non-contradictory tool hierarchy:
1. Rewrite §15.1 to reflect the dominance of `ask_knowledge_base` and align with §2.1.
2. Update §15.3 (Stage 1) to mandate `ask_knowledge_base` for "understanding the how", reserving `query_documents` for exhaustive path enumeration.
3. Ensure the documentation consistently promotes the Embedded RAG pattern over manual file reading for conceptual tasks.

### Acceptance Criteria
- [ ] §15.1 no longer claims `query_documents` is the "most important tool".
- [ ] §15.3 instructs the use of `ask_knowledge_base` for Stage 1 conceptual queries.
- [ ] The overall document is internally consistent with the hierarchy defined in §2.1.
- [ ] Any references to manual `query_documents` -> `view_file` chains for conceptual understanding are removed.

## Timeline

- 2026-04-26T12:07:44Z @neo-gemini-pro cross-referenced by PR #10369
- 2026-04-26T12:15:01Z @neo-gemini-pro assigned to @neo-gemini-pro
- 2026-04-26T12:15:17Z @neo-gemini-pro added the `ai` label
- 2026-04-26T12:15:17Z @neo-gemini-pro added the `bug` label
- 2026-04-26T12:15:17Z @neo-gemini-pro added the `documentation` label
- 2026-04-26T12:18:55Z @tobiu referenced in commit `00b57b9` - "fix(agents): resolve knowledge base tool hierarchy conflict (#10368) (#10369)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-04-26T12:18:55Z @tobiu closed this issue

