Spec Authoring
Turn a rough intent into a backlog-ready spec: interrogate scope and requirements against the real code, then file a well-formed, unambiguous issue.
Steps
Entry step: inspect. Each step names the specialist role it wants; the full working prompt is expandable.
- Inspect the current systemprincipal engineerentry
Map present behavior, relevant code, conventions, dependencies, tests, and constraints.
Show working prompt
Read the approved intent and inspect the relevant workspace before asking the user anything. Trace current behavior through entry points, interfaces, data models, dependencies, tests, and adjacent patterns. Record exact paths and what each proves. Identify root cause for bugs, compatibility boundaries, security or migration risks, and unknowns that cannot be answered from the project. Do not design the change yet. Observable handoff: write the completed result to `specs/source-audit.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.
- Resolve scope and design decisionssolution architect
Close consequential ambiguities and record alternatives, rationale, and boundaries.
Show working prompt
Use `specs/source-audit.md` to enumerate only decisions the workspace cannot settle. Ask the user one consequential question at a time with `ask_user_question`, supplying a recommendation and trade-offs. In unattended mode, make only reversible assumptions and label them. Record the selected architecture, data and interface shapes, compatibility choices, dependency order, out-of-scope items, alternatives rejected, and decisions still blocked. Observable handoff: write the completed result to `specs/decision-log.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.
- Write the implementation specificationspecification writer
Produce a backlog-ready spec with concrete interfaces, sequencing, tests, and rollback.
Show working prompt
Synthesize the source audit and decision log into a self-contained implementation specification. Include current versus proposed behavior, precise file changes, actual schema or API shapes where relevant, dependency-ordered work, measurable acceptance criteria, a testing pyramid, observability, rollout and rollback, effort by component, and explicit exclusions. Split work that cannot be completed safely as one bounded change. Use real workspace paths; never manufacture line numbers or execution results. Observable handoff: write the completed result to `specs/implementation-spec.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.
- Evaluate the deliverableengineering reviewer
Independently grade the observable deliverable and route it to finish, repair, or user escalation.
Show working prompt
Review `specs/implementation-spec.md`, `specs/source-audit.md`, `specs/decision-log.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone. 1. Every material current-state claim and file reference traces to inspected workspace evidence. 2. The proposed architecture, interfaces, data shapes, and sequencing leave no hidden design decision to the implementer. 3. Acceptance criteria are individually observable and pass/fail rather than subjective. 4. The testing plan covers unit, integration, and end-to-end layers in proportion to risk. 5. Migration, compatibility, observability, rollout, and rollback are addressed when relevant. 6. Scope is bounded, exclusions are explicit, and unresolved blockers are not disguised as assumptions. Open `specs/implementation-spec.md`, `specs/source-audit.md`, `specs/decision-log.md` with `read_file`. Write the evidence-backed review to `reviews/spec-authoring-review.md` in the artifacts drawer with `write_artifact`. Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. Then use `advance_task_step` for the active task: PASS routes to `finish`; REVISE routes to `repair` for review rounds 1 through 2, and the 3th REVISE routes to `needs-user`. Never route to finish while a criterion is unmet.
- Repair the deliverablespecification writer
Fix only the concrete gaps from the latest independent review.
Show working prompt
Read `reviews/spec-authoring-review.md` with `read_artifact` and repair every failed criterion in `specs/implementation-spec.md`, `specs/source-audit.md`, `specs/decision-log.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `specs/implementation-spec.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.
- Finishproject lead
All deterministic and reviewer criteria passed.
Show working prompt
The independent review passed. Read `reviews/spec-authoring-review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`specs/implementation-spec.md`, `specs/source-audit.md`, `specs/decision-log.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
- Escalate unresolved concernsproject lead
The bounded repair loop ended without a defensible pass.
Show working prompt
The deliverable did not pass after 3 review rounds. Do not claim success. Read `reviews/spec-authoring-review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.
Triggers
Phrases that suggest this craftbook to a crew.
- spec this out
- file an issue
- write up a ticket
- turn this into an issue
- make this a github issue
- turn this into a backlog item
Source
View this craftbook on GitHub · MIT license