From 1b4737360b6e16e3fb77fa49c6e506dead1ef1ab Mon Sep 17 00:00:00 2001 From: Rongsong Shen Date: Thu, 27 Aug 2026 09:01:17 +0000 Subject: [PATCH] docs: general design-time cross-check against project invariant dimensions Extends the save/restore-specific gate added moments ago with a broader, self-maintaining mechanism: rather than enumerating each xce-audit-invariants dimension individually in the design-review files (which would drift out of sync as new dimensions get added -- already up to 9 for controller, 4 for scheduler), both gates now instruct walking the relevant component's whole dimension list against the draft design. Catches design-time-checkable invariants (async I/O thread-role placement, fail-loud/never-self-exit process lifecycle, Raft/TLA+ safety checklist, commit-before-materialize ordering, redirect-completeness for new opcodes, driver/sim state-equivalence) before implementation rather than only via a later audit or live soak. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01AgYRU3zDTqNGV5Jk8aiKLg --- .claude/skills/kiro-spec-design/rules/design-review-gate.md | 6 ++++++ .claude/skills/kiro-validate-design/rules/design-review.md | 5 +++++ 2 files changed, 11 insertions(+) diff --git a/.claude/skills/kiro-spec-design/rules/design-review-gate.md b/.claude/skills/kiro-spec-design/rules/design-review-gate.md index 77758b9a..81aa0445 100644 --- a/.claude/skills/kiro-spec-design/rules/design-review-gate.md +++ b/.claude/skills/kiro-spec-design/rules/design-review-gate.md @@ -40,6 +40,12 @@ Before writing `design.md`, review the draft design and repair local issues unti - An omitted field is acceptable ONLY if the design explicitly documents it as a deliberate scope decision with a stated reason — a silent omission discovered later is treated as a defect, not a scope choice made after the fact. - If this project has a persistence steering doc (e.g. `persistence.md`) or an invariant-audit skill (e.g. `xce-audit-invariants`) covering this exact concern, cross-check the design against it and cite the relevant section/dimension rather than re-deriving the principle from scratch. +## Project Invariant Cross-Check (when applicable) + +- If this project maintains a persisted list of component-specific design invariants (e.g. an `xce-audit-invariants`-style skill tracking dimensions like async I/O thread-role placement, fail-loud/never-self-exit process lifecycle, consensus/replication safety checklists, commit-before-materialize ordering, or driver/simulation state-equivalence per component), and this design touches one of those components, walk that component's dimension list against the draft design — not just after implementation via a later audit. +- A design that would violate a known invariant (e.g. places blocking work on a trigger-only thread, includes a code path that self-terminates on an operational condition, or adds a new primary-only operation without a redirect path) should be repaired at design time, not discovered later by an audit or a live soak. +- Cite which dimensions were checked and their outcome in the design's own Constraints or Boundary Commitments section, so a later reviewer doesn't have to re-derive which invariants were even considered. + ## Mechanical Checks Before applying judgment, verify these mechanically: diff --git a/.claude/skills/kiro-validate-design/rules/design-review.md b/.claude/skills/kiro-validate-design/rules/design-review.md index c842ad12..3cb829b2 100644 --- a/.claude/skills/kiro-validate-design/rules/design-review.md +++ b/.claude/skills/kiro-validate-design/rules/design-review.md @@ -47,6 +47,11 @@ Conduct interactive quality review of technical design documents to ensure they - A design that only checks aggregate signals (row counts, cursor position, "state looks right") without addressing per-field completeness should be flagged here, not waved through as a detail for implementation. - Cross-check against this project's own persistence steering doc / invariant-audit skill if one exists, and cite the specific section rather than re-deriving the principle. +### 6. Project-Specific Invariant Alignment (when applicable) +- Applies when this project maintains a persisted list of component-specific design invariants (e.g. an `xce-audit-invariants`-style skill) and the design touches a component that list covers. +- Walk that component's dimension list against the design draft rather than assuming a later audit will catch a violation — a design that would place blocking work on a trigger-only thread, self-terminate on an operational condition instead of fencing, or otherwise contradict a documented invariant is a design-stage defect, not an implementation detail. +- Flag as a critical issue if the design is silent on a dimension that clearly applies (e.g. an HA-touching design that never addresses the consensus/replication safety checklist). + ## Review Process ### Step 1: Analyze