gilde

← All craftbooks

Technical Design Doc

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

Write a technical design document (RFC / engineering design doc) that gets a system change reviewed and approved — covering context and problem, goals and non-goals, the proposed design, alternatives considered, trade-offs, risks, and a rollout plan. Scopes the problem, goals, and explicit non-goals FIRST (non-goals prevent reviewer scope-creep), writes the detailed design with diagrams and alternatives, then has a reviewer check it for completeness and unjustified decisions. Use for RFCs, architecture proposals, and pre-implementation design reviews.

Steps

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

  1. Scope the designplannerentry

    problem, goals, explicit non-goals, constraints, success metrics

    Show working prompt
    Frame the problem before proposing a solution. Step 1: write the context and problem statement — what is broken or needed and why now. Step 2: list the GOALS (what the design must achieve) and, explicitly, the NON-GOALS (what it deliberately will not address) — the non-goals keep the review focused. Step 3: capture the constraints (compatibility, performance, deadline, team, existing systems) the design must respect. Step 4: define success metrics — how you will know the change worked. Step 5: note at least one alternative direction worth documenting so the doc shows the decision was considered. Step 6: write an acceptance-criteria checklist ('problem + context stated', 'goals AND non-goals listed', 'constraints captured', 'success metrics defined', 'at least one alternative to document', 'a rollout/migration consideration noted'). Write the framing + checklist via write_task_note AND to notes/scope.md. No detailed design yet.
  2. Write the designdeveloper

    detailed proposed design, alternatives, trade-offs, rollout plan

    Show working prompt
    Write the design document as spec.md. Step 1: open with the context/problem, then the goals and non-goals exactly as scoped. Step 2: write the Proposed Design in depth — components and responsibilities, data model/schema changes, APIs/interfaces, and the key flows; include at least one diagram (an ASCII/mermaid block is fine) of the architecture or sequence. Step 3: write an Alternatives Considered section covering each documented alternative with its pros/cons and WHY it was rejected — every significant decision must be justified, not asserted. Step 4: write a Trade-offs and Risks section (what this design gives up, failure modes, mitigations). Step 5: write a Rollout/Migration plan (phasing, flags, backfill, backward compatibility) and a Testing/validation plan tied to the success metrics. Step 6: list open questions. Use numbered headings and keep it concrete with real names. On a loop-back, fix ONLY the named gaps. Write the path + section count via write_task_note.
  3. Review the designreviewer

    check completeness, justified decisions, and risk coverage

    Show working prompt
    Review the design as a staff engineer would in an RFC review. Step 1: confirm the proposed design actually satisfies every stated goal and respects every non-goal and constraint. Step 2: check that each significant decision is justified against the documented alternatives — flag any choice asserted without reasoning. Step 3: verify the risks/trade-offs section is honest (not just 'no risks') and the rollout plan addresses backward compatibility and a way to back out. Step 4: confirm a testing/validation plan ties back to the success metrics. Step 5: list concrete gaps with the section and the fix needed, recorded as PASS/FAIL against the scope checklist. Write the findings via write_task_note AND to notes/review.md. Remaining 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 design doc against the locked criteria. Step 1: read spec.md end to end. Step 2: check EACH acceptance criterion: problem + context stated, goals AND non-goals present, constraints captured, the proposed design includes a diagram and concrete interfaces/data model, alternatives are documented with reasons for rejection, risks/trade-offs are honest, a rollout/migration plan with a back-out path exists, and a validation plan ties to the success metrics. Step 3: confirm decisions are justified rather than asserted, folding in notes/review.md findings. Write PASS/FAIL per criterion with the offending section 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