gilde

← All craftbooks

FAQ from Source Docs

Content and writingevalv1.0.0released 2026-06-05workflow: build-loop

Build a grounded FAQ page by mining real source documents for the questions users actually ask, then writing tight, accurate answers traced back to the source: it first researches the corpus to extract candidate questions, dedupes and groups them, and ranks by likely frequency, then writes clear question-and-answer pairs where every answer is supported by the docs. Covers FAQ generation, help center questions, support docs, knowledge mining, common questions, and self-service content. Mining the source before writing is the point: a small model that derives questions from the actual docs avoids inventing FAQs nobody asks and answers the docs cannot support.

Steps

Entry step: mine. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Mine the questionsresearcherentry

    extract, dedupe, group, and rank candidate questions from the docs

    Show working prompt
    1) Read all source documents/files in scope. 2) Extract every implicit and explicit question the docs answer — phrase each as a real user would ask it ('How do I reset my password?'), not as a doc heading. 3) Dedupe near-identical questions and group them into 3-6 topical sections. 4) Rank questions within each section by likely frequency/importance. 5) For each kept question, note the source location (file + section/anchor) that supports the answer, so the writer can ground it. Write an acceptance-criteria checklist (e.g. 'every question is answerable from the docs'; 'questions phrased in user language'; 'grouped into clear sections'; 'no fabricated questions or answers'; 'each Q maps to a source'). Use write_task_note for the question bank with sources + checklist, and write the same to the produces path. No final answers yet.
  2. Write the FAQcopywriter

    write grounded Q&A pairs in scannable sections

    Show working prompt
    Write the FAQ from the mined question bank. 1) Organize into the grouped sections, each with an H2 header. 2) For each question, write it as an H3 (or bold) line, then a concise answer (1-4 sentences) drawn strictly from the source docs — no speculation beyond what the docs support. 3) Where a doc has step-by-step detail, render the answer as a short numbered list. 4) Keep a consistent, plain, reassuring support voice. 5) Add a short intro line at the top and, where useful, a 'see also' link to the source doc. Output GitHub-flavored markdown. Save to the produces path and note total Q&A count and section count.
  3. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Read faq.md and cross-check against the mined question bank and the source docs. Check EACH criterion and write PASS/FAIL: (a) every answer is supported by the source docs (spot-check 4-5 against their cited source); (b) questions are phrased in natural user language; (c) Q&As are grouped into clear sections with headers; (d) no fabricated questions or unsupported answers; (e) answers are concise and consistently voiced. An FAQ with invented or unsupported answers FAILS — loop back to write and name the offending entries.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "write" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  4. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license