Coverage Matrix (coverage matrix generation/maintenance)
Positioning
Three-way coverage matrix:Invariants ↔ L1 tests / Events ↔ tests / DoD ↔ gates. LLM semi-automatic—
the matrix is generated in an initial version by this skill, then manually verified;no runtime enforcement(division of labor with ddd-qa-chain's enforcement gates).
When to use
- End of stage: "Update coverage matrix" (from S2 onward, always asserted as part of DoD—see stage-spec template)
- After adding invariants / adding events
Inputs (scan sources)
Scope declaration: the paths/symbols in the table below aredefault layout example for this project (neonforge), not universal facts.
When taking over a new repository, first perform the existence probe in process step 0 and adjust according to the repository's actual equivalent sources; if no correspondence can be made, stop and explain to the user.
| Source |
Path |
What to extract |
| L1 tests |
tests/unit/*.test.ts |
describe/it names (case list) |
| Event registry |
src/domain/timeline.ts TIMELINE_EVENT_SPECS |
All event ids/semantics |
| Invariants |
Design §9.5 invariant matrix / domain documentation |
Invariants 1-N and assertions |
| stage-spec DoD |
docs/design/stage-specs/S{N}.md |
DoD assertion checklist |
Process
- [ ] 0. 布局探测：核对上表默认源是否存在（tests/unit/、事件注册表文件、
docs/design/stage-specs/、docs/tests/）；布局不同→先映射到仓库实际等价源
并在矩阵头部记录映射；无法映射→停止，向用户说明本技能仅适用 staged-delivery 布局
- [ ] 1. 扫 L1 测试：读 tests/unit/ 全部 *.test.ts，提取 describe/it 名（含所属文件）
- [ ] 2. 扫事件注册表：读 src/domain/timeline.ts TIMELINE_EVENT_SPECS，提取事件 id 清单
- [ ] 3. 读不变量来源（设计 §9.5）与当前阶段 stage-spec DoD
- [ ] 4. 生成/更新 docs/tests/coverage-matrix.md 三向表（见下）
- [ ] 5. 标缺口：不变量无测试 / 事件无断言 / DoD 无门禁方法
- [ ] 6. 缺口清单（非空时）→ audit-item 入账（open，来源=覆盖矩阵）
- [ ] 7. 自查：抽查 3 条与测试/注册表一致（验收硬项）
Matrix structure (three-way tables)
Table 1: Invariants ↔ L1 tests
| Invariant |
Semantics |
Covering tests (file::case) |
Verdict |
| Inv 1 |
… |
tests/unit/conversationState.test.ts::「…」 |
✓ / ✗ gap |
Table 2: Events ↔ tests
| Event id |
Semantics |
Assertion tests |
Verdict |
| session.pending_set |
… |
… |
✓ / ✗ no assertion |
Table 3: DoD ↔ gates
| DoD assertion (spec original text) |
Gate method (stage-gate execution method) |
Verdict |
| L1 fully green (N new added) |
npx vitest run |
Assertion executable ✓ |
Gap determination
- Invariant is defined in the design but has no test coverage whatsoever → gap
- The event registry has an event but the tests have no assertion (not limited to tlog instrumentation—semantic assertion is required) → gap
- DoD assertion cannot be mapped to a gate method → spec defect(return to stage-spec, not counted as a matrix gap)
- Gaps are always entered into audit-item (open), for stage-gate audit status assertion enumeration
Acceptance
- The matrix is consistent with the tests/registry (spot-check 3 entries: randomly pick test names and look them up in reverse in the matrix, and events and look them up in reverse in the tests)
- When the gap list is non-empty, it has been output (in the matrix + entered into audit-item)
- All three tables are complete; no empty values in the verdict column
- The matrix header has the generation date and data source version (test count/event count)
Boundaries (division of labor)
| Adjacent skill |
Division of labor |
audit-item |
Gaps → audit items (this skill only enters them; tracking belongs to audit-item) |
stage-gate |
Gates onlycheckmatrix existence and consistency; matrix generation/update belongs to this skill |
ddd-qa-chain |
Runtime enforcement gate (L1-L5 execution); the matrix is a static document and does not replace execution |
stage-spec |
DoD cites the assertion "coverage matrix has been updated"; spec changes drive matrix rescans |
Anti-patterns
- Writing the matrix by hand off the top of one's head (without scanning tests/registry—it is bound to go stale)
- The matrix is disconnected from the tests yet still marked ✓ (spot checks are a hard requirement)
- Gaps found are not recorded (the gate cannot see them)
- Treating the matrix as gate execution (coverage ≠ passing—the matrix does not run tests)
- Doing only Table 1 and ignoring the event/DoD dimensions (all three are indispensable)
