diff options
| -rw-r--r-- | .ai/workflows/INDEX.org | 4 | ||||
| -rw-r--r-- | .ai/workflows/spec-create.org | 4 | ||||
| -rw-r--r-- | .ai/workflows/spec-response.org | 61 | ||||
| -rw-r--r-- | .ai/workflows/spec-review.org | 104 | ||||
| -rw-r--r-- | claude-templates/.ai/workflows/INDEX.org | 4 | ||||
| -rw-r--r-- | claude-templates/.ai/workflows/spec-create.org | 4 | ||||
| -rw-r--r-- | claude-templates/.ai/workflows/spec-response.org | 61 | ||||
| -rw-r--r-- | claude-templates/.ai/workflows/spec-review.org | 104 |
8 files changed, 146 insertions, 200 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 diff --git a/.ai/workflows/spec-create.org b/.ai/workflows/spec-create.org index f90c511..508b969 100644 --- a/.ai/workflows/spec-create.org +++ b/.ai/workflows/spec-create.org @@ -10,7 +10,7 @@ The guiding principle, drawn from how Google, Oxide, Amazon, Basecamp, and the A It is the front of a trio: - =spec-create.org= (this one) — author writes the spec. -- =spec-review.org= — a reviewer gates the spec for implementation-readiness and writes =<spec-basename>-review.org=. +- =spec-review.org= — a reviewer gates the spec for implementation-readiness and records findings in the spec's =* Review findings= section. - =spec-response.org= — the author folds the review back in. The spec this workflow produces has to *pass spec-review's gate* — that gate is the definition of done. So the structure below is built to answer the reviewer's questions up front. Keep it lightweight anyway: a short required spine plus a *readiness-dimensions menu* where each item is either answered or explicitly marked "N/A because…". The best spec is the shortest one that still lets an engineer build it, test it, and ship behavior that matches the user's mental model. @@ -59,7 +59,7 @@ Capture, in this order: This is where the spec earns a "Ready" from review: an engineer must be able to build it in steps, know when it's done, and never have to invent product behavior mid-implementation. -1. *Implementation phases* — decompose the work into phases each small enough to finish in one focused session and each leaving the tree in a working (not half-broken) state. =spec-review= lifts this section straight into =todo.org= tasks, so a spec that can't be phased fails the gate — the absence is itself a finding. +1. *Implementation phases* — decompose the work into phases each small enough to finish in one focused session and each leaving the tree in a working (not half-broken) state. =spec-review= checks this section decomposes cleanly and =spec-response= lifts it into =todo.org= tasks, so a spec that can't be phased fails the gate — the absence is itself a finding. 2. *Acceptance criteria* — the observable conditions that mean the feature works, written as checkable items. The review's test-surface task mirrors these. 3. *Readiness dimensions* — walk this menu and, for each, either define the behavior or write "N/A because…". The escape hatch keeps a simple spec short; the prompt keeps a hidden decision from slipping into implementation: - *Data model & ownership* — what's user-authored / generated / cached / remote; who owns each editable region; what persists vs refreshes. diff --git a/.ai/workflows/spec-response.org b/.ai/workflows/spec-response.org index 2686cf8..de5b1c8 100644 --- a/.ai/workflows/spec-response.org +++ b/.ai/workflows/spec-response.org @@ -5,9 +5,9 @@ * Overview -The spec-response workflow processes external reviews of a design spec and folds them into the spec until it is implementation-ready. A reviewer (human or another agent) leaves a review file next to the spec — typically produced by its counterpart, the *spec-review* workflow, which writes =<spec-basename>-review.org= and assigns a readiness rubric. Claude works through every recommendation, deciding accept / modify / reject for each, updates the spec for the accepted ones, documents the modified and rejected ones with reasons, then deletes the review file. Repeat for each spec under review. +The spec-response workflow processes a review's findings and folds them into the spec until it is implementation-ready. A reviewer (human or another agent) records findings in the spec's =* Review findings= section — typically via its counterpart, the *spec-review* workflow, which writes one =TODO= task per finding (=[/]= cookie on the heading) and assigns a readiness rubric. Claude works through every finding, deciding accept / modify / reject, updates the spec body for the accepted ones, and completes each finding task in place: accept and modify finish =DONE= (the modify's change noted in the body), reject finishes =CANCELLED= with the reason. Repeat for each spec under review. -The output is a spec a reader could implement from, plus a durable record — inside the spec — of why any recommendation was changed or declined, so the reviewer can find the reasoning later without re-litigating. +The output is a spec a reader could implement from, plus a durable record — inside the spec — of why any finding was changed or declined, so the reviewer can find the reasoning later without re-litigating. The reasoning lives on the completed finding task, not a separate file. This workflow was first run on 2026-05-23 against the linear-emacs =issue-query-spec.org= and =issue-representation-spec.org= reviews, and written up from that run. @@ -27,25 +27,25 @@ A review is only useful if every point in it gets a decision. Without a defined A spec's review is fully processed when: -1. *Every recommendation has an explicit disposition* — accepted, modified, or rejected. None dropped. -2. *Accepted recommendations are woven into the spec body* — the spec reads as if they were always there, not appended as a changelog. -3. *Modified and rejected recommendations are documented in a bottom section* (e.g. "Review dispositions") with a one-paragraph reason each, so the reviewer can find the reasoning. +1. *Every finding has an explicit disposition* — accepted, modified, or rejected, and its task completed (=DONE= or =CANCELLED=). None dropped. +2. *Accepted findings are woven into the spec body* — the spec reads as if they were always there, not appended as a changelog. +3. *Modified and rejected findings carry a one-paragraph reason in the completed task's body*, so the reviewer can find the reasoning. 4. *Review/response provenance is documented in the spec* — iteration count/date, contributor, role, what changed, and why. 5. *Pre-agreed decisions are flipped to =DONE=* — each settled decision's =TODO= becomes =DONE=, and the =[/]= cookie on the spec's =* Decisions= heading reflects the tally. 6. *Cross-spec tensions are reconciled in writing* when related specs were reviewed together. -7. *The review file is deleted* once 1-6 hold. +7. *Every finding task is completed* — the =* Review findings= =[/]= cookie reads complete (each finding =DONE= or =CANCELLED=). 8. *Tracking is updated* — the spec's VERIFY/task body notes "review incorporated" and whether it's implementation-ready. 9. *Implementation tasks exist* — once the author confirms the spec is Ready, the project's =todo.org= carries the full implementation-task breakdown (Phase 6), reviewed for completeness, with =:solo:= marked and a Manual-testing task for everything else. -The whole run is done when no =*-review.org= files remain and each spec is judged implementation-ready (or its remaining blockers are named). +The whole run is done when every spec's =* Review findings= cookie reads complete and each spec is judged implementation-ready (or its remaining blockers are named). -*Measurable validation:* a reader scanning the review against the revised spec can find, for every review point, either the change in the body or its disposition at the bottom. Nothing is unaccounted for. +*Measurable validation:* a reader scanning the spec can find, for every finding, either the change in the body or its disposition on the completed finding task. Nothing is unaccounted for. * When to Use This Workflow Trigger when: -- A reviewer drops a review file alongside a spec — convention: same basename with a =-review.org= suffix (=foo.org= → =foo-review.org=). +- A reviewer records findings in the spec's =* Review findings= section — typically via the spec-review workflow. - Craig says "respond to the review" / "let's run the spec-response workflow" / "process the spec reviews." - Any time a spec needs to absorb structured external feedback and converge to implementation-ready. @@ -63,7 +63,7 @@ the file should be renamed first. Spec workflows require the -spec.org suffix as guard against pointing the workflow at tutorial, inventory, or setup docs. #+end_example -The review file the response consumes follows the convention =<spec-basename>-review.org=, so a misnamed spec produces a mis-pointed review file too. Fix the spec name first. +The findings the response consumes live in the spec's own =* Review findings= section, so the spec filename is the handle the workflow keys on — point it at the right =-spec.org= file. Fix the spec name first. The user resolves the mismatch and re-invokes the workflow. Do not proceed with the response against a misnamed spec. @@ -71,7 +71,7 @@ The user resolves the mismatch and re-invokes the workflow. Do not proceed with ** Phase 0: Orient -1. List the review files (=ls docs/*-review.org= or wherever they live). Process them one at a time in whatever order; the user may name an order. +1. Find specs with open findings — a =* Review findings= section whose =[/]= cookie isn't complete (=TODO= findings remain). Process them one at a time in whatever order; the user may name an order. 2. Re-read the *current* spec, not your memory of it — it may have changed since you wrote it (the user or a linter may have edited it, and pre-agreed decisions may already be encoded in the tracking file). 3. Note any *pre-agreed decisions* the reviewer or user has already settled — in the review's own "Agreed decisions" section, or in the spec's tracking task. These are settled inputs. Don't reopen them; bake them in. @@ -79,15 +79,15 @@ The user resolves the mismatch and re-invokes the workflow. Do not proceed with Read the entire review first. Recommendations interact — an early "medium" finding may be subsumed by a "high" one, or two findings may point at the same edit. Decide dispositions with the whole picture in view, not finding-by-finding as you scroll. -** Phase 2: Decide a disposition for every recommendation +** Phase 2: Decide a disposition for every finding -For each recommendation, choose one: +For each finding, choose one: -- *Accept* — the recommendation is right as written. Plan the edit. -- *Modify* — the recommendation is right in spirit but wrong in detail or scope. Adjust it, and record what you changed and why. -- *Reject* — the recommendation doesn't fit. Record why. +- *Accept* — the finding is right as written. Plan the edit. +- *Modify* — the finding is right in spirit but wrong in detail or scope. Adjust it, and record what you changed and why. +- *Reject* — the finding doesn't fit. Record why. -*Engage critically.* Rubber-stamping is a failure mode. On a strong review most points are accepts, but actively look for the genuine modify/reject cases — they are where your judgment earns its place. Examples from the first run: +*Engage critically.* Rubber-stamping is a failure mode. On a strong review most findings are accepts, but actively look for the genuine modify/reject cases — they are where your judgment earns its place. Examples from the first run: - *Modify:* the review proposed an automatic cache-TTL defcustom. Accepted the goal (fresh data) but deferred TTL to vNext because for a single-user tool an explicit force-refresh + clear-cache command covers it without invalidation complexity. - *Reject:* the review floated a separate =default-issue-filter= defcustom. Rejected as redundant — a fixed default command plus a default-view preference already covered it. @@ -101,8 +101,8 @@ When related specs were reviewed together, two reviews can recommend opposite th ** Phase 4: Update the spec -1. *Weave accepted recommendations into the body.* The spec should read naturally — a new "Selector semantics" section, a revised phase plan, an added test-strategy section — not a list of "review said X so I did Y." The body reflects the decisions; it doesn't narrate them. -2. *Add a bottom "Review dispositions" section* listing only the *modified* and *rejected* recommendations, each with a short reason. Close it with a one-line "everything else accepted as written" so the reader knows the omissions from this section are accepts, not gaps. +1. *Weave accepted findings into the body.* The spec should read naturally — a new "Selector semantics" section, a revised phase plan, an added test-strategy section — not a list of "review said X so I did Y." The body reflects the decisions; it doesn't narrate them. +2. *Complete each finding task in place.* Accept → =DONE=, body noting where it was folded; modify → =DONE=, body noting what you changed and why; reject → =CANCELLED=, body giving the reason. The =[/]= cookie on =* Review findings= tracks progress. The reason on a modified or rejected finding is the durable record — accepted findings are recorded by the body change itself, so they need no separate note. The asymmetry is deliberate. 3. *Update or add a bottom "Review and iteration history" section.* Every response pass gets an entry, even when all findings are accepted. Each entry is an org subheading with a compound id followed by three body fields: Heading format: =YYYY-MM-DD Day @ HH:MM:SS -ZZZZ — Contributor — Role= @@ -113,17 +113,17 @@ When related specs were reviewed together, two reviews can recommend opposite th - *What changed:* compact summary of accepted, modified, and rejected work. - *Why:* the rationale or decision pressure behind the changes. - - *Artifacts:* review filename, disposition section, task IDs, source checks, or commits when useful. + - *Artifacts:* the relevant findings, task IDs, source checks, or commits when useful. 4. *Flip settled decisions to =DONE=.* Each decision the decision-maker has agreed flips its =TODO= to =DONE=; the =[/]= cookie on the =* Decisions= heading tracks the tally. A contested decision stays =TODO= with the back-and-forth under its =*** Discussion= child header. Decisions still =TODO= should be only what genuinely still blocks, each with an owner and a by-when. -5. *Raise the spec to implementation-ready:* consolidate decisions up front, add any implementation prerequisites the review surfaced (e.g. a schema-verification checklist), a consolidated test strategy, and a phased plan ordered so dependencies (like an output model everything depends on) come early. *Gate:* the spec Status cannot move past =draft= to implementation-ready while any decision is still =TODO= — the =[/]= cookie must read complete, or the author consciously accepts and records the risk of building with one open. +5. *Raise the spec to implementation-ready:* consolidate decisions up front, add any implementation prerequisites the review surfaced (e.g. a schema-verification checklist), a consolidated test strategy, and a phased plan ordered so dependencies (like an output model everything depends on) come early. *Gate:* the spec Status cannot move past =draft= to implementation-ready while any decision or any =:blocking:= finding is still =TODO= — both =[/]= cookies must read complete, or the author consciously accepts and records the risk of building with one open. *If this response expanded scope* — folding a finding in added new phases, decisions, or external-dependency assumptions — re-run spec-review's readiness rubric against the *expanded* spec, and file any new gap as a finding or decision before claiming =Ready=. Disposition-completeness gates the *review*; the readiness rubric gates the *spec*. A response can resolve every finding and still be less ready than before, because the answers introduced unproven obligations — the cookies only protect you if the new obligation is actually filed. 6. *Update the status line* to note "review incorporated (<reviewer>, <date>)." ** Phase 5: Close out and iterate -1. *Delete the review file* — only after every recommendation has a disposition. Its deletion is the signal the review is fully processed. -2. *Update tracking* — the spec's VERIFY/task body gets a line noting review incorporated, what changed at a high level, which recommendations were modified (pointing at Review dispositions), and whether it's now implementation-ready pending final go. +1. *Confirm every finding is completed* — the =* Review findings= =[/]= cookie reads complete (every finding =DONE= or =CANCELLED=). The complete cookie is the signal the review is fully processed; there is no file to delete. +2. *Update tracking* — the spec's VERIFY/task body gets a line noting review incorporated, what changed at a high level, which findings were modified or rejected (pointing at the completed findings), and whether it's now implementation-ready pending final go. 3. *Update the session log* (state changed this turn). -4. *Move to the next review file.* Repeat Phases 1-5 until none remain. +4. *Move to the next spec with open findings.* Repeat Phases 1-5 until none remain. 5. *Report* what was accepted-wholesale, what was modified/rejected and why, any cross-spec reconciliations, and the implementation-ready verdict per spec. ** Phase 6: On Ready, build the implementation-task breakdown @@ -150,7 +150,7 @@ The workflow is complete when these tasks exist, the completeness pass confirms Accept, modify, or reject — but never silently drop. The reviewer must be able to account for every point. ** Document the no's, not the yes's -Accepted recommendations live in the spec body (the change *is* the record). Modified and rejected ones need an explicit written reason at the bottom, because the change is invisible and the reasoning would otherwise be lost. The asymmetry is deliberate. +Accepted findings live in the spec body (the change *is* the record). Modified and rejected ones need an explicit written reason on the completed finding task, because the change is invisible and the reasoning would otherwise be lost. The asymmetry is deliberate. ** Critique, don't rubber-stamp A review you accept entirely without finding a single thing to push on probably wasn't read critically. Your judgment — including a well-reasoned no — is the value you add. @@ -164,11 +164,11 @@ When reviews conflict, find the framing where both are right. Silently honoring ** A reject goes back to the reviewer, not just into the file Recording a reasoned reject is the floor, not the close. Communicate the rejection and its reason to the reviewer — a reject is a two-party event, not a unilateral call. If the reviewer disagrees, that's a discussion: weigh the counter, and if you still can't agree, escalate to whoever owns the decision rather than letting the author's "no" stand by default. "I'm not doing that" with no reason the reviewer can engage is the failure mode. (For a tight solo author-reviewer loop this is lightweight; for a team it's the difference between a review and a rubber-stamp-in-reverse.) -** The spec reads forward, the dispositions read backward -The body is written for the implementer (no review archaeology). The dispositions section is written for the reviewer (the reasoning trail). Keep the two audiences separate. +** The spec reads forward, the findings read backward +The body is written for the implementer (no review archaeology). A completed finding's reason is written for the reviewer (the reasoning trail). Keep the two audiences separate. ** The history explains provenance, not implementation behavior -The spec body should still be the implementation contract. The bottom =Review and iteration history= section is for provenance: number of iterations, dates, contributors (including agents), roles, what each pass contributed, and why. Keep it short enough that future readers can understand how decisions evolved without rereading chats, deleted review files, or session logs. +The spec body should still be the implementation contract. The bottom =Review and iteration history= section is for provenance: number of iterations, dates, contributors (including agents), roles, what each pass contributed, and why. Keep it short enough that future readers can understand how decisions evolved without rereading chats or session logs. ** Re-read before editing The spec may have changed since you last saw it. Edit the current file, reconcile against the latest tracking state. @@ -213,3 +213,8 @@ Update this workflow as we learn what works. Capture new disposition patterns, b - *What:* Reconciled this workflow to spec-create's new Decisions convention (each decision is an org =TODO= task that flips to =DONE= on agreement, with a =[/]= cookie on the =* Decisions= heading and a =*** Discussion= child for disputes). Exit Criterion 5, Phase 2's pre-agreed-decisions step, and Phase 4 steps 4-5 now speak in flip-to-=DONE= terms, and the implementation-ready step gates on the all-=DONE= cookie. - *Why:* The convention change landed in spec-create.org via an .emacs.d handoff (originated in its keymap-consolidation spec); this workflow still described the retired =State: proposed | accepted | superseded= model. - *Artifacts:* Handoff =inbox/2026-06-12-1906-from-.emacs.d-spec-create-decisions-todo-note.org=. Paired spec-create.org and spec-review.org edits in the same commit. + +** 2026-06-21 Sun @ 23:16:06 -0400 — Claude Code (rulesets) — responder +- *What:* Folded the review into the spec. Findings are now =* Review findings= =TODO= tasks the responder completes in place (accept/modify → =DONE=, reject → =CANCELLED= with the reason) instead of a "Review dispositions" section; the response is done when the =[/]= cookie reads complete, not when a review file is deleted. Phase 0 finds open work by an incomplete findings cookie; the Phase 4 implementation-ready gate now also requires the findings cookie, and rerun-the-readiness-rubric-on-expanded-scope is folded into that gate (a scope-expanding response must file new obligations as findings or decisions before claiming =Ready=). +- *Why:* Deleting the review file left the iteration-history =Artifacts= line dangling and lost the verbatim review; keeping the file collided with this workflow's file discovery and its "no review files remain" done-condition. Craig's call: incorporate the review into the document, reusing the decisions machinery so the readiness signal is a cookie. The scope-expansion rerun closes a real gap — a response can resolve every finding and still introduce unreviewed obligations. +- *Artifacts:* Paired spec-review.org edits in the same commit. Inbox handoffs =2026-06-20-2339-from-home-spec-response-readiness-gate-proposal.org= and =2026-06-21-0156-from-home-companion-to-tonight-s-spec-response.org=. diff --git a/.ai/workflows/spec-review.org b/.ai/workflows/spec-review.org index d956f00..833dfc9 100644 --- a/.ai/workflows/spec-review.org +++ b/.ai/workflows/spec-review.org @@ -5,9 +5,9 @@ * Overview -The spec-review workflow evaluates a feature/specification document before implementation and decides one thing: can an engineer implement it confidently, test it thoroughly, and ship behavior that matches the user's mental model? If yes, say so and stop. If no, write a review file next to the spec naming every blocking gap and the concrete change that closes it. +The spec-review workflow evaluates a feature/specification document before implementation and decides one thing: can an engineer implement it confidently, test it thoroughly, and ship behavior that matches the user's mental model? If yes, say so and stop. If no, record every blocking gap and the concrete change that closes it as findings in the spec's own =* Review findings= section. -This is the *reviewer* side of a pair. Its counterpart is the spec-response workflow, which the spec's author runs to fold a review back in. The contract between them is the review file: =<spec-basename>-review.org= (e.g. =docs/issue-query-spec.org= → =docs/issue-query-spec-review.org=). spec-review produces it; spec-response consumes it. +This is the *reviewer* side of a pair. Its counterpart is the spec-response workflow, which the spec's author runs to disposition the findings. The contract between them lives *in the spec*: a =* Review findings= section carrying one =TODO= task per finding, with a =[/]= cookie — the same shape the spec's =* Decisions= section already uses. spec-review writes the findings; spec-response completes them. No separate review file is written, so nothing dangles when a review is processed and the full review/response trail stays in the spec. The goal is not to prove the spec is clever. It is to leave the implementer with *fewer* hidden decisions, not more prose. @@ -28,7 +28,7 @@ A review is complete when: 1. *The implementation-readiness gate has been evaluated* and a rubric label assigned (=Ready= / =Ready with caveats= / =Not ready= / =Needs research=). 2. *If ready:* the user is told plainly ("This spec is implementation-ready. I have no further blocking review notes."), and the review stops — no churn for its own sake. -3. *If not ready:* a =<spec>-review.org= file is written next to the spec, in the standard structure, with every finding specific and actionable (current behavior named, risk explained, change recommended, blocking-or-not stated). +3. *If not ready:* findings are recorded in the spec's =* Review findings= section as =TODO= tasks (one per finding, =[/]= cookie on the heading), each specific and actionable (current behavior named, risk explained, change recommended, blocking-or-not stated). 4. *The spec's review history is updated* with who reviewed it, when, which iteration it was, what changed or was recommended, and why. 5. *Deferred work is logged* to =todo.org= (v1 = =[#B]=, vNext/someday = =[#D]=), not left only in chat. 6. *Implementation tasks are enumerated* — the spec's =Implementation phases= section is lifted into a drop-in =todo.org= block (one entry per phase plus a test-surface entry), or, if the spec has no phase decomposition, that gap is raised as a finding. @@ -93,19 +93,19 @@ Mark the spec implementation-ready only if *all* of these hold: - The plan can be phased without shipping broken intermediate states, and phases are small enough to reach a clean stopping point in one focused work session. - External API assumptions are verified or explicitly listed as prerequisites. -If all true → tell the user it's ready and stop unless they ask for more. If any false → continue and write the review file. A "ready" at this phase is provisional; confirm it at Phase 3 after the code read. +If all true → tell the user it's ready and stop unless they ask for more. If any false → continue and record findings (Phase 5). A "ready" at this phase is provisional; confirm it at Phase 3 after the code read. ** Phase 2: Required reading order Never review a spec in isolation. 1. *Read the existing implementation first.* The code paths the spec would touch: public commands and entry points, internal helpers/boundaries, current data representation, persistence/write-back, async/sync, caching, error handling, existing tests, naming/style. Capture current-state facts with function names and file paths. Don't recommend designs that ignore how the package works today. -2. *Read related specs and task tracking.* Companion specs, relevant =todo.org= tasks, README/testing docs, prior review files. Record which tasks the spec absorbs, which stay separate, which decisions are already made, which are still open. +2. *Read related specs and task tracking.* Companion specs, relevant =todo.org= tasks, README/testing docs, prior reviews (in each spec's =* Review findings= and =Review and iteration history=). Record which tasks the spec absorbs, which stay separate, which decisions are already made, which are still open. 3. *Read the target spec end to end — twice.* First for its problem/behavior/phases/assumptions; second looking only for gaps. The second read asks: "What would an implementer still have to invent?" ** Phase 3: Re-run the gate (authoritative) -After reading code and spec, re-run the Phase 1 gate — this is the pass that counts, because now you can actually judge the items that needed the code: architecture fit, API verification, integration points. If now ready, don't manufacture churn. If not, write the review file. +After reading code and spec, re-run the Phase 1 gate — this is the pass that counts, because now you can actually judge the items that needed the code: architecture fit, API verification, integration points. If now ready, don't manufacture churn. If not, record findings (Phase 5). ** Phase 4: Evaluate across dimensions @@ -136,57 +136,30 @@ Work the spec against these. Each is a source of concrete findings, not a box to - *Development tooling.* Does the repo give contributors obvious commands for setup, fast tests, specific tests, compile, lint, coverage, cleanup, slow/manual tests, and release checks? Are optional/live tests gated by explicit environment variables? Is the Makefile/script surface consistent with sibling projects? - *Small enhancement radar.* Are there low-complexity, high-value affordances already provided by the platform that should be surfaced now or explicitly deferred? Examples: archive/compress commands in file managers, built-in history, previews, diagnostics, or doctor commands. Keep the hot path simple; capture the opportunity rather than accidentally losing it. -** Phase 5: Write the review file +** Phase 5: Record findings in the spec -Use this structure for =<spec-basename>-review.org= unless the spec calls for something different: +Findings live in the spec, not a sibling file. Add (or append to) a =* Review findings= section near the spec's =* Decisions= section, with a =[/]= cookie on the heading. Each finding is a =** TODO= task: the heading is the smallest noun phrase naming the gap; the body names current behavior, the risk, and the recommended change. Tag a blocking (high-priority) finding =:blocking:= — it holds the rubric at =Not ready= until dispositioned; leave non-blocking findings untagged. Findings accumulate across review rounds the way decisions do, and the responder completes each one in place (Phase 4 of spec-response), so the section becomes the full review/response trail. #+begin_src org -,#+TITLE: Review: <Spec Title> -,#+AUTHOR: <reviewer> -,#+DATE: <date> -,#+STARTUP: showall - -,* Scope reviewed -What code, tests, docs, and specs you read. - -,* Implementation-readiness -Whether the spec is ready. If not, summarize the blockers. - -,* Overall assessment -The short senior-engineering read: what's right, what's risky, what must be clarified. - -,* High-priority findings -Concrete headings. Each: why it matters and what to change. - -,* Medium-priority findings -Important improvements that shouldn't block all progress. - -,* UX observations -,* Architecture observations -,* Robustness and performance observations -,* Test strategy recommendations -Specific test cases, not generic "add tests". -,* Documentation and tooling recommendations -README/user/developer docs, Makefile/package scripts, coverage, debug tools, and customization surface. - -,* Suggested spec edits -Concrete edits to make the spec implementation-ready. - -,* Agreed decisions -Answers reached during review. Omit if none. - -,* Open questions -Only questions that truly block or materially affect implementation. - -,* vNext candidates -Deferred features to capture in task tracking. +,* Review findings [/] +,** TODO Comment edit-back is undefined :blocking: +The spec says fetched comments render as subheadings but doesn't define whether +editing one syncs back. Linear only lets users edit their own comments. V1 should +treat fetched comments as remote-owned display content and support only adding new +comments; editing own comments can be vNext. (blocking) +,** TODO Empty result and fetch error render identically +A failed fetch and a successful-but-empty fetch produce the same buffer, so the +user can't tell "no issues" from "the query broke." Define a distinct empty-state +message. (non-blocking) #+end_src +Where the old review-file sub-sections go now: the scope-reviewed and overall-assessment narrative goes in the =Review and iteration history= entry (Phase 6); suggested spec edits are the recommended-change line in each finding's body; agreed decisions flip the spec's own =* Decisions= tasks; open questions are =:blocking:= findings or open decisions; vNext candidates are logged to =todo.org= as =[#D]= (Phase 6). The Phase 4 review dimensions are where findings come *from* — not headings to reproduce in the spec. + ** Phase 6: Assign the rubric and update tracking Assign one label consistently: -- =Ready= — no blocking open questions; implementation can start. Requires no decision in the spec's =* Decisions= section to still be =TODO= (the =[/]= cookie reads complete; =SUPERSEDED= and =CANCELLED= count as resolved) — a decision still =TODO= holds the rubric at =Not ready=, or =Ready with caveats= if the author consciously accepts and records the risk. +- =Ready= — no blocking open questions; implementation can start. Requires both cookies complete: no decision in =* Decisions= and no =:blocking:= finding in =* Review findings= still =TODO= (the =[/]= cookies read complete; =SUPERSEDED=/=CANCELLED= and a completed or rejected finding count as resolved) — a still-=TODO= decision or =:blocking:= finding holds the rubric at =Not ready=, or =Ready with caveats= if the author consciously accepts and records the risk. A non-blocking finding left =TODO= is author's discretion and does not hold the rubric. - =Ready with caveats= — can start if the caveats are accepted and tracked. - =Not ready= — blocking ambiguity / missing decisions would force implementers to invent product behavior. - =Needs research= — external API/library/platform assumptions must be verified first. @@ -195,7 +168,7 @@ The most useful reviews move a spec from =Not ready= to =Ready with caveats= or Finding severity maps to blocking power: *high-priority findings block =Ready=* — they hold the rubric at =Not ready= (or =Ready with caveats= if the author accepts and tracks them) until dispositioned; *medium-priority findings are the author's discretion* and don't block. State the blocking status on each finding so the author running spec-response knows which ones gate the rubric. -Then update the spec's review history. Specs should carry a bottom section named =Review and iteration history= (or the nearest existing equivalent) that tracks each material author/reviewer pass. Add a concise entry for this review even when the spec is ready and no review file is written. +Then update the spec's review history. Specs should carry a bottom section named =Review and iteration history= (or the nearest existing equivalent) that tracks each material author/reviewer pass. Add a concise entry for this review even when the spec is ready and no findings are recorded. Each entry is an org subheading with a compound id followed by three body fields. @@ -207,27 +180,11 @@ Body fields: - *What changed or was recommended:* high-signal summary, not a duplicate of the whole review. - *Why:* the decision pressure or rationale that caused the contribution. -- *Artifacts:* links to the review file, response/disposition section, commits, task IDs, or source checks when useful. +- *Artifacts:* links to the relevant findings, commits, task IDs, or source checks when useful. If the spec has no such section, add it at the bottom. Keep the history short and cumulative; it is provenance for future readers, not a session transcript. -*Emit implementation tasks (drop-in for =todo.org=).* Read the spec's =Implementation phases= section and turn it into a paste-ready block in the review file, under a heading =Implementation tasks (drop-in for todo.org)=. One =** TODO= entry per phase, plus a final entry for the test surface. The point: the handoff to whoever implements is one paste, not a re-read of the spec, and a spec that can't be decomposed into phases fails this step, surfacing a shape problem before =Ready=. - -Per-phase entry, following =todo-format.md= (terse heading names the phase; body holds the one-line deliverable plus a pointer back to the spec; tags on the heading): - -#+begin_example -** TODO [#B] <phase name — smallest noun phrase> :feature: -<what this phase delivers, one line>. Spec: [[file:<spec path>]] (Implementation phases, phase N). -#+end_example - -Final test-surface entry, mirroring the spec's =Acceptance criteria= when present: - -#+begin_example -** TODO [#B] <feature> — test surface :test: -Unit: <...>. Integration: <...>. E2e / manual-verify: <acceptance criteria as checkable items>. Spec: [[file:<spec path>]] (Acceptance criteria). -#+end_example - -Priority and tags follow the deferred-work rule below. Emit the block in the review file; the author pastes it into =todo.org= during spec-response, or you log it directly when you're also closing the loop. If the spec has no =Implementation phases= section, don't invent one — that absence is the finding, and the step becomes the prompt to ask the author to add a phase decomposition before the spec can be =Ready=. +*Check the spec decomposes into phases.* A =Ready= spec needs an =Implementation phases= section an implementer can turn into one task per phase plus a test surface. Confirm it's present and decomposable — each phase small enough to reach a clean stopping point in one focused session, with no broken intermediate states. If it's missing or can't be phased, file that as a =:blocking:= finding; don't invent the phases. The phase-to-task breakdown itself is spec-response's job (its Phase 6 reads =Implementation phases= directly once the author confirms =Ready=); the reviewer only verifies the section exists and is sound. Then log deferred work to =todo.org=: v1 implementation = =[#B]= (unless urgent or speculative); vNext/someday = =[#D]=. Tag =:feature:= / =:bug:= / =:refactor:= / =:test:= / =:quick:= / =:solo:= only when accurate. Don't leave important deferred decisions only in chat. @@ -256,8 +213,11 @@ Every material comment should be tagged by force: blocking, should-fix, or optio ** Make feedback author-usable Review comments should be specific, neutral, and actionable: quote or name the spec behavior, explain the risk, recommend the smallest concrete change, and say how the author can verify the fix. Avoid personal language, rhetorical questions, vague "this needs work" comments, and comments that require the author to infer the desired edit. +** Keep review and response roles explicit +If the user asks for review plus "enhance the spec" in the same turn, produce the findings first. Make only low-risk provenance and tracking edits unless the user clearly wants the reviewer to respond too. Don't silently resolve product decisions on the author's behalf — a proposed default belongs in a finding until it's accepted, modified, or rejected. + ** Preserve iteration provenance -Future reviewers and implementers need to know not just the current decision, but how the spec got there: how many review/response loops happened, who contributed, what they changed or recommended, and why. Keep that record in the spec itself under =Review and iteration history= so the trail survives deleted review files, chat loss, and agent handoffs. +Future reviewers and implementers need to know not just the current decision, but how the spec got there: how many review/response loops happened, who contributed, what they changed or recommended, and why. Keep that record in the spec itself under =Review and iteration history= so the trail survives chat loss and agent handoffs. ** Be strict about ownership Especially for org-mode features: a user treats visible text as editable unless the representation says otherwise. Make generated-vs-editable explicit. @@ -265,6 +225,9 @@ Especially for org-mode features: a user treats visible text as editable unless ** Never depend on an unverified API shape If the spec assumes fields/mutations/enums, they're verified against current schema/docs/live responses, or listed as a research prerequisite. =Needs research= is a real, useful verdict. +** Source external-dependency checks in the finding +When a finding turns on a current external-dependency fact (release version, API capability, platform behavior, package availability, hosted-service terms), cite the checked source in the finding body. Stale dependency assumptions are common, and the next reviewer needs to tell "verified this pass" from "remembered from prior context." + ** Favor small pure cores and thin IO layers Push findings toward separable, unit-testable pure functions surrounded by thin command/transport layers. @@ -354,3 +317,8 @@ Sources: - *What:* Two refinements to the same-day decisions convention after Craig's review: the gate item and =Ready= rubric now read "no decision is still =TODO=" with =SUPERSEDED= and =CANCELLED= counting as resolved (spec-create's template defines them as done-class keywords via a =#+TODO:= header), and a spec still on the retired =State:= field model explicitly fails the gate item until converted — closing the vacuous-pass hole on old specs. - *Why:* Review of the freshly-landed convention flagged that TODO/DONE alone lost the old model's superseded state and that the gate as written would silently pass a spec with no decision tasks at all. Craig chose the two done-class keywords and the auto-added =#+TODO:= header (the in-file header is what makes custom keywords portable). - *Artifacts:* Paired spec-create.org edits (keyword scheme + template header) in the same commit. + +** 2026-06-21 Sun @ 23:16:06 -0400 — Claude Code (rulesets) — responder +- *What:* Moved findings from a sibling =<spec>-review.org= file into the spec itself. Findings are now =** TODO= tasks under a =* Review findings= section with a =[/]= cookie, mirroring =* Decisions=; =:blocking:= marks high-priority. Phase 5 records findings in the spec instead of writing a review file; the Phase 6 =Ready= rubric gates on both the decisions and the findings cookie; the implementation-task drop-in (which lived in the review file) is gone, leaving the reviewer to verify the spec decomposes into phases and spec-response to build the breakdown. Also added two reviewer-practice principles harvested from a home spec-review: keep review and response roles explicit, and source external-dependency checks in the finding. +- *Why:* The delete-the-review-file convention 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. Craig's call: incorporate the review into the document, reusing the decisions machinery so the readiness signal is a cookie, not a file's presence or absence. The role-explicit and source-checking practices came in from the home finance-report spec via inbox handoffs. +- *Artifacts:* Paired spec-response.org edits in the same commit. Inbox handoffs =2026-06-20-2339-from-home-spec-response-readiness-gate-proposal.org=, =2026-06-21-0156-from-home-companion-to-tonight-s-spec-response.org=, and the home-edited =2026-06-21-0156-from-home-spec-review.org=. diff --git a/claude-templates/.ai/workflows/INDEX.org b/claude-templates/.ai/workflows/INDEX.org index a45807e..5ae8480 100644 --- a/claude-templates/.ai/workflows/INDEX.org +++ b/claude-templates/.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 diff --git a/claude-templates/.ai/workflows/spec-create.org b/claude-templates/.ai/workflows/spec-create.org index f90c511..508b969 100644 --- a/claude-templates/.ai/workflows/spec-create.org +++ b/claude-templates/.ai/workflows/spec-create.org @@ -10,7 +10,7 @@ The guiding principle, drawn from how Google, Oxide, Amazon, Basecamp, and the A It is the front of a trio: - =spec-create.org= (this one) — author writes the spec. -- =spec-review.org= — a reviewer gates the spec for implementation-readiness and writes =<spec-basename>-review.org=. +- =spec-review.org= — a reviewer gates the spec for implementation-readiness and records findings in the spec's =* Review findings= section. - =spec-response.org= — the author folds the review back in. The spec this workflow produces has to *pass spec-review's gate* — that gate is the definition of done. So the structure below is built to answer the reviewer's questions up front. Keep it lightweight anyway: a short required spine plus a *readiness-dimensions menu* where each item is either answered or explicitly marked "N/A because…". The best spec is the shortest one that still lets an engineer build it, test it, and ship behavior that matches the user's mental model. @@ -59,7 +59,7 @@ Capture, in this order: This is where the spec earns a "Ready" from review: an engineer must be able to build it in steps, know when it's done, and never have to invent product behavior mid-implementation. -1. *Implementation phases* — decompose the work into phases each small enough to finish in one focused session and each leaving the tree in a working (not half-broken) state. =spec-review= lifts this section straight into =todo.org= tasks, so a spec that can't be phased fails the gate — the absence is itself a finding. +1. *Implementation phases* — decompose the work into phases each small enough to finish in one focused session and each leaving the tree in a working (not half-broken) state. =spec-review= checks this section decomposes cleanly and =spec-response= lifts it into =todo.org= tasks, so a spec that can't be phased fails the gate — the absence is itself a finding. 2. *Acceptance criteria* — the observable conditions that mean the feature works, written as checkable items. The review's test-surface task mirrors these. 3. *Readiness dimensions* — walk this menu and, for each, either define the behavior or write "N/A because…". The escape hatch keeps a simple spec short; the prompt keeps a hidden decision from slipping into implementation: - *Data model & ownership* — what's user-authored / generated / cached / remote; who owns each editable region; what persists vs refreshes. diff --git a/claude-templates/.ai/workflows/spec-response.org b/claude-templates/.ai/workflows/spec-response.org index 2686cf8..de5b1c8 100644 --- a/claude-templates/.ai/workflows/spec-response.org +++ b/claude-templates/.ai/workflows/spec-response.org @@ -5,9 +5,9 @@ * Overview -The spec-response workflow processes external reviews of a design spec and folds them into the spec until it is implementation-ready. A reviewer (human or another agent) leaves a review file next to the spec — typically produced by its counterpart, the *spec-review* workflow, which writes =<spec-basename>-review.org= and assigns a readiness rubric. Claude works through every recommendation, deciding accept / modify / reject for each, updates the spec for the accepted ones, documents the modified and rejected ones with reasons, then deletes the review file. Repeat for each spec under review. +The spec-response workflow processes a review's findings and folds them into the spec until it is implementation-ready. A reviewer (human or another agent) records findings in the spec's =* Review findings= section — typically via its counterpart, the *spec-review* workflow, which writes one =TODO= task per finding (=[/]= cookie on the heading) and assigns a readiness rubric. Claude works through every finding, deciding accept / modify / reject, updates the spec body for the accepted ones, and completes each finding task in place: accept and modify finish =DONE= (the modify's change noted in the body), reject finishes =CANCELLED= with the reason. Repeat for each spec under review. -The output is a spec a reader could implement from, plus a durable record — inside the spec — of why any recommendation was changed or declined, so the reviewer can find the reasoning later without re-litigating. +The output is a spec a reader could implement from, plus a durable record — inside the spec — of why any finding was changed or declined, so the reviewer can find the reasoning later without re-litigating. The reasoning lives on the completed finding task, not a separate file. This workflow was first run on 2026-05-23 against the linear-emacs =issue-query-spec.org= and =issue-representation-spec.org= reviews, and written up from that run. @@ -27,25 +27,25 @@ A review is only useful if every point in it gets a decision. Without a defined A spec's review is fully processed when: -1. *Every recommendation has an explicit disposition* — accepted, modified, or rejected. None dropped. -2. *Accepted recommendations are woven into the spec body* — the spec reads as if they were always there, not appended as a changelog. -3. *Modified and rejected recommendations are documented in a bottom section* (e.g. "Review dispositions") with a one-paragraph reason each, so the reviewer can find the reasoning. +1. *Every finding has an explicit disposition* — accepted, modified, or rejected, and its task completed (=DONE= or =CANCELLED=). None dropped. +2. *Accepted findings are woven into the spec body* — the spec reads as if they were always there, not appended as a changelog. +3. *Modified and rejected findings carry a one-paragraph reason in the completed task's body*, so the reviewer can find the reasoning. 4. *Review/response provenance is documented in the spec* — iteration count/date, contributor, role, what changed, and why. 5. *Pre-agreed decisions are flipped to =DONE=* — each settled decision's =TODO= becomes =DONE=, and the =[/]= cookie on the spec's =* Decisions= heading reflects the tally. 6. *Cross-spec tensions are reconciled in writing* when related specs were reviewed together. -7. *The review file is deleted* once 1-6 hold. +7. *Every finding task is completed* — the =* Review findings= =[/]= cookie reads complete (each finding =DONE= or =CANCELLED=). 8. *Tracking is updated* — the spec's VERIFY/task body notes "review incorporated" and whether it's implementation-ready. 9. *Implementation tasks exist* — once the author confirms the spec is Ready, the project's =todo.org= carries the full implementation-task breakdown (Phase 6), reviewed for completeness, with =:solo:= marked and a Manual-testing task for everything else. -The whole run is done when no =*-review.org= files remain and each spec is judged implementation-ready (or its remaining blockers are named). +The whole run is done when every spec's =* Review findings= cookie reads complete and each spec is judged implementation-ready (or its remaining blockers are named). -*Measurable validation:* a reader scanning the review against the revised spec can find, for every review point, either the change in the body or its disposition at the bottom. Nothing is unaccounted for. +*Measurable validation:* a reader scanning the spec can find, for every finding, either the change in the body or its disposition on the completed finding task. Nothing is unaccounted for. * When to Use This Workflow Trigger when: -- A reviewer drops a review file alongside a spec — convention: same basename with a =-review.org= suffix (=foo.org= → =foo-review.org=). +- A reviewer records findings in the spec's =* Review findings= section — typically via the spec-review workflow. - Craig says "respond to the review" / "let's run the spec-response workflow" / "process the spec reviews." - Any time a spec needs to absorb structured external feedback and converge to implementation-ready. @@ -63,7 +63,7 @@ the file should be renamed first. Spec workflows require the -spec.org suffix as guard against pointing the workflow at tutorial, inventory, or setup docs. #+end_example -The review file the response consumes follows the convention =<spec-basename>-review.org=, so a misnamed spec produces a mis-pointed review file too. Fix the spec name first. +The findings the response consumes live in the spec's own =* Review findings= section, so the spec filename is the handle the workflow keys on — point it at the right =-spec.org= file. Fix the spec name first. The user resolves the mismatch and re-invokes the workflow. Do not proceed with the response against a misnamed spec. @@ -71,7 +71,7 @@ The user resolves the mismatch and re-invokes the workflow. Do not proceed with ** Phase 0: Orient -1. List the review files (=ls docs/*-review.org= or wherever they live). Process them one at a time in whatever order; the user may name an order. +1. Find specs with open findings — a =* Review findings= section whose =[/]= cookie isn't complete (=TODO= findings remain). Process them one at a time in whatever order; the user may name an order. 2. Re-read the *current* spec, not your memory of it — it may have changed since you wrote it (the user or a linter may have edited it, and pre-agreed decisions may already be encoded in the tracking file). 3. Note any *pre-agreed decisions* the reviewer or user has already settled — in the review's own "Agreed decisions" section, or in the spec's tracking task. These are settled inputs. Don't reopen them; bake them in. @@ -79,15 +79,15 @@ The user resolves the mismatch and re-invokes the workflow. Do not proceed with Read the entire review first. Recommendations interact — an early "medium" finding may be subsumed by a "high" one, or two findings may point at the same edit. Decide dispositions with the whole picture in view, not finding-by-finding as you scroll. -** Phase 2: Decide a disposition for every recommendation +** Phase 2: Decide a disposition for every finding -For each recommendation, choose one: +For each finding, choose one: -- *Accept* — the recommendation is right as written. Plan the edit. -- *Modify* — the recommendation is right in spirit but wrong in detail or scope. Adjust it, and record what you changed and why. -- *Reject* — the recommendation doesn't fit. Record why. +- *Accept* — the finding is right as written. Plan the edit. +- *Modify* — the finding is right in spirit but wrong in detail or scope. Adjust it, and record what you changed and why. +- *Reject* — the finding doesn't fit. Record why. -*Engage critically.* Rubber-stamping is a failure mode. On a strong review most points are accepts, but actively look for the genuine modify/reject cases — they are where your judgment earns its place. Examples from the first run: +*Engage critically.* Rubber-stamping is a failure mode. On a strong review most findings are accepts, but actively look for the genuine modify/reject cases — they are where your judgment earns its place. Examples from the first run: - *Modify:* the review proposed an automatic cache-TTL defcustom. Accepted the goal (fresh data) but deferred TTL to vNext because for a single-user tool an explicit force-refresh + clear-cache command covers it without invalidation complexity. - *Reject:* the review floated a separate =default-issue-filter= defcustom. Rejected as redundant — a fixed default command plus a default-view preference already covered it. @@ -101,8 +101,8 @@ When related specs were reviewed together, two reviews can recommend opposite th ** Phase 4: Update the spec -1. *Weave accepted recommendations into the body.* The spec should read naturally — a new "Selector semantics" section, a revised phase plan, an added test-strategy section — not a list of "review said X so I did Y." The body reflects the decisions; it doesn't narrate them. -2. *Add a bottom "Review dispositions" section* listing only the *modified* and *rejected* recommendations, each with a short reason. Close it with a one-line "everything else accepted as written" so the reader knows the omissions from this section are accepts, not gaps. +1. *Weave accepted findings into the body.* The spec should read naturally — a new "Selector semantics" section, a revised phase plan, an added test-strategy section — not a list of "review said X so I did Y." The body reflects the decisions; it doesn't narrate them. +2. *Complete each finding task in place.* Accept → =DONE=, body noting where it was folded; modify → =DONE=, body noting what you changed and why; reject → =CANCELLED=, body giving the reason. The =[/]= cookie on =* Review findings= tracks progress. The reason on a modified or rejected finding is the durable record — accepted findings are recorded by the body change itself, so they need no separate note. The asymmetry is deliberate. 3. *Update or add a bottom "Review and iteration history" section.* Every response pass gets an entry, even when all findings are accepted. Each entry is an org subheading with a compound id followed by three body fields: Heading format: =YYYY-MM-DD Day @ HH:MM:SS -ZZZZ — Contributor — Role= @@ -113,17 +113,17 @@ When related specs were reviewed together, two reviews can recommend opposite th - *What changed:* compact summary of accepted, modified, and rejected work. - *Why:* the rationale or decision pressure behind the changes. - - *Artifacts:* review filename, disposition section, task IDs, source checks, or commits when useful. + - *Artifacts:* the relevant findings, task IDs, source checks, or commits when useful. 4. *Flip settled decisions to =DONE=.* Each decision the decision-maker has agreed flips its =TODO= to =DONE=; the =[/]= cookie on the =* Decisions= heading tracks the tally. A contested decision stays =TODO= with the back-and-forth under its =*** Discussion= child header. Decisions still =TODO= should be only what genuinely still blocks, each with an owner and a by-when. -5. *Raise the spec to implementation-ready:* consolidate decisions up front, add any implementation prerequisites the review surfaced (e.g. a schema-verification checklist), a consolidated test strategy, and a phased plan ordered so dependencies (like an output model everything depends on) come early. *Gate:* the spec Status cannot move past =draft= to implementation-ready while any decision is still =TODO= — the =[/]= cookie must read complete, or the author consciously accepts and records the risk of building with one open. +5. *Raise the spec to implementation-ready:* consolidate decisions up front, add any implementation prerequisites the review surfaced (e.g. a schema-verification checklist), a consolidated test strategy, and a phased plan ordered so dependencies (like an output model everything depends on) come early. *Gate:* the spec Status cannot move past =draft= to implementation-ready while any decision or any =:blocking:= finding is still =TODO= — both =[/]= cookies must read complete, or the author consciously accepts and records the risk of building with one open. *If this response expanded scope* — folding a finding in added new phases, decisions, or external-dependency assumptions — re-run spec-review's readiness rubric against the *expanded* spec, and file any new gap as a finding or decision before claiming =Ready=. Disposition-completeness gates the *review*; the readiness rubric gates the *spec*. A response can resolve every finding and still be less ready than before, because the answers introduced unproven obligations — the cookies only protect you if the new obligation is actually filed. 6. *Update the status line* to note "review incorporated (<reviewer>, <date>)." ** Phase 5: Close out and iterate -1. *Delete the review file* — only after every recommendation has a disposition. Its deletion is the signal the review is fully processed. -2. *Update tracking* — the spec's VERIFY/task body gets a line noting review incorporated, what changed at a high level, which recommendations were modified (pointing at Review dispositions), and whether it's now implementation-ready pending final go. +1. *Confirm every finding is completed* — the =* Review findings= =[/]= cookie reads complete (every finding =DONE= or =CANCELLED=). The complete cookie is the signal the review is fully processed; there is no file to delete. +2. *Update tracking* — the spec's VERIFY/task body gets a line noting review incorporated, what changed at a high level, which findings were modified or rejected (pointing at the completed findings), and whether it's now implementation-ready pending final go. 3. *Update the session log* (state changed this turn). -4. *Move to the next review file.* Repeat Phases 1-5 until none remain. +4. *Move to the next spec with open findings.* Repeat Phases 1-5 until none remain. 5. *Report* what was accepted-wholesale, what was modified/rejected and why, any cross-spec reconciliations, and the implementation-ready verdict per spec. ** Phase 6: On Ready, build the implementation-task breakdown @@ -150,7 +150,7 @@ The workflow is complete when these tasks exist, the completeness pass confirms Accept, modify, or reject — but never silently drop. The reviewer must be able to account for every point. ** Document the no's, not the yes's -Accepted recommendations live in the spec body (the change *is* the record). Modified and rejected ones need an explicit written reason at the bottom, because the change is invisible and the reasoning would otherwise be lost. The asymmetry is deliberate. +Accepted findings live in the spec body (the change *is* the record). Modified and rejected ones need an explicit written reason on the completed finding task, because the change is invisible and the reasoning would otherwise be lost. The asymmetry is deliberate. ** Critique, don't rubber-stamp A review you accept entirely without finding a single thing to push on probably wasn't read critically. Your judgment — including a well-reasoned no — is the value you add. @@ -164,11 +164,11 @@ When reviews conflict, find the framing where both are right. Silently honoring ** A reject goes back to the reviewer, not just into the file Recording a reasoned reject is the floor, not the close. Communicate the rejection and its reason to the reviewer — a reject is a two-party event, not a unilateral call. If the reviewer disagrees, that's a discussion: weigh the counter, and if you still can't agree, escalate to whoever owns the decision rather than letting the author's "no" stand by default. "I'm not doing that" with no reason the reviewer can engage is the failure mode. (For a tight solo author-reviewer loop this is lightweight; for a team it's the difference between a review and a rubber-stamp-in-reverse.) -** The spec reads forward, the dispositions read backward -The body is written for the implementer (no review archaeology). The dispositions section is written for the reviewer (the reasoning trail). Keep the two audiences separate. +** The spec reads forward, the findings read backward +The body is written for the implementer (no review archaeology). A completed finding's reason is written for the reviewer (the reasoning trail). Keep the two audiences separate. ** The history explains provenance, not implementation behavior -The spec body should still be the implementation contract. The bottom =Review and iteration history= section is for provenance: number of iterations, dates, contributors (including agents), roles, what each pass contributed, and why. Keep it short enough that future readers can understand how decisions evolved without rereading chats, deleted review files, or session logs. +The spec body should still be the implementation contract. The bottom =Review and iteration history= section is for provenance: number of iterations, dates, contributors (including agents), roles, what each pass contributed, and why. Keep it short enough that future readers can understand how decisions evolved without rereading chats or session logs. ** Re-read before editing The spec may have changed since you last saw it. Edit the current file, reconcile against the latest tracking state. @@ -213,3 +213,8 @@ Update this workflow as we learn what works. Capture new disposition patterns, b - *What:* Reconciled this workflow to spec-create's new Decisions convention (each decision is an org =TODO= task that flips to =DONE= on agreement, with a =[/]= cookie on the =* Decisions= heading and a =*** Discussion= child for disputes). Exit Criterion 5, Phase 2's pre-agreed-decisions step, and Phase 4 steps 4-5 now speak in flip-to-=DONE= terms, and the implementation-ready step gates on the all-=DONE= cookie. - *Why:* The convention change landed in spec-create.org via an .emacs.d handoff (originated in its keymap-consolidation spec); this workflow still described the retired =State: proposed | accepted | superseded= model. - *Artifacts:* Handoff =inbox/2026-06-12-1906-from-.emacs.d-spec-create-decisions-todo-note.org=. Paired spec-create.org and spec-review.org edits in the same commit. + +** 2026-06-21 Sun @ 23:16:06 -0400 — Claude Code (rulesets) — responder +- *What:* Folded the review into the spec. Findings are now =* Review findings= =TODO= tasks the responder completes in place (accept/modify → =DONE=, reject → =CANCELLED= with the reason) instead of a "Review dispositions" section; the response is done when the =[/]= cookie reads complete, not when a review file is deleted. Phase 0 finds open work by an incomplete findings cookie; the Phase 4 implementation-ready gate now also requires the findings cookie, and rerun-the-readiness-rubric-on-expanded-scope is folded into that gate (a scope-expanding response must file new obligations as findings or decisions before claiming =Ready=). +- *Why:* Deleting the review file left the iteration-history =Artifacts= line dangling and lost the verbatim review; keeping the file collided with this workflow's file discovery and its "no review files remain" done-condition. Craig's call: incorporate the review into the document, reusing the decisions machinery so the readiness signal is a cookie. The scope-expansion rerun closes a real gap — a response can resolve every finding and still introduce unreviewed obligations. +- *Artifacts:* Paired spec-review.org edits in the same commit. Inbox handoffs =2026-06-20-2339-from-home-spec-response-readiness-gate-proposal.org= and =2026-06-21-0156-from-home-companion-to-tonight-s-spec-response.org=. diff --git a/claude-templates/.ai/workflows/spec-review.org b/claude-templates/.ai/workflows/spec-review.org index d956f00..833dfc9 100644 --- a/claude-templates/.ai/workflows/spec-review.org +++ b/claude-templates/.ai/workflows/spec-review.org @@ -5,9 +5,9 @@ * Overview -The spec-review workflow evaluates a feature/specification document before implementation and decides one thing: can an engineer implement it confidently, test it thoroughly, and ship behavior that matches the user's mental model? If yes, say so and stop. If no, write a review file next to the spec naming every blocking gap and the concrete change that closes it. +The spec-review workflow evaluates a feature/specification document before implementation and decides one thing: can an engineer implement it confidently, test it thoroughly, and ship behavior that matches the user's mental model? If yes, say so and stop. If no, record every blocking gap and the concrete change that closes it as findings in the spec's own =* Review findings= section. -This is the *reviewer* side of a pair. Its counterpart is the spec-response workflow, which the spec's author runs to fold a review back in. The contract between them is the review file: =<spec-basename>-review.org= (e.g. =docs/issue-query-spec.org= → =docs/issue-query-spec-review.org=). spec-review produces it; spec-response consumes it. +This is the *reviewer* side of a pair. Its counterpart is the spec-response workflow, which the spec's author runs to disposition the findings. The contract between them lives *in the spec*: a =* Review findings= section carrying one =TODO= task per finding, with a =[/]= cookie — the same shape the spec's =* Decisions= section already uses. spec-review writes the findings; spec-response completes them. No separate review file is written, so nothing dangles when a review is processed and the full review/response trail stays in the spec. The goal is not to prove the spec is clever. It is to leave the implementer with *fewer* hidden decisions, not more prose. @@ -28,7 +28,7 @@ A review is complete when: 1. *The implementation-readiness gate has been evaluated* and a rubric label assigned (=Ready= / =Ready with caveats= / =Not ready= / =Needs research=). 2. *If ready:* the user is told plainly ("This spec is implementation-ready. I have no further blocking review notes."), and the review stops — no churn for its own sake. -3. *If not ready:* a =<spec>-review.org= file is written next to the spec, in the standard structure, with every finding specific and actionable (current behavior named, risk explained, change recommended, blocking-or-not stated). +3. *If not ready:* findings are recorded in the spec's =* Review findings= section as =TODO= tasks (one per finding, =[/]= cookie on the heading), each specific and actionable (current behavior named, risk explained, change recommended, blocking-or-not stated). 4. *The spec's review history is updated* with who reviewed it, when, which iteration it was, what changed or was recommended, and why. 5. *Deferred work is logged* to =todo.org= (v1 = =[#B]=, vNext/someday = =[#D]=), not left only in chat. 6. *Implementation tasks are enumerated* — the spec's =Implementation phases= section is lifted into a drop-in =todo.org= block (one entry per phase plus a test-surface entry), or, if the spec has no phase decomposition, that gap is raised as a finding. @@ -93,19 +93,19 @@ Mark the spec implementation-ready only if *all* of these hold: - The plan can be phased without shipping broken intermediate states, and phases are small enough to reach a clean stopping point in one focused work session. - External API assumptions are verified or explicitly listed as prerequisites. -If all true → tell the user it's ready and stop unless they ask for more. If any false → continue and write the review file. A "ready" at this phase is provisional; confirm it at Phase 3 after the code read. +If all true → tell the user it's ready and stop unless they ask for more. If any false → continue and record findings (Phase 5). A "ready" at this phase is provisional; confirm it at Phase 3 after the code read. ** Phase 2: Required reading order Never review a spec in isolation. 1. *Read the existing implementation first.* The code paths the spec would touch: public commands and entry points, internal helpers/boundaries, current data representation, persistence/write-back, async/sync, caching, error handling, existing tests, naming/style. Capture current-state facts with function names and file paths. Don't recommend designs that ignore how the package works today. -2. *Read related specs and task tracking.* Companion specs, relevant =todo.org= tasks, README/testing docs, prior review files. Record which tasks the spec absorbs, which stay separate, which decisions are already made, which are still open. +2. *Read related specs and task tracking.* Companion specs, relevant =todo.org= tasks, README/testing docs, prior reviews (in each spec's =* Review findings= and =Review and iteration history=). Record which tasks the spec absorbs, which stay separate, which decisions are already made, which are still open. 3. *Read the target spec end to end — twice.* First for its problem/behavior/phases/assumptions; second looking only for gaps. The second read asks: "What would an implementer still have to invent?" ** Phase 3: Re-run the gate (authoritative) -After reading code and spec, re-run the Phase 1 gate — this is the pass that counts, because now you can actually judge the items that needed the code: architecture fit, API verification, integration points. If now ready, don't manufacture churn. If not, write the review file. +After reading code and spec, re-run the Phase 1 gate — this is the pass that counts, because now you can actually judge the items that needed the code: architecture fit, API verification, integration points. If now ready, don't manufacture churn. If not, record findings (Phase 5). ** Phase 4: Evaluate across dimensions @@ -136,57 +136,30 @@ Work the spec against these. Each is a source of concrete findings, not a box to - *Development tooling.* Does the repo give contributors obvious commands for setup, fast tests, specific tests, compile, lint, coverage, cleanup, slow/manual tests, and release checks? Are optional/live tests gated by explicit environment variables? Is the Makefile/script surface consistent with sibling projects? - *Small enhancement radar.* Are there low-complexity, high-value affordances already provided by the platform that should be surfaced now or explicitly deferred? Examples: archive/compress commands in file managers, built-in history, previews, diagnostics, or doctor commands. Keep the hot path simple; capture the opportunity rather than accidentally losing it. -** Phase 5: Write the review file +** Phase 5: Record findings in the spec -Use this structure for =<spec-basename>-review.org= unless the spec calls for something different: +Findings live in the spec, not a sibling file. Add (or append to) a =* Review findings= section near the spec's =* Decisions= section, with a =[/]= cookie on the heading. Each finding is a =** TODO= task: the heading is the smallest noun phrase naming the gap; the body names current behavior, the risk, and the recommended change. Tag a blocking (high-priority) finding =:blocking:= — it holds the rubric at =Not ready= until dispositioned; leave non-blocking findings untagged. Findings accumulate across review rounds the way decisions do, and the responder completes each one in place (Phase 4 of spec-response), so the section becomes the full review/response trail. #+begin_src org -,#+TITLE: Review: <Spec Title> -,#+AUTHOR: <reviewer> -,#+DATE: <date> -,#+STARTUP: showall - -,* Scope reviewed -What code, tests, docs, and specs you read. - -,* Implementation-readiness -Whether the spec is ready. If not, summarize the blockers. - -,* Overall assessment -The short senior-engineering read: what's right, what's risky, what must be clarified. - -,* High-priority findings -Concrete headings. Each: why it matters and what to change. - -,* Medium-priority findings -Important improvements that shouldn't block all progress. - -,* UX observations -,* Architecture observations -,* Robustness and performance observations -,* Test strategy recommendations -Specific test cases, not generic "add tests". -,* Documentation and tooling recommendations -README/user/developer docs, Makefile/package scripts, coverage, debug tools, and customization surface. - -,* Suggested spec edits -Concrete edits to make the spec implementation-ready. - -,* Agreed decisions -Answers reached during review. Omit if none. - -,* Open questions -Only questions that truly block or materially affect implementation. - -,* vNext candidates -Deferred features to capture in task tracking. +,* Review findings [/] +,** TODO Comment edit-back is undefined :blocking: +The spec says fetched comments render as subheadings but doesn't define whether +editing one syncs back. Linear only lets users edit their own comments. V1 should +treat fetched comments as remote-owned display content and support only adding new +comments; editing own comments can be vNext. (blocking) +,** TODO Empty result and fetch error render identically +A failed fetch and a successful-but-empty fetch produce the same buffer, so the +user can't tell "no issues" from "the query broke." Define a distinct empty-state +message. (non-blocking) #+end_src +Where the old review-file sub-sections go now: the scope-reviewed and overall-assessment narrative goes in the =Review and iteration history= entry (Phase 6); suggested spec edits are the recommended-change line in each finding's body; agreed decisions flip the spec's own =* Decisions= tasks; open questions are =:blocking:= findings or open decisions; vNext candidates are logged to =todo.org= as =[#D]= (Phase 6). The Phase 4 review dimensions are where findings come *from* — not headings to reproduce in the spec. + ** Phase 6: Assign the rubric and update tracking Assign one label consistently: -- =Ready= — no blocking open questions; implementation can start. Requires no decision in the spec's =* Decisions= section to still be =TODO= (the =[/]= cookie reads complete; =SUPERSEDED= and =CANCELLED= count as resolved) — a decision still =TODO= holds the rubric at =Not ready=, or =Ready with caveats= if the author consciously accepts and records the risk. +- =Ready= — no blocking open questions; implementation can start. Requires both cookies complete: no decision in =* Decisions= and no =:blocking:= finding in =* Review findings= still =TODO= (the =[/]= cookies read complete; =SUPERSEDED=/=CANCELLED= and a completed or rejected finding count as resolved) — a still-=TODO= decision or =:blocking:= finding holds the rubric at =Not ready=, or =Ready with caveats= if the author consciously accepts and records the risk. A non-blocking finding left =TODO= is author's discretion and does not hold the rubric. - =Ready with caveats= — can start if the caveats are accepted and tracked. - =Not ready= — blocking ambiguity / missing decisions would force implementers to invent product behavior. - =Needs research= — external API/library/platform assumptions must be verified first. @@ -195,7 +168,7 @@ The most useful reviews move a spec from =Not ready= to =Ready with caveats= or Finding severity maps to blocking power: *high-priority findings block =Ready=* — they hold the rubric at =Not ready= (or =Ready with caveats= if the author accepts and tracks them) until dispositioned; *medium-priority findings are the author's discretion* and don't block. State the blocking status on each finding so the author running spec-response knows which ones gate the rubric. -Then update the spec's review history. Specs should carry a bottom section named =Review and iteration history= (or the nearest existing equivalent) that tracks each material author/reviewer pass. Add a concise entry for this review even when the spec is ready and no review file is written. +Then update the spec's review history. Specs should carry a bottom section named =Review and iteration history= (or the nearest existing equivalent) that tracks each material author/reviewer pass. Add a concise entry for this review even when the spec is ready and no findings are recorded. Each entry is an org subheading with a compound id followed by three body fields. @@ -207,27 +180,11 @@ Body fields: - *What changed or was recommended:* high-signal summary, not a duplicate of the whole review. - *Why:* the decision pressure or rationale that caused the contribution. -- *Artifacts:* links to the review file, response/disposition section, commits, task IDs, or source checks when useful. +- *Artifacts:* links to the relevant findings, commits, task IDs, or source checks when useful. If the spec has no such section, add it at the bottom. Keep the history short and cumulative; it is provenance for future readers, not a session transcript. -*Emit implementation tasks (drop-in for =todo.org=).* Read the spec's =Implementation phases= section and turn it into a paste-ready block in the review file, under a heading =Implementation tasks (drop-in for todo.org)=. One =** TODO= entry per phase, plus a final entry for the test surface. The point: the handoff to whoever implements is one paste, not a re-read of the spec, and a spec that can't be decomposed into phases fails this step, surfacing a shape problem before =Ready=. - -Per-phase entry, following =todo-format.md= (terse heading names the phase; body holds the one-line deliverable plus a pointer back to the spec; tags on the heading): - -#+begin_example -** TODO [#B] <phase name — smallest noun phrase> :feature: -<what this phase delivers, one line>. Spec: [[file:<spec path>]] (Implementation phases, phase N). -#+end_example - -Final test-surface entry, mirroring the spec's =Acceptance criteria= when present: - -#+begin_example -** TODO [#B] <feature> — test surface :test: -Unit: <...>. Integration: <...>. E2e / manual-verify: <acceptance criteria as checkable items>. Spec: [[file:<spec path>]] (Acceptance criteria). -#+end_example - -Priority and tags follow the deferred-work rule below. Emit the block in the review file; the author pastes it into =todo.org= during spec-response, or you log it directly when you're also closing the loop. If the spec has no =Implementation phases= section, don't invent one — that absence is the finding, and the step becomes the prompt to ask the author to add a phase decomposition before the spec can be =Ready=. +*Check the spec decomposes into phases.* A =Ready= spec needs an =Implementation phases= section an implementer can turn into one task per phase plus a test surface. Confirm it's present and decomposable — each phase small enough to reach a clean stopping point in one focused session, with no broken intermediate states. If it's missing or can't be phased, file that as a =:blocking:= finding; don't invent the phases. The phase-to-task breakdown itself is spec-response's job (its Phase 6 reads =Implementation phases= directly once the author confirms =Ready=); the reviewer only verifies the section exists and is sound. Then log deferred work to =todo.org=: v1 implementation = =[#B]= (unless urgent or speculative); vNext/someday = =[#D]=. Tag =:feature:= / =:bug:= / =:refactor:= / =:test:= / =:quick:= / =:solo:= only when accurate. Don't leave important deferred decisions only in chat. @@ -256,8 +213,11 @@ Every material comment should be tagged by force: blocking, should-fix, or optio ** Make feedback author-usable Review comments should be specific, neutral, and actionable: quote or name the spec behavior, explain the risk, recommend the smallest concrete change, and say how the author can verify the fix. Avoid personal language, rhetorical questions, vague "this needs work" comments, and comments that require the author to infer the desired edit. +** Keep review and response roles explicit +If the user asks for review plus "enhance the spec" in the same turn, produce the findings first. Make only low-risk provenance and tracking edits unless the user clearly wants the reviewer to respond too. Don't silently resolve product decisions on the author's behalf — a proposed default belongs in a finding until it's accepted, modified, or rejected. + ** Preserve iteration provenance -Future reviewers and implementers need to know not just the current decision, but how the spec got there: how many review/response loops happened, who contributed, what they changed or recommended, and why. Keep that record in the spec itself under =Review and iteration history= so the trail survives deleted review files, chat loss, and agent handoffs. +Future reviewers and implementers need to know not just the current decision, but how the spec got there: how many review/response loops happened, who contributed, what they changed or recommended, and why. Keep that record in the spec itself under =Review and iteration history= so the trail survives chat loss and agent handoffs. ** Be strict about ownership Especially for org-mode features: a user treats visible text as editable unless the representation says otherwise. Make generated-vs-editable explicit. @@ -265,6 +225,9 @@ Especially for org-mode features: a user treats visible text as editable unless ** Never depend on an unverified API shape If the spec assumes fields/mutations/enums, they're verified against current schema/docs/live responses, or listed as a research prerequisite. =Needs research= is a real, useful verdict. +** Source external-dependency checks in the finding +When a finding turns on a current external-dependency fact (release version, API capability, platform behavior, package availability, hosted-service terms), cite the checked source in the finding body. Stale dependency assumptions are common, and the next reviewer needs to tell "verified this pass" from "remembered from prior context." + ** Favor small pure cores and thin IO layers Push findings toward separable, unit-testable pure functions surrounded by thin command/transport layers. @@ -354,3 +317,8 @@ Sources: - *What:* Two refinements to the same-day decisions convention after Craig's review: the gate item and =Ready= rubric now read "no decision is still =TODO=" with =SUPERSEDED= and =CANCELLED= counting as resolved (spec-create's template defines them as done-class keywords via a =#+TODO:= header), and a spec still on the retired =State:= field model explicitly fails the gate item until converted — closing the vacuous-pass hole on old specs. - *Why:* Review of the freshly-landed convention flagged that TODO/DONE alone lost the old model's superseded state and that the gate as written would silently pass a spec with no decision tasks at all. Craig chose the two done-class keywords and the auto-added =#+TODO:= header (the in-file header is what makes custom keywords portable). - *Artifacts:* Paired spec-create.org edits (keyword scheme + template header) in the same commit. + +** 2026-06-21 Sun @ 23:16:06 -0400 — Claude Code (rulesets) — responder +- *What:* Moved findings from a sibling =<spec>-review.org= file into the spec itself. Findings are now =** TODO= tasks under a =* Review findings= section with a =[/]= cookie, mirroring =* Decisions=; =:blocking:= marks high-priority. Phase 5 records findings in the spec instead of writing a review file; the Phase 6 =Ready= rubric gates on both the decisions and the findings cookie; the implementation-task drop-in (which lived in the review file) is gone, leaving the reviewer to verify the spec decomposes into phases and spec-response to build the breakdown. Also added two reviewer-practice principles harvested from a home spec-review: keep review and response roles explicit, and source external-dependency checks in the finding. +- *Why:* The delete-the-review-file convention 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. Craig's call: incorporate the review into the document, reusing the decisions machinery so the readiness signal is a cookie, not a file's presence or absence. The role-explicit and source-checking practices came in from the home finance-report spec via inbox handoffs. +- *Artifacts:* Paired spec-response.org edits in the same commit. Inbox handoffs =2026-06-20-2339-from-home-spec-response-readiness-gate-proposal.org=, =2026-06-21-0156-from-home-companion-to-tonight-s-spec-response.org=, and the home-edited =2026-06-21-0156-from-home-spec-review.org=. |