faq-mine
Mine docs/faq.md from README.md, docs/*.md, and the pi-hermes memory stores. Dispatches @fast subagents per source, dedupes against the existing FAQ, and merges entries in caveman style. Use when asked to "build / regenerate / extend the FAQ", "mine docs into FAQ", "mine hermes memory into FAQ", "surface runtime problems in the FAQ", or "create FAQ from README + docs".
BlackBeltTechnology · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill faq-mine技能说明
name: faq-mine description: 'Mine docs/faq.md from README.md, docs/*.md, and the pi-hermes memory stores. Dispatches @fast subagents per source, dedupes against the existing FAQ, and merges entries in caveman style. Use when asked to "build / regenerate / extend the FAQ", "mine docs into FAQ", "mine hermes memory into FAQ", "surface runtime problems in the FAQ", or "create FAQ from README + docs".' license: MIT compatibility: Requires @fast subagents (general-purpose) + write access to docs/ + read access to ~/.pi/agent hermes stores. metadata: author: robson version: "2.0"
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 evergreendocs/*.md.--docs skip= memory-only run (disables doc mining; the ship-change harvest path). - Optional
--memory <off|project|failures|all>— hermes stores to mine. Defaultfailures= project store + globalfailures.md(relevance-filtered).off= docs only.all= also globalMEMORY.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
- Read
docs/faq.mdif 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.
- If file missing, create with header:
- Enumerate candidate source docs (SKIP this whole step when
--docs skip— memory-only run):
Exclude:ls README.md docs/*.md 2>/dev/nulldocs/faq.mditselfdocs/faq.agent.md(condensed index derived FROM faq.md — refreshed in Phase 4, never mined)docs/AGENTS.mdand anyAGENTS.md(index, not narrative)docs/session-knowledge-*.md(point-in-time notes)docs/spec-gap-analysis.mdand any*-resolved.md(transient analyses)- Anything matching
docs/.faq-draft-*.md(in-flight draft)
- For each remaining doc, capture
wc -lto surface size. - 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$PROJdir 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).
- Project store
Phase 1 — Confirm scope
Use ask_user (multiselect) to let the user pick which sources to mine — list the docs AND the resolved hermes stores as options. Pre-select the evergreen docs + the project store + failures.md. Skip the prompt only when the user already passed both --docs and --memory.
Phase 2 — Parallel extraction (@fast subagents)
Dispatch ONE general-purpose subagent with model: @fast, run_in_background: true per selected source (docs AND stores). All agents run in parallel — each writes to its OWN draft file to avoid write conflicts:
- Docs →
docs/.faq-draft-<basename>.md - Stores →
docs/.faq-draft-mem-<label>.md(label=project|failures|memory)
Phase 2A — Doc mining
Subagent prompt template (substitute <DOC> with the source doc path):
Mine FAQ-worthy entries from
<DOC>and write them to a NEW filedocs/.faq-draft-<basename>.md. Do NOT touch any other file.STEP 1 — read existing
docs/faq.md. Extract every## <Question>heading. DEDUPE: skip questions already covered (or trivially equivalent).STEP 2 — read
<DOC>fully. Identify recurring how-to / what-is questions a user or future agent would actually ask. Aim for 4–10 entries. Quality > quantity. Skip implementation trivia.STEP 3 — write the draft using the EXACT format of existing faq.md entries:
## <Question>? <one-line terse answer> Command: `<cmd>` (when applicable; omit for what-is questions). <optional bullets / sub-sections with concrete tokens> Cross-refs: - <DOC>:<line> - <other source file:line>CAVEMAN STYLE (verbatim, all docs/ prose obeys):
- Short declarative fragments. Drop articles (a/an/the) and most copulas (is/are/was) when meaning survives.
- Subject → verb → object, present tense. No hedging, no marketing voice, no "we", no "you".
- One fact per line/row. No restating context the file already establishes.
- Prefer concrete tokens (paths, function names, env vars, ports, exit codes) over prose.
- Keep symbols/identifiers verbatim; only connective tissue compresses.
Verify every command + path against the source doc. No invented flags, no speculation. Confirm completion in your final reply with the entry count.
Phase 2B — Hermes memory mining
Runtime problems live in the hermes stores as §-separated terse entries, each stamped <!-- created=…, last=… -->. Convert each FAQ-worthy problem into a symptom-first Q&A entry. One subagent per store.
Subagent prompt template (substitute <STORE> = absolute s