Knowledge Base Article
Write a support knowledge-base article that lets a user solve their problem without contacting support: it first scopes the exact user problem, the search terms they would use, prerequisites, and the success outcome, then writes a task-oriented article with a clear title, a short overview, numbered steps with expected results, screenshots/placeholders where needed, and a troubleshooting section, then a review pass verifies accuracy and self-service completeness. Covers help center article, support documentation, how-to article, KB article, self-service docs, and product help. Scoping the precise problem and search terms before writing is the point: a small model that pins the one job-to-be-done writes a findable, followable article instead of a vague overview that leaves the user still stuck.
Steps
Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.
- Article scopeplannerentry
lock the problem, search terms, prerequisites, and success outcome
Show working prompt
1) State the exact user PROBLEM the article solves, phrased as the user experiences it ('I can't log in after changing my email'). 2) List the search terms/keywords a stuck user would type, so the title and intro can match them. 3) List prerequisites (account type, permissions, plan, things they need before starting). 4) Define the SUCCESS outcome — how the user knows it worked. 5) Identify where a screenshot or example would prevent confusion. 6) Note common failure points for the troubleshooting section. Write an acceptance-criteria checklist (e.g. 'title matches likely search terms'; 'prerequisites stated up front'; 'numbered steps with one action each and expected results'; 'a troubleshooting section covers common failures'; 'ends with how to confirm success'; 'a user could self-serve without contacting support'). Use write_task_note for the scope + checklist, and write the same to the produces path. No article prose yet. - Write the articlecopywriter
write the task-oriented, self-service article
Show working prompt
Write the KB article from the scope. 1) Title: action- and search-oriented, matching the user's likely query. 2) Short overview (1-2 sentences): what this article helps them do and who it is for. 3) Prerequisites section. 4) Numbered step-by-step instructions: one action per step, in imperative voice, with the expected result after key steps and screenshot placeholders ('') where the scope flagged them. 5) A 'How to confirm it worked' line tied to the success outcome. 6) A 'Troubleshooting' section addressing the common failure points as a short Q&A. 7) Optional 'Related articles' links. Use scannable H2/H3 headings and a plain, reassuring support voice. Output GitHub-flavored markdown. Save to the produces path and note which checklist items pass. - Accuracy & completeness reviewreviewer
verify the article is accurate and lets a user self-serve
Show working prompt
Review and edit the article in place against the checklist. 1) Walk the steps as if you were the stuck user: are they complete, in order, and each a single clear action? Fix gaps and ambiguity. 2) Verify technical accuracy of every instruction and UI reference; flag anything you cannot confirm. 3) Confirm prerequisites are up front and the success check is present. 4) Confirm the troubleshooting section covers the likely failures. 5) Confirm the title matches search intent. The bar: could a real user solve this without contacting support? If not, fix what blocks them. Save the polished article to the produces path and note any criteria still unmet.
- Evaluatereviewer
Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.
Show working prompt
Read kb-article.md against the scope and walk it as a stuck user. Check EACH criterion and write PASS/FAIL: (a) title matches the likely search terms; (b) prerequisites stated up front; (c) numbered steps, one action each, with expected results; (d) a troubleshooting section covers common failures; (e) a clear 'how to confirm success' step; (f) a real user could self-serve end to end without contacting support. An article that is a vague overview or leaves a step missing FAILS — loop back to write. 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. - 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.
- write a knowledge base article
- help center article
- support how-to
- kb article
- self-service docs
Source
View this craftbook on GitHub · MIT license