From 7f2aea1e022c93f3eb463e5222bdb0d8ae6288b9 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sat, 23 May 2026 12:59:31 -0500 Subject: feat(workflows): add spec-review and spec-response workflow pair These two workflows form a reviewer side and an author side for taking a design spec to implementation-ready. spec-review judges a spec against a readiness gate, reads the code before critiquing, evaluates across dimensions, assigns a rubric (Ready / Ready-with-caveats / Not-ready / Needs-research), and writes a -review.org file when it isn't ready. spec-response consumes that file: it decides accept / modify / reject for every recommendation, weaves the accepts into the spec body, records the modifies and rejects with reasons in a "Review dispositions" section, and reconciles tensions when coupled specs get reviewed together. The review file is the contract between them. Both were validated by a real run on 2026-05-23 before landing here. I then reviewed them against established practice and tightened five things. The readiness gate now covers security/privacy and observability, since a spec shouldn't pass with those undefined. Phase 1 is a fast triage and Phase 3 is the authoritative gate after the code read. Finding severity maps to blocking power. A rejection goes back to the reviewer instead of standing as a unilateral call. And the response loop has an explicit termination condition. I added both to INDEX.org under a new "Specs and design" section with trigger phrases, cross-linked as a pair, and kept the canonical and mirror copies identical. --- .ai/workflows/INDEX.org | 7 +++++++ 1 file changed, 7 insertions(+) (limited to '.ai/workflows/INDEX.org') diff --git a/.ai/workflows/INDEX.org b/.ai/workflows/INDEX.org index 756c6a9..bad2a48 100644 --- a/.ai/workflows/INDEX.org +++ b/.ai/workflows/INDEX.org @@ -66,6 +66,13 @@ This index must list every =.org= file in =.ai/workflows/= except this one. Star - =email-assembly.org= — gather documents into an email package. - Triggers: "assemble an email", "email assembly workflow", "gather documents for an email", "I need to send [person] some documents" +** Specs and design + +- =spec-review.org= — review a design/feature spec for implementation-readiness: run the readiness gate, read the code first, evaluate across dimensions, assign a rubric (Ready / Ready-with-caveats / Not-ready / Needs-research), and write a =-review.org= file when not ready. The *reviewer* side; its output feeds =spec-response.org=. + - Triggers: "review the spec", "is this spec implementation-ready?", "spec-review workflow", "review the design" +- =spec-response.org= — fold an external spec review back in: decide accept / modify / reject for every recommendation, weave accepts into the spec body, document modifies and rejects in a "Review dispositions" section, reconcile cross-spec tensions, iterate to implementation-ready. The *author* side; consumes the =-review.org= file =spec-review.org= produces. + - Triggers: "respond to the review", "process the spec reviews", "spec-response workflow", "fold in the review" + ** Tools and meta - =process-meeting-transcript.org= — record → transcript → labeled archive. -- cgit v1.2.3