DB-FIRST: Search the Database, Not Memory

Primary source: DB-FIRST.md. Rule: before answering a question that
concerns AGGG2.0 folder content or the sherpa-voice project — DATABASE
FIRST, then answer. Not from memory.

Workflow (order of application)

0. The answer comes ONLY from the database (search.py / MCP db-tools) — not grep, not memory. Having the db-tools MCP tools in the toolset does not replace this skill: it carries the database-selection and freshness rules below.
1. Determine if the question relates to database content. Question about skills/docs/patterns → aggg2.db; about code/voice assistant history → sherpa-voice.db; "we looked at this before / what we concluded" → research.db (findings). Doesn't relate → database not needed.
2. Check that the database exists and is fresh. No project database → build it with the verified target root and executable: python3 <target-root>/db-tools/build.py -r <target-root>/projects/<project> -o <target-root>/db/<project>.db (project-local AGGG2 roots may use their own equivalent command; do not substitute Oper paths silently). (MCP will pick it up automatically). Freshness before work: search.py --refresh -r <root> (incremental, seconds). Searching stale database = wrong answer.
3. Search BEFORE formulating the answer. FTS on content: python3 db-tools/search.py "<query>" (or -b db/sherpa-voice.db). Compound: "pattern AND agent". More results: --limit 5. What you found = FACTS. Everything else = hypotheses that need verification.
4. Find symbols via the project map. Where defined: search.py --symbol load_telegram. Who calls it: --calls. Inheritance: --inherits TestCase (who inherits) / --inherits =FakeStream (from whom). Files with parse errors: --errors. File structure: sqlite SELECT name, line FROM symbols WHERE rel_path='...' AND kind='h2'.
5. What you found — read the file, don't paraphrase. Open the file and quote, reference it in the answer (skills/.../SKILL.md). Match in snippet […] = the answer location.
6. Nothing found → reformulate. Shorter, without declensions ("window" → "windows"). Check database freshness (build.py is incremental; full = --full). "We discussed this" → findings.py search <topic>. Still empty → honestly "not found in database," don't fabricate.

Findings and Conclusions (research.db)

• Record after any research/experiment/analysis: python3 db-tools/findings.py add "Topic" --text "conclusion: what we chose, why, what we rejected, links" --tags "mcp lsp". Topic — short and specific; text — a conclusion useful in a month; tags — 2-4 words. Otherwise knowledge is lost after the conversation.
• Search before "we discussed this": findings.py search mcp / findings.py search "conclusion AND LSP". List: findings.py list / list --tags lsp.
• Links: findings.py link add <id> <id> --kind related|extends|contradicts --note "...", findings.py related <id>, findings.py show <id>, findings.py stats.
• Auto-candidates from session history: db-tools/extract_findings.py (preview) → --add 1,3,7 (add).
• Usage metrics: search.py --stats — top queries, empty results.

Gotchas

• The search.py query must come BEFORE --extra-files (nargs='*' will consume it as a file): search.py "<query>" -b ... --refresh -r ... --extra-files ....
• The database is a fast static layer (symbol, calls, FTS). Need types/scope/ALL references/rename → agent-lsp (lsp-code-depth). Diff review → CRG (code-graph-review).
• Lesson: installed chezmoi without checking existing scripts/install_*.py — always survey existing tooling (scripts/, db-tools/, findings) before adopting new.

Checklist

• Question relates to database content → search BEFORE answering
• Database is fresh (--refresh when working with code)
• What was found = facts; the rest labeled as hypothesis
• After research/analysis → findings.py add
• Nothing found → reformulated → honestly reported

When NOT to use

• General question, code outside the project — database not needed.
• Question about the search itself (how the database works) — that's docs, not search.
• Already searched this query in this session and know the answer.

References

• Primary source: DB-FIRST.md
• Related: lsp-code-depth (depth after database), code-graph-review (diff review), web-research-camoufox (browser for NEW knowledge, database for old)