aim-best-practices-researcher

# Best Practices Researcher Research specialist for current (2024-2026) best practices. Checks local database first, then web if needed. Stores findings and evaluates skill-worthiness. ## Quick Start ```python # Phase 1: Check database import os import sys sys.path.insert(0, os.path.join(os.path.expanduser("~/.ai-memory"), "src")) from memory.search import search_memories from memory.secrets_env import pin_qdrant_api_key, is_auth_error # Pin QDRANT_API_KEY from .env.secrets so a stale exported key can't silently # fail auth and degrade this search to file-only (run-with-env.sh parity). pin_qdrant_api_key() # The 'conventions' collection is project-scoped (PLAN-028 P1, DEC-PM298-D4). # Resolve the project from AI_MEMORY_PROJECT_ID — never from os.getcwd(), which # is unreliable for this forked skill subprocess. Fail loud if it is not set. project_id = os.environ.get("AI_MEMORY_PROJECT_ID") if not project_id: raise RuntimeError( "AI_MEMORY_PROJECT_ID is not set — cannot search the project-scoped " "'conventions' collection. Set AI_MEMORY_PROJECT_ID and retry." ) try: results = search_memories( query="your topic", collection="conventions", group_id=project_id, memory_type=["guideline", "rule"], limit=5 ) except Exception as e: # Auth failure: the knowledge base was NOT consulted. Do not present this # as "no results found" — results are file-only. if is_auth_error(str(e)): print("❌ Memory search auth FAILED (401) — knowledge base NOT " "consulted; results are file-only") raise ``` ```bash # Phase 4: Store findings scripts/memory/run-with-env.sh store_best_practice.py \ --content "Best practice description" \ --session-id "current-session" \ --domain "python" \ --tags topic \ --source "https://source-url.com" \ --source-date "2026-01-29" \ --group-id "$AI_MEMORY_PROJECT_ID" ``` ## 5-Phase Workflow Copy this checklist and track progress: ``` Research Progress: - [ ] Phase 1: Check database (conventions collection) - [ ] Phase 2: Web research (if needed) - [ ] Phase 3: Save to file (BP-XXX.md) - [ ] Phase 4: Store to database - [ ] Phase 5: Evaluate skill-worthiness ``` ### Phase 1: Check Database Query conventions collection via semantic search. Decision rules: - Score >0.7 and <6 months old → Use it, skip to Phase 5 - Score >0.7 and >6 months old → Mark "needs refresh", proceed to Phase 2 - Score <0.7 or not found → Proceed to Phase 2 ### Phase 2: Web Research Search for current best practices (2024-2026). Source prioritization: 1. Official documentation 2. GitHub repositories 3. Established tech blogs 4. Community discussions ### Phase 3: Save to File Generate next BP-ID and create `oversight/knowledge/best-practices/BP-XXX-[topic].md` ### Phase 4: Store to Database (MANDATORY) **CRITICAL**: You MUST run this command to store findings to the database. Without this step, research is lost and BUG-048 occurs. ```bash # MANDATORY - Run this command to store findings scripts/memory/run-with-env.sh store_best_practice.py \ --content "YOUR_FINDING_CONTENT_HERE" \ --session-id "YOUR_SESSION_ID" \ --domain "YOUR_DOMAIN" \ --tags YOUR TAGS \ --source "SOURCE_URL" \ --source-date "2026-05-30" \ --group-id "$AI_MEMORY_PROJECT_ID" ``` **Checklist before moving to Phase 5**: - [ ] Ran store_best_practice.py via run-with-env.sh - [ ] Received "Stored: <id>" or "Duplicate skipped" confirmation - [ ] If duplicate, that's OK - finding already exists ### Phase 5: Skill Evaluation Evaluate findings against criteria from [SKILL-EVALUATION.md](SKILL-EVALUATION.md): **Decision rule**: (Process-oriented AND Reusable) OR Stack Pain Point → recommend skill If skill-worthy, prompt user. If user confirms, invoke Skill Creator. ## Detailed Methodology See [RESEARCH-METHODOLOGY.md](RESEARCH-METHODOLOGY.md) ## Skill Evaluation Criteria See [SKILL-EVALUATION.md](SKILL-EVALUATION.md) ## Output Format See [OUTPUT-FORMAT.md](OUTPUT-FORMAT.md)