gilde

← All craftbooks

Team Handbook Section

Documents and decksevalv1.0.0released 2026-06-05workflow: build-loop

Write a clear, reference-grade section of a team/company handbook — a policy, process, or how-we-work doc that a new hire can read once and act on correctly. Scopes the policy's intent, audience, and edge cases FIRST, writes unambiguous prose with concrete examples, a quick-reference summary, and FAQ, then has a reviewer check it for ambiguity and contradictions with how things actually work. Use for onboarding docs, policy pages, process documentation, and internal wikis.

Steps

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

  1. Scope the sectionplannerentry

    intent, audience, what's in/out, and the tricky edge cases

    Show working prompt
    Define the policy/process before writing it. Step 1: state the section's intent — what behavior or knowledge it is trying to produce — and who reads it. Step 2: define what this section covers and what it explicitly does not (link-outs for the rest). Step 3: enumerate the edge cases and 'what if' questions people actually hit, because unhandled edge cases are where handbooks fail. Step 4: decide whether the topic is a POLICY (rules + rationale) or a PROCESS (ordered steps + owners) and structure accordingly. Step 5: write an acceptance-criteria checklist ('states intent up front', 'covers the enumerated edge cases', 'includes at least one concrete example', 'has a quick-reference summary (TL;DR)', 'unambiguous — no "usually/it depends" without resolution', 'owner/contact named for questions'). Write the scope + edge-case list + checklist via write_task_note AND to notes/scope.md. No prose yet.
  2. Write the sectioncopywriter

    unambiguous prose with examples, TL;DR, and FAQ

    Show working prompt
    Write the handbook section as handbook.md so a new hire reads it once and acts correctly. Step 1: open with a one-line TL;DR / quick-reference summary capturing the rule or the steps at a glance. Step 2: state the intent/why briefly (people follow policy better when they understand it). Step 3: write the body — for a POLICY, the rules with rationale; for a PROCESS, NUMBERED steps with the owner/role for each — in plain, direct language. Step 4: include at least one concrete worked example showing the policy/process applied. Step 5: write a short FAQ resolving every enumerated edge case with a definite answer (no 'it depends' left dangling). Step 6: name the owner/contact for questions and the last-reviewed date. Avoid hedging where a decision is needed. On a loop-back, fix ONLY the named gaps. Write the path via write_task_note.
  3. Review for clarityreviewer

    hunt for ambiguity, contradictions, and unanswered edge cases

    Show working prompt
    Review the section for the failure modes that make handbooks useless. Step 1: read it as a new hire and flag any sentence that leaves you unsure what to actually do. Step 2: check every enumerated edge case is answered definitively in the FAQ or body. Step 3: hunt for internal contradictions and for hedging ('usually', 'generally') where a firm answer is required. Step 4: confirm the TL;DR matches the detailed body and the example is correct. Step 5: list concrete gaps with the location and the fix, recorded as PASS/FAIL against the scope checklist. Write the findings via write_task_note AND to notes/review.md. Gaps must be fixed in the write phase before this passes.
  4. Evaluatereviewer

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

    Show working prompt
    QA the handbook section against the locked criteria. Step 1: read handbook.md as a brand-new hire. Step 2: check EACH acceptance criterion: a TL;DR/quick-reference is present and matches the body, the intent is stated up front, the body is unambiguous (no unresolved 'it depends'), every enumerated edge case is answered, at least one concrete example is present and correct, and an owner/contact is named. Step 3: confirm there are no internal contradictions, folding in notes/review.md findings. Write PASS/FAIL per criterion with the offending location on any FAIL.

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