跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

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 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).

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 file docs/.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

阅读完整来源 ↗