faq-mine

Orchestrate FAQ extraction from project knowledge docs AND pi-hermes memory stores into docs/faq.md.

Two source classes:

• Docs — README.md + evergreen docs/*.md. How-to / what-is questions.
• Hermes memory — accumulated runtime problems (tool-quirks, failures, insights, corrections) that never reach the docs. These carry the "why does X fail / how do I fix Y" answers a future agent keeps re-discovering.

Inputs:

• Optional --docs <a.md>,<b.md> — explicit doc list. Default = README.md + every evergreen docs/*.md. --docs skip = memory-only run (disables doc mining; the ship-change harvest path).
• Optional --memory <off|project|failures|all> — hermes stores to mine. Default failures = project store + global failures.md (relevance-filtered). off = docs only. all = also global MEMORY.md.
• Optional --max <N> — entry cap per source (default ~10).

Non-interactive: passing BOTH --docs (incl. --docs skip) and --memory skips the Phase 1 prompt — the headless invocation faq-mine --docs skip --memory failures runs memory-only with no ask_user.

Phase 0 — Pre-flight

1. Read docs/faq.md if it exists. Extract every ## <Question> heading into a dedupe list.
   • If file missing, create with header:

     # FAQ
     
     FAQ. How-to answers that already live in README.md + docs/. New entries here when same question recurs.
     

2. Enumerate candidate source docs (SKIP this whole step when --docs skip — memory-only run):

   ls README.md docs/*.md 2>/dev/null
   

   Exclude:
   • docs/faq.md itself
   • docs/faq.agent.md (condensed index derived FROM faq.md — refreshed in Phase 4, never mined)
   • docs/AGENTS.md and any AGENTS.md (index, not narrative)
   • docs/session-knowledge-*.md (point-in-time notes)
   • docs/spec-gap-analysis.md and any *-resolved.md (transient analyses)
   • Anything matching docs/.faq-draft-*.md (in-flight draft)
3. For each remaining doc, capture wc -l to surface size.
4. Enumerate hermes memory stores (unless --memory off):

   PROJ=$(basename "$(git rev-parse --show-toplevel)")
   ls -l "$HOME/.pi/agent/projects-memory/$PROJ/MEMORY.md" \
         "$HOME/.pi/agent/pi-hermes-memory/failures.md" \
         "$HOME/.pi/agent/pi-hermes-memory/MEMORY.md" 2>/dev/null
   

   • Project store projects-memory/$PROJ/MEMORY.md — all entries repo-scoped, no filter. If $PROJ dir absent (e.g. worktree name differs), ls ~/.pi/agent/projects-memory/ and pick the matching dir; skip if none.
   • Global pi-hermes-memory/failures.md — mixed across projects, needs a repo-relevance filter (subagent applies it).
   • Global pi-hermes-memory/MEMORY.md — mixed, only when --memory all.
   • Any store path that does not exist: skip silently (fresh machine).