first-plan-semantic-reuse

Semantic Reuse via BM25

Habilita busca por intencao em vez de busca por nome exato. Isso fecha o gap mais comum entre Claude e o codigo: nomes de simbolos divergem da forma como descrevemos intencoes.

Exemplos:

• Query: "validar email" -> encontra validateEmailRFC, is_valid_email, EmailValidator
• Query: "fetch HTTP com retry" -> encontra httpClientWithBackoff, fetchWithRetries, RetryableClient
• Query: "modal de confirmacao" -> encontra ConfirmDialog, useConfirmModal, AlertConfirmation

Workflow

Passo 1 - Detectar engine

ENGINE=""
for c in "${CLAUDE_PLUGIN_ROOT}/engine/bin/first-plan-engine" "${HOME}/.local/bin/first-plan-engine" "$(command -v first-plan-engine 2>/dev/null)"; do
  [ -x "$c" ] && ENGINE="$c" && break
done

Se ausente, oferecer first-plan-engine-bootstrap skill ou cair no fallback markdown.

Passo 2 - Garantir indice atualizado

DB=".first-plan/cache/search.db"
# Re-indexar se DB nao existe ou esta stale (>= 24h)
if [ ! -f "$DB" ] || [ $(find "$DB" -mmin +1440 | wc -l) -gt 0 ]; then
  "$ENGINE" index --repo . --db-path "$DB" --output-json /tmp/idx.json
  echo "indexado: $(jq -r .total_symbols /tmp/idx.json) simbolos em $(jq -r .elapsed_ms /tmp/idx.json)ms"
fi

Passo 3 - Query

"$ENGINE" search \
  --db-path "$DB" \
  --query "<intencao>" \
  --limit 10 \
  --output-json /tmp/search.json

Output JSON first-plan-search-v1:

{
  "$schema": "first-plan-search-v1",
  "query": "<intencao>",
  "hits": [
    {
      "symbol": {
        "name": "ValidateEmail",
        "kind": "function",
        "language": "go",
        "path": "pkg/validation/email.go",
        "line": 12,
        "signature": "func ValidateEmail(s string) error",
        "doc": "Valida formato RFC 5322"
      },
      "score": 8.42,
      "matched_tokens": ["validate", "email"]
    }
  ]
}

Passo 4 - Renderizar para usuario

Para /fp:reuse <intencao>, mostrar top 5 com:

• Nome + path:line
• Signature
• Doc resumida
• Score (ajuda o usuario calibrar relevancia)
• Matched tokens (transparencia sobre o ranking)