1 files changed, 52 insertions, 0 deletions
diff --git a/docs/design/2026-06-06-spec-review-reusable-checks-handoff.md b/docs/design/2026-06-06-spec-review-reusable-checks-handoff.md
new file mode 100644
index 0000000..89d1104
--- /dev/null
+++ b/docs/design/2026-06-06-spec-review-reusable-checks-handoff.md
@@ -0,0 +1,52 @@
+# Spec-review workflow updated for reusable package-readiness checks
+
+Updated .emacs.d/.ai/workflows/spec-review.org on 2026-06-06 after the DUET spec review surfaced reusable gaps.
+
+Added generic review checks for:
+- lost opportunities / existing framework affordances that should be reused or intentionally replaced;
+- actionable user-facing error strings;
+- observability, structured logs, debug/doctor commands, and redacted diagnostics;
+- long-running operation performance and fake-process testing;
+- public customization/defcustom surface with clear names, defaults, and safety notes;
+- documentation plan: README, user guide, developer guide, migration/upgrade notes where appropriate;
+- Makefile/package-script surface as part of product scope: setup, test, test-file, compile, lint, coverage, clean, slow/manual/live tests;
+- coverage reporting as a design requirement and refactoring signal;
+- implementation phases small enough to reach a clean stopping point in one focused work session.
+
+DUET-specific review was expanded in .emacs.d/docs/design/duet-spec-review.org with high-priority findings for documentation/tooling and diagnostics, plus medium findings for dired/dirvish reuse, error messages, and defcustom inventory.
+
+Additional update from same DUET review pass:
+- Added a generic requirement that specs state project principles / non-negotiable do-dont rules when they touch user data, remote systems, destructive actions, long-running operations, or extension points.
+- DUET-specific examples added to the review: never leave unverified temp/partial files on remote servers; make transfer status/route/progress/ETA/hung state transparent; make hung transfers killable; never silently lose data; make slow fallback routes visible; keep user-owned config user-owned; never log secrets; document backend temp-file/progress/cancellation/redaction contracts; test temp cleanup/hung/cancel/partial-failure paths with fakes.
+
+Second DUET review update:
+- Added reusable spec-review checks for explicit architecture weak points and mitigation tables.
+- Added simplicity/complexity-control checks: hot-path UX simplicity, advanced controls out of the way, thin command functions, branchy functions split/justified, and cyclomatic-complexity/coverage/code-size reports as refactoring signals.
+- Added extension/developer-experience checks: precise public ABI, capability semantics, lifecycle/failure states, redaction rules, and contract tests so plugin authors do not need private internals.
+- Expanded performance review to include concurrency, queueing, backpressure, cheap/throttled process filters, and progress/ETA only when defensible.
+- Added a small-enhancement radar dimension for low-complexity built-in affordances worth surfacing or explicitly deferring, such as archive/compress commands in file-manager specs.
+- DUET round-2 review created at .emacs.d/docs/design/duet-spec-review.org with caveats for transfer queue/monitor UX, responsiveness under heavy output, backend ABI, complexity controls, dired archive support, weak-point mitigations, sparse-pane UX, and qualitative coverage expectations.
+
+Third DUET review update:
+- Added reusable spec-review checks for transfer/sync/data-movement failure-mode research using current online sources and comparable products.
+- Added the requirement to classify each researched edge case as covered, avoided by scope, deferred with guardrails, or missing.
+- Added comparable-product sentiment review: list what users love/hate about adjacent products, then state whether the spec provides, avoids, defers, inherits, or accepts each item.
+- Added terminal-state discovery checks: completion, failure, partial success, stalled/hung, cancelled, cleanup-unverified, and needs-user-action states must be visible, notify appropriately, and keep non-success states visible until acknowledged.
+- Clarified that when Craig or a review pass surfaces a broadly reusable question/topic, it should be rewritten in generic review-checklist language, added to spec-review.org, and noted here; spec-specific questions stay in the spec review.
+- DUET-specific outcome: docs/design/duet-spec-review.org now contains a researched failure matrix and Syncthing/Dropbox love-hate comparison; docs/design/duet-spec.org gained notification policy, source-changed detection, quota/space and locked-file failure categories, expanded tests, and Appendix C.
+
+Fourth DUET review update:
+- Added a reusable CLI/tool-wrapper value check to spec-review.org: when a spec wraps command-line tools or external executables, the review must ask why a user would prefer the package over running the tool directly.
+- Added helpful-error success criteria for CLI wrappers: identify the failure class, explain likely cause, prove it with redacted evidence, state safety outcome, offer repair actions, and provide a redacted reproduction command/log bundle.
+- DUET-specific outcome: duet-spec.org now treats helpful failure explanation as a project principle, adds duet-explain-transfer-failure, backend failure-normalizers, backend doctor/preflight probes, CLI/destination gotcha matrices, and backend-normalizer fixture tests.
+
+Fifth DUET review update:
+- Expanded the reusable extension/developer-experience check in spec-review.org: plugin/backend specs should define a precise ABI, capability flags, lifecycle/failure/redaction rules, and contract tests, but also keep the authoring path tiered and approachable.
+- Added guidance that plugin authors are end-users too: reviews should look for minimum runnable / publishable / excellent tiers, scaffolds/templates, fixture-capture tools, pattern-table helpers, contract-test tiers, and docs that clearly state what information is required vs optional.
+- DUET-specific outcome: duet-spec.org now defines minimum runnable, safe publishable, and excellent backend tiers; duet-define-cli-backend; duet-define-cli-failure-patterns; duet-scaffold-backend; duet-capture-failure-fixture; duet-run-backend-contract-tests; and explicit guidance that plugin authors can start small while declaring capabilities conservatively.
+- Follow-up refinement from Craig: made the extension/developer-experience check explicitly ask what plugin authors must provide, what is optional/unknown, whether authors will know what evidence/capability metadata to add, whether the contract is too complex, and what helper APIs remove that burden while preserving diagnostic quality for plugin users.
+
+Final meta-review update:
+- Researched spec/design-review advice from reputable engineering/documentation sources and developer-community guidance.
+- Added reusable spec-review guidance: review as risk reduction rather than rewrite contest; separate blockers from preferences; make feedback author-usable; and check rollout/rollback/reversibility when public behavior, persisted data, config, plugin APIs, external resources, or remote/shared state changes.
+- Applied to DUET: duet-spec.org now includes rollback/reversibility, duet-rollback-generated-config, Phase 9.5, and acceptance criteria for generated-config rollback. The final review verdict remains Ready.