Positioning
Findings produced by audits/reviews → numbered issue files + summary index, so every finding can be tracked to closure, andcan be enumerated by stage-gate(the gate "audit status" assertion checks the open items).
When to use
- After an audit/review produces findings: "record audit findings", "audit item"
- Coverage matrix gaps, code-review phase review, documentation audit, domain audit — findings from any source
Directory conventions
- Single entry:
.scratch/neonforge-v1/audit-items/NNN-slug.md(NNN = sequential number, slug = kebab) - Index:
.scratch/neonforge-v1/audit-items/README.md(summary table) - Directory does not exist → create it (including README skeleton)
Template (fields required)
# A-NNN {标题}
- id: NNN
- 严重度: high | medium | low
- 来源审计: {报告路径 + 轮次/章节，如 docs/audits/intent-confirmation-impl-audit.md §S2}
- 状态: open | fixed | recorded
- 修复 commit: {hash（fixed 时）}
- 回归测试: {测试文件::用例（fixed 时）}
- 关闭证据: {链接/命令输出尾部（fixed/recorded 时）}
## 发现
{现象 + 证据 + 影响}
## 关闭条件
{可勾选：修复 commit 存在 / 回归测试红→绿 / 证据链接}
Status transitions
open ──修复──→ fixed（修复 commit + 回归测试 + 关闭证据，三缺一不算 fixed）
open ──裁决──→ recorded（裁决不修：记录理由，不再要求修复——门禁视为已收）
- fixed: fix commit traceable + regression test proof (red→green or equivalent evidence) + closure evidence link.
- recorded: explicit decision not to fix (e.g. "V2 scope pending decision") — rationale written into closure evidence; satisfies the gate the same as fixed.
- When status changes, update the README index row (status + closure evidence column).
Index README
# Audit Items 索引
| # | 标题 | 严重度 | 状态 | 来源 | 关闭证据 |
|---|------|--------|------|------|---------|
| 001 | … | medium | fixed | … | commit abc + 测试 |
- stage-gate "audit status" assertion = enumerate the open rows of this index (should be empty, or each has fixed/recorded evidence).
Acceptance
- one issue file per finding (fields complete), index row added
- open items can be enumerated by stage-gate (README status column filterable)
- fixed items include verification evidence (commit + regression test + link)
- recorded items include decision rationale
Boundaries (division of labor)
| Adjacent skills | Division of labor |
|---|---|
code-review |
End-of-phase review produces findings → ledger skill (review only finds; tracking belongs here) |
coverage-matrix |
Matrix gaps → ledger skill |
stage-gate |
Gate enumerates and checks open items (consumes this skill's index) |
| Various audits | Landing point for domain/documentation/product audit findings (source audit field points to the report) |
Anti-patterns
- Findings written only in the audit report without being recorded (invisible to the gate)
- fixed with no regression test/no evidence chain ("fixed it" does not count)
- recorded with no rationale (becomes a shield for permanent open)
- Skipped numbers/overwriting old issues
- Deleting files after closure (historical audit trail is retained)