QA Code Agent

Builds and queries a searchable knowledge base of best practices, library patterns,
tools, and session learnings. Storage: ChromaDB qa-knowledge collection at
~/.claude/chroma/.

Triggers

• "qa", "scan project", "code quality", "best practices for X"
• "what worked", "what failed", "patterns in this codebase"
• Starting a new project (query first for relevant prior practices)
• End of a significant code session (auto-capture learnings)

---

Commands

1 — Scan a project (auto-extract patterns)

~/.agents/venv/bin/python ~/.agents/skills/qa-agent/scripts/qa_scan.py /path/to/project

Extracts: stack, dependencies, imports, TODO/FIXME/HACK markers, config files.
Each finding stored as a ChromaDB entry with metadata.

2 — Query the knowledge base

~/.agents/venv/bin/python ~/.agents/skills/qa-agent/scripts/qa_query.py "chromadb best practices"
~/.agents/venv/bin/python ~/.agents/skills/qa-agent/scripts/qa_query.py "python async" --n 10
~/.agents/venv/bin/python ~/.agents/skills/qa-agent/scripts/qa_query.py "what failed" --category failed

3 — Capture a pattern manually

~/.agents/venv/bin/python ~/.agents/skills/qa-agent/scripts/qa_capture.py \
  --content "Always use PersistentClient for ChromaDB — EphemeralClient loses data on restart" \
  --category anti-pattern \
  --library chromadb \
  --tags "chromadb,persistence" \
  --domain python-agents \
  --outcome "prevents silent KB data loss on restart"

4 — Lateral (cross-domain) query

# Find patterns from domains OTHER than aws-cloud that are relevant to "idempotent deduplication"
~/.agents/venv/bin/python ~/.agents/skills/qa-agent/scripts/qa_query.py \
  "idempotent deduplication" --lateral aws-cloud

Lateral mode excludes the specified domain and surfaces transferable patterns from other domains. This is the D4 cross-domain synthesis retrieval path.

---

Sub-agent usage

Other skills query the KB inline to enrich their output:

import subprocess, json
result = subprocess.run(
    ["~/.agents/venv/bin/python",
     "~/.agents/skills/qa-agent/scripts/qa_query.py",
     "topic", "--json"],
    capture_output=True, text=True
)
entries = json.loads(result.stdout)

---

Data schema

ChromaDB collection: qa-knowledge

Field	Values
document	Natural language description of the pattern/practice
category	pattern · anti-pattern · library · tool · worked · failed · config
source	project-scan · manual · session
project	project name or path
language	python · javascript · all · etc.
library	library name if applicable
tags	comma-separated keywords
confidence	high · medium · low
domain	python-agents · aws-cloud · bench-harness · data-pipeline · web-backend · devtools · ml-ops · all
outcome	free text — what happened when this was applied
created_at	ISO timestamp

domain and outcome are the handles for cross-domain synthesis (D4). Use --lateral <domain> in queries to retrieve patterns from other domains ranked by relevance — the creative retrieval path.

---

Behaviour rules

• Always query the KB before starting a non-trivial task on an unfamiliar library.
• After scanning a project, print a summary: N entries added, top libraries found.
• Dedup: before inserting, check if near-identical content already exists (cosine > 0.95).
• Never store secrets, tokens, or personal data in the KB.