diff options
| author | Craig Jennings <c@cjennings.net> | 2026-06-21 23:49:26 -0400 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-06-21 23:49:26 -0400 |
| commit | ed27e3c760bdc924edcba85bc99ed083df484086 (patch) | |
| tree | c27d289dd31035edd55dc68ac68d9d0adb1db628 /.ai/workflows/INDEX.org | |
| parent | 98ebb2f37d6dba1c5864d49744e8adb8c392c589 (diff) | |
| download | rulesets-ed27e3c760bdc924edcba85bc99ed083df484086.tar.gz rulesets-ed27e3c760bdc924edcba85bc99ed083df484086.zip | |
refactor: fold spec review findings into the spec itself
The spec-review/spec-response pair wrote findings to a sibling <spec>-review.org file that spec-response deleted once processed. The deletion left the iteration-history Artifacts line dangling and dropped the verbatim review. Keeping the file instead collided with spec-response's file discovery and its "no review files remain" done-condition.
Findings now live in the spec under a * Review findings section as TODO tasks with a [/] cookie, the same shape * Decisions already uses. The reviewer records findings there. The responder completes each in place (accept and modify finish DONE, reject finishes CANCELLED with the reason), and the readiness rubric gates on the cookie. A scope-expanding response re-runs the rubric and files any new obligation as a finding or decision before claiming Ready, because resolving every finding can still introduce unreviewed assumptions.
Also folds in two reviewer-practice principles: keep review and response roles explicit, and cite the source for external-dependency facts in a finding. Updates spec-create.org and the workflow INDEX so the trio describes one convention.
Diffstat (limited to '.ai/workflows/INDEX.org')
| -rw-r--r-- | .ai/workflows/INDEX.org | 4 |
1 files changed, 2 insertions, 2 deletions
diff --git a/.ai/workflows/INDEX.org b/.ai/workflows/INDEX.org index a45807e..5ae8480 100644 --- a/.ai/workflows/INDEX.org +++ b/.ai/workflows/INDEX.org @@ -81,9 +81,9 @@ This index must list every =.org= file in =.ai/workflows/= except this one and e - =spec-create.org= — author a design/feature spec before non-trivial work (more than ~6 hours, or real trade-offs): a when-to-spec gate, then problem-first framing, design + alternatives + inline mini-ADR decisions, implementation phases + acceptance criteria + a readiness-dimensions menu, a terseness pass, and a hand-off self-check against the review rubric. The *author* side that starts the trio; its output feeds =spec-review.org=. - Triggers: "let's write a spec", "spec this out", "create a spec for X", "spec-create workflow" -- =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 =<spec>-review.org= file when not ready. The *reviewer* side; its output feeds =spec-response.org=. +- =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 record findings as =TODO= tasks in the spec's =* Review findings= section 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 =<spec>-review.org= file =spec-review.org= produces. +- =spec-response.org= — fold a spec review back in: decide accept / modify / reject for every finding, weave accepts into the spec body, complete each finding task in place (the reason recorded on modifies and rejects), reconcile cross-spec tensions, iterate to implementation-ready. The *author* side; consumes the =* Review findings= =spec-review.org= produces. - Triggers: "respond to the review", "process the spec reviews", "spec-response workflow", "fold in the review" ** Tools and meta |
