From d22e74762125b2b308e9259b6f606ae7eaa2ba21 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sat, 13 Jun 2026 01:42:33 -0500 Subject: chore: capture spec-decisions convention, skeptical-review gate, and wrapup routing spec --- ...ons-convention-skeptical-review-wrapup-spec.org | 196 +++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 .ai/sessions/2026-06-13-01-41-decisions-convention-skeptical-review-wrapup-spec.org diff --git a/.ai/sessions/2026-06-13-01-41-decisions-convention-skeptical-review-wrapup-spec.org b/.ai/sessions/2026-06-13-01-41-decisions-convention-skeptical-review-wrapup-spec.org new file mode 100644 index 0000000..e553490 --- /dev/null +++ b/.ai/sessions/2026-06-13-01-41-decisions-convention-skeptical-review-wrapup-spec.org @@ -0,0 +1,196 @@ +#+TITLE: Session Context — 2026-06-12 19:06 +#+AUTHOR: Craig Jennings & Claude + +* Summary + +** Active Goal + +Started with startup + an inbox handoff and grew into a full day on inbox-processing discipline: apply the spec-decisions-as-TODO convention from .emacs.d, codify a Skeptical Review gate for inbox change proposals, then exercise it on a /loop and run spec-create end to end on the wrap-up routing feature it surfaced. + +** Decisions + +- Spec decisions are org TODO tasks that flip to DONE on agreement, with a =[/]= cookie, a =*** Discussion= child for disputes, SUPERSEDED/CANCELLED as done-class keywords (Craig's refinement), and a =#+TODO:= header making them portable. The implementation-ready gate is "no decision still TODO." +- Downstream edits to rulesets-owned synced files propagate via inbox-send back to rulesets (codified in cross-project.md). +- New Skeptical Review gate: inbox proposals to change shared assets get a written question battery + recommendation before applying; in no-approvals sessions they defer-and-stage as a [#B] VERIFY rather than self-applying. The inbox gate, the router, and defer-and-stage stay three distinct mechanisms. +- Wrap-up routing spec: Reading B (router acts on session-filed keepers that belong elsewhere, not raw inbox files), separate from the inbox gate (D1), distinct from defer-and-stage (D5), transcripts deferred to vNext (D4). All 6 decisions resolved. + +** Data Collected / Findings + +- The Skeptical Review caught real gaps on its first live outing: a verification.md self-contradiction (smoke handoff) and an over-scoped feature that needed a spec not a direct apply (archsetup handoff). +- Grounding for the wrap-up spec: =tc--find-section "open work"= in todo-cleanup.el is the reusable destination anchor; =inbox-send.py= discovery filters on =.ai/protocols.org= and must widen to "todo.org with Open Work"; the existing inbox sanity check is a pure gate the router must not muddy. +- The A-vs-B input ambiguity (raw inbox files vs filed keepers) was the root under both D1 and D5; resolving it once settled both. + +** Files Modified + +- claude-templates/.ai/workflows/spec-create.org, spec-response.org, spec-review.org (+ .ai mirror) — decisions-as-TODO convention + SUPERSEDED/CANCELLED keywords + old-State-model gate. +- claude-rules/cross-project.md — propagate-synced-edits section + reconciling sentence; claude-rules/verification.md — src-block rule for executable checklist steps. +- claude-templates/.ai/workflows/process-inbox.org, monitor-inbox.org, protocols.org (+ mirror) — Skeptical Review gate + act-now exceptions. +- docs/design/wrapup-routing-spec.org (new) + 2026-06-13-wrapup-inbox-transcript-routing-proposal.org (filed source); todo.org task DOING with cross-link. +- Commits 7c05253, f058b4c, 22edacf, 4fa8fd7, e8d1640, 049aafb, 7b65b2d, 62cd707 (+ this wrap). + +** Next Steps + +- Run spec-review on docs/design/wrapup-routing-spec.org (the task is DOING; spec-review gates it to a rubric and lifts the implementation phases into tasks). The one detail flagged for the reviewer: how a session-filed keeper is marked as a cross-project candidate (tag at file time vs CREATED-this-session inference). +- 11 projects still carry the 2026-06-12 Priority Scheme handoff; helper-instance build still awaits Craig's go (both pre-existing, untouched today). + +KB: promoted 0 / consulted no + +* Session Log + +** Startup + inbox: spec-create decisions-as-TODO convention + +Startup ran clean (no crashed session, no reminders, 0 stale tasks). Two +handoffs from .emacs.d arrived at 19:06: a note describing the new +spec-create Decisions convention (each decision is an org TODO task that +flips to DONE on agreement, Discussion child header for disputes, [/] +cookie on the Decisions heading, implementation-ready gate on all-DONE) +plus the edited spec-create.org as attachment. Value gate: improves how +the project works — accepted, implement now (Craig's call documented in +the handoff). + +Diffed attached vs canonical: delta is exactly the three named spots +(Phase 2 item 3, Phase 6 gate, template skeleton). Plan: copy attached +over canonical claude-templates/.ai/workflows/spec-create.org, reconcile +spec-response.org (Phase 4 steps 4-5) and spec-review.org (Phase 1 gate + +Phase 6 rubric) to the TODO/DONE model, sync mirror via sync-check --fix, +reply to .emacs.d, commit. + +Also noted: .claude/settings.json has an uncommitted model change +opus → fable (Craig's edit, presumably deliberate) — surfaced, not +committed by me. + +** Applied the convention + second handoff + +Copied the attached spec-create.org over canonical (diff confirmed the +three named spots only). Reconciled spec-response.org (Exit Criterion 5, +Phase 2 pre-agreed step, Phase 4 steps 4-5 + implementation-ready gate on +the all-DONE cookie) and spec-review.org (Phase 1/3 gate item + +Phase 6 Ready rubric requires the cookie complete). Appended +iteration-history entries to both. Ran lint-org on the three files — it +reflowed the spec-create template's Metadata table to the org-table +standard (rules under every row); verified the Related row + link intact. +sync-check --fix run twice (once after edits, once after the reflow); +mirror matches canonical. make test green: 415+54+12 pytest, all ERT, +bats fail 0. + +Replied to .emacs.d (accept + what landed), deleted both inbox files. +A second handoff arrived mid-pass: codify the propagate-synced-edits +process. Accepted, implemented as a new section in +claude-rules/cross-project.md ("Changing a Rulesets-Owned Synced File +from a Downstream Project" — three steps, agent's-job framing, spec-create +as worked example). Replied, deleted, inbox now 0 pending. notes.org +:LAST_INBOX_PROCESS: stamped 2026-06-12 evening. + +** Published + +Publish flow ran: Step 0 clean (0 behind / 0 ahead), /review-code --staged +verdict Approve (no Critical/Important; one dated-example Minor noted), +/voice personal on both drafts (em-dashes, a semicolon, terse cuts fired). +Gate skipped (.ai/ tracked). Two commits pushed to cjennings.net: + +- 7c05253 feat(workflows): spec decisions become org TODO/DONE tasks + (6 files: spec-create/response/review canonical + mirror) +- f058b4c docs(rules): codify propagating synced-file edits back to + rulesets (cross-project.md + notes.org stamp) + +Inbox pass totals: 3 items processed (2 + 1 mid-pass arrival), 3 accepted +as implement-now, 0 rejected. Two acceptance replies sent to .emacs.d. + +Still uncommitted, deliberately: .claude/settings.json model opus → fable +(Craig's edit — his call whether to commit). + +** Soft-spot review + refinements (Craig's call) + +Craig asked whether I agreed with the incoming changes. Surfaced four +soft spots: superseded state lost (two-state model), mixed-convention +corpus (old State: specs vacuously pass the new gate), agenda-visibility +claim (I called it oversold — wrong: Craig's M-F8 buffer-scoped todo list +makes spec TODOs immediately visible), and a literal-reading tension in +cross-project.md (stop-and-ask vs proactive send). + +Craig's decisions: SUPERSEDED + CANCELLED as done-class keywords (not +DONE + annotation), and the #+TODO: header auto-added to the spec +template — he corrected my portability reasoning (the in-file header IS +the portability mechanism; even CANCELLED isn't built-in). + +Applied: spec-create template gains "#+TODO: TODO | DONE SUPERSEDED +CANCELLED" after #+DATE; revisiting paragraph now covers reopen/ +supersede/cancel; Phase 6 + spec-review gate and Ready rubric reworded to +"no decision is still TODO" with SUPERSEDED/CANCELLED counting resolved; +spec-review gate fails old State:-model specs until converted; +cross-project.md gains the reconciling sentence. spec-response needed no +edit (its gate already said "while any decision is still TODO"). +Iteration-history entry appended to spec-review. Mirror synced, lint +clean, make test green. FYI handoff sent to .emacs.d (keywords + header + +old-spec gate note). + +Published: /review-code --staged Approve, /voice personal on both drafts, +two commits pushed: 22edacf feat(workflows) keyword scheme + old-model +gate; 4fa8fd7 docs(rules) reconciling sentence. + +** /codify: the Skeptical Review for inbox change proposals + +Craig invoked /codify with the insight: approach inbox files with +curiosity and skepticism (his question battery + summary/recommendation/ +approval shape). Harvested against today's evidence (the spec-decisions +handoffs were applied autonomously and the critical gaps only surfaced in +his after-the-fact "do you agree?"). Promotion target: canonical +process-inbox.org, not CLAUDE.md (inbox processing is cross-project). + +Design refined across three exchanges: (1) the no-approvals tension +resolved by defer-and-stage — behavior-changing proposals park as a [#B] +VERIFY with prepared diff in working/, wording-only fixes proceed logged; +key insight: the cross-project propagation process makes canonical +updates non-urgent (sender has a local stopgap). (2) VERIFY shape: +decision package (what arrived / recommendation / diff link / the ask), +[#B] so startup A/B surfacing catches it, no SCHEDULED unless a real +deadline. (3) Conflict sites patched: monitor-inbox.org act-vs-file +gains the shared-asset exception; protocols.org's act-now summary line +gains the same clause. + +Edits: process-inbox.org (new Skeptical Review section + Phase B step 4 + +Phase C note + Park disposition + Common Mistake #9 with today as worked +example), monitor-inbox.org (exception), protocols.org (exception +clause). Lint reflowed protocols.org's three tables to the org-table +standard (predated the rule) — riding along. Mirror synced, make test +green (exit 0). + +** Loop: skeptical-review on /loop, two handoffs processed + +Set up /loop 5m "check the inbox and give it the skeptical-review" (cron +f8e999c6, since cancelled on Craig's word). Two handoffs arrived and got +the new Skeptical Review: +- smoke: executable checklist steps in org src blocks. Accepted with one + added change — scoped verification.md's existing "one action per item" + bullet so it didn't contradict the new rule. Pushed e8d1640, replied. +- archsetup: wrap-up inbox/transcript routing. Review concluded + spec-shaped, not apply-shaped (multi-part, design uncertainty, + cross-project write, transcript-source dependency, overlap with the + defer-and-stage router). Filed [#B] :feature:spec: TODO, moved proposal + to docs/design/, replied. Pushed 049aafb. +The gate did its job first time out: caught the verification.md +self-contradiction and stopped the archsetup feature from being applied +raw. Switched default model opus per /model. + +** spec-create: wrap-up routing spec drafted + +Ran spec-create on the wrap-up-routing task. Grounded against +wrap-it-up.org Step 3, todo-cleanup.el's tc--find-section "open work" +matcher (reused as destination anchor), inbox-send.py's .ai/ discovery +filter (widened to "todo.org with Open Work"). Wrote +docs/design/wrapup-routing-spec.org dogfooding the decisions-as-TODO +convention: 3 DONE (matcher reuse, atomic move helper, cross-project +provenance), 3 TODO for Craig (D1 separate-vs-merged step, D4 transcript +scope, D5 reconcile with defer-and-stage). 5 phases, acceptance criteria, +readiness dimensions, risks. Status draft per the gate. Lint clean +(wrap-org-table reflowed the Metadata table). todo flipped to DOING with +spec cross-link. Next: spec-review once D1/D4/D5 resolve. + +** Decisions resolved: Reading B + +Craig picked Reading B (router input = filed keepers belonging elsewhere, +not raw inbox files). Resolved all 6 decisions: D1 separate sub-step, D4 +transcript deferred to vNext, D5 distinct from defer-and-stage. Reworked +the design (input definition + candidate-set note bounding the router to +session-filed keepers, never the standing backlog), Phase 3, cookie [6/6], +Status → ready for review. todo body updated. Lint clean. Next: spec-review. -- cgit v1.2.3