Aim Best Practices Researcher

Best Practices Researcher

Research specialist for current best practices. Checks local database first, then web if needed. Stores findings and evaluates skill-worthiness.

Quick Start

# 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,
        attach_raw_cosine=True,  # BP-058/#317: needed for the relevance gate below
    )
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

# Phase 4: Store findings
"${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/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) + append INDEX row
- [ ] Phase 4: Store to database
- [ ] Phase 5: Evaluate skill-worthiness

Write scope (this skill writes ONLY these): the BP file (oversight/knowledge/best-practices/BP-XXX-[topic].md), its INDEX row (oversight/knowledge/best-practices/index.md, appended in Phase 3), and the conventions-collection store (Phase 4). Do NOT edit roadmaps, SoT files, or any other oversight file.

Phase 1: Check Database

Query conventions collection via semantic search. Gate on raw_score not score — see RESEARCH-METHODOLOGY.md ("Phase 1"). Decision rules:

• raw_score ≥0.7 AND content addresses the query AND <6 months old → Use it, skip to Phase 5
• raw_score ≥0.7 AND content addresses the query AND 6-12 months old → Mark "needs refresh", proceed to Phase 2
• raw_score ≥0.7 AND content addresses the query AND >12 months old → Mark "outdated", proceed to Phase 2
• raw_score <0.7, OR content doesn't address the query, OR not found → Proceed to Phase 2

Phase 2: Web Research

Search for current best practices, prioritizing sources published within the last ~6 months relative to today's date (flag an older source only when it remains the authoritative current standard). Source prioritization:

1. Official documentation
2. GitHub repositories
3. Established tech blogs
4. Community discussions

When presenting each finding, state why it is the current gold standard and cite the source's publication recency.

Phase 3: Save to File

1. Generate the next BP-ID by scanning existing files with Glob (oversight/knowledge/best-practices/BP-*.md) — take the highest ID + 1.

2. Write oversight/knowledge/best-practices/BP-XXX-[topic].md using the format from OUTPUT-FORMAT.md.

3. Update the INDEX from disk:

   "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/.venv/bin/python" \
       "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/_ai-memory/skills/aim-best-practices-researcher/scripts/bp_index.py" \
       --write oversight/knowledge/best-practices
   

   bp_index.py appends any BP-*.md file missing from index.md (matched by BP-ID) without touching existing rows — idempotent, non-destructive. Swap --write for --check to verify every BP file has a matching INDEX row (silent when all present; non-zero and lists offenders when not).

   index.md's table is wrapped in a <!-- BEGIN bp-index (...) --> / <!-- END bp-index --> marker pair; --write/--check key canonical-table selection off this region, so a renamed header or a second top-level table doesn't break selection. Markers absent → falls back to header-sniffing and refuses (writes/reports nothing) on ambiguity. Never remove the markers by hand.

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.

# MANDATORY - Run this command to store findings
"${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/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: " or "Duplicate skipped" confirmation
• If duplicate, that's OK - finding already exists
• If exit code 3 / WARNING (stored but embedding incomplete): the finding IS stored but not yet semantically searchable — run backfill_pending_embeddings.py, don't re-run store (it would just report "Duplicate skipped")

Phase 5: Skill Evaluation

Evaluate findings against criteria from 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

Skill Evaluation Criteria

See SKILL-EVALUATION.md

Output Format

See OUTPUT-FORMAT.md