lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: general design-time cross-check against project invariant dimensions

Browse source 
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AgYRU3zDTqNGV5Jk8aiKLg
This commit is contained in:
Rongsong Shen 2026-08-27 09:01:17 +00:00
parent d32f06e5fc
commit 1b4737360b
No known key found for this signature in database
GPG key ID: 5BCDAAE0123E9FE2
2 changed files with 11 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

6
.claude/skills/kiro-spec-design/rules/design-review-gate.md
View file

@ -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:

5
.claude/skills/kiro-validate-design/rules/design-review.md
View file

@ -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