audit-item · diff
v1.0.1 to v1.1.0
80 added, 9 removed. Audit A to A.
---
name: audit-item
description: >-
- Track audit/review findings as numbered issue files
- (.scratch/neonforge-v1/audit-items/NNN-slug.md) with id, severity, source audit,
- status (open/fixed/recorded), fix commit, regression test, and closing evidence,
- plus a summary index README that the stage-completion gate enumerates. Use when an audit or review
- produces findings ("把审计发现入账" / "审计项"). NOT for: finding the issues
- (that is the review or audit pass itself) — this skill only tracks them.
+ Track audit/review findings as numbered issue files (audit-items/NNN-slug.md,
+ under the directory the project keeps such findings) with id, severity, source
+ audit, status (open/fixed/recorded), fix commit, regression test, and closing
+ evidence, plus a summary index README that the stage-completion gate enumerates.
+ Use when an audit or review produces findings and the user asks to record them
+ (e.g. "log the audit findings"). USER-INVOKED ONLY: it writes tracked files —
+ the agent must not auto-invoke it. NOT for: finding the issues (that is the
+ review or audit pass itself) — this skill only tracks them.
slug: audit-item
- version: 1.0.1
+ disable-model-invocation: true
+ version: 1.1.0
displayName: audit-item
---
# Audit Item（审计问题 issue 化跟踪）
## 定位
审计/评审产出的发现 → 编号 issue 文件 + 汇总索引，让每个发现可追踪到关闭，
且**可被 stage-gate 枚举**（门禁「审计状态」断言核对 open 项）。
## 何时使用
- 审计/评审产出发现后：「把审计发现入账」「审计项」
- 覆盖矩阵缺口、code-review 阶段评审、文档审计、领域审计——任何来源的发现
## 目录约定
- - 单条：`.scratch/neonforge-v1/audit-items/NNN-slug.md`（NNN = 顺序编号，slug = kebab）
- - 索引：`.scratch/neonforge-v1/audit-items/README.md`（汇总表）
+ - 单条：`audit-items/NNN-slug.md`（NNN = 顺序编号，slug = kebab）
+ - 索引：`audit-items/README.md`（汇总表）
- 目录不存在 → 创建（含 README 骨架）
## 模板（字段必填）
```markdown
# 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 存在 / 回归测试红→绿 / 证据链接}
```
## 状态流转
```
open ──修复──→ fixed（修复 commit + 回归测试 + 关闭证据，三缺一不算 fixed）
open ──裁决──→ recorded（裁决不修：记录理由，不再要求修复——门禁视为已收）
```
- **fixed**：修复 commit 可查 + 回归测试证明（红→绿或等价证据）+ 关闭证据链接。
- **recorded**：明确裁决不修（如「V2 规模待拍板」）——理由写入关闭证据；与 fixed 同样满足门禁。
- 状态变更时更新 README 索引行（状态 + 关闭证据列）。
## 索引 README
```markdown
# Audit Items 索引
| # | 标题 | 严重度 | 状态 | 来源 | 关闭证据 |
|---|------|--------|------|------|---------|
| 001 | … | medium | fixed | … | commit abc + 测试 |
```
- stage-gate「审计状态」断言 = 枚举本索引 open 行（应为空，或每条有 fixed/recorded 证据）。
## 验收
- [ ] 每条发现一条 issue 文件（字段齐全），索引已加行
- [ ] open 项可被 stage-gate 枚举（README 状态列可过滤）
- [ ] fixed 项含验证证据（commit + 回归测试 + 链接）
- [ ] recorded 项含裁决理由
## 边界（分工）
| 相邻技能 | 分工 |
|---------|------|
| `code-review` | 阶段末评审产出发现 → 入账本技能（评审只管发现，跟踪归这里） |
| `coverage-matrix` | 矩阵缺口 → 入账本技能 |
| `stage-gate` | 门禁枚举 open 项核对（消费本技能的索引） |
| 各类 audit | 领域/文档/产品审计发现的落点（来源审计字段指向报告） |
## 反模式
- 发现只写在审计报告里不入账（门禁看不见）
- fixed 无回归测试/无证据链（「修了」不算数）
- recorded 无理由（变成永久 open 的挡箭牌）
- 编号跳号/覆盖旧 issue
- 关闭后删文件（历史审计轨迹保留）
+
+ ## 显式调用示例
+
+ ```text
+ @audit-item
+ 把 docs/audits/intent-confirmation-impl-audit.md §S2 的 3 条发现入账（severity 见报告）
+ ```
+
+ - 入账 N 条 → 产出 N 个 issue 文件 + README 索引 N 行；无参数时先问来源审计报告路径，**不猜**。
+ - 本技能只做入账与跟踪，不自主触发审计；`disable-model-invocation: true` 时仅用户显式调用。
+
+ ## 最短真实样例（前置 → 调用 → 产出摘录）
+
+ 前置：一轮文档审计已产出报告 `docs/audits/xxx-audit.md`，其中 §S2 有 1 条 medium 发现。
+
+ 产出摘录（`audit-items/007-intent-confirm-missing.md`）：
+
+ ```markdown
+ # A-007 意图确认缺少驳回分支
+
+ - id: 007
+ - 严重度: medium
+ - 来源审计: docs/audits/xxx-audit.md §S2
+ - 状态: open
+ - 修复 commit:
+ - 回归测试:
+ - 关闭证据:
+
+ ## 发现
+
+ 意图确认只处理"确认"，驳回时流程静默继续（证据：报告 §S2 截图 2）。
+
+ ## 关闭条件
+
+ - [ ] 修复 commit 存在
+ - [ ] 回归测试红→绿
+ - [ ] 关闭证据链接
+ ```
+
+ 索引 README 对应行：
+
+ ```markdown
+ | 007 | 意图确认缺少驳回分支 | medium | open | xxx-audit.md §S2 | — |
+ ```
+
+ ## 失败出口与校验（可观察）
+
+ 本技能无自带脚本；每步出口都是**文件与文本层面可核对**的检查，不通过就停在原地并报告，不带病入账：
+
+ | 情形 | 可观察出口 |
+ |------|-----------|
+ | 来源审计路径不存在 | 停止入账该条；回复「来源审计文件不存在: <路径>」，不创建 issue 文件 |
+ | 发现无证据（只写"感觉有问题"） | 退回补证据行号/引用后才入账；issue 文件里「发现」节不得为空 |
+ | NNN 编号与已有文件冲突（`ls audit-items/ | grep ^NNN` 命中） | 取下一个空闲编号，不覆盖旧文件 |
+ | 状态改为 fixed 但三要素缺一（commit/回归测试/证据） | 保持 open，回复「三缺一不算 fixed，缺：<字段>」——不许中间态 |
+ | recorded 无裁决理由 | 不改状态；回复「recorded 需把理由写入关闭证据字段」 |
+ | 目录不存在 | 创建目录 + README 骨架（这是唯一允许的自动动作） |
+
+ ## 错法 → 改法（FAQ）
+
+ | 错法 | 后果 | 改法 |
+ |------|------|------|
+ | 发现只留在审计报告里，不入账 | stage-gate 枚举不到，门禁形同虚设 | 每条发现一条 issue 文件 + 索引行 |
+ | 修完直接标 fixed，没留测试与证据 | 「修了」不算数，回归无从验证 | 三要素齐了才改 fixed（commit + 回归测试 + 关闭证据） |
+ | 用 recorded 永久挂起不想修的项 | 变成规避门禁的挡箭牌 | recorded 必须写明裁决理由（如「V2 规模待拍板」），无理由不许 recorded |
+ | 关闭后删 issue 文件 | 历史审计轨迹丢失，复查无据 | 文件只改状态列，永不删除 |
+ | 编号随手起（复用已关闭的号） | 索引与文件对不上，门禁误判 | 严格递增 NNN；冲突时取下一个空闲号 |
+ | 手改 README 索引但不同步 issue 文件 | 两处状态不一致，枚举结果不可信 | 状态变更时先改 issue 文件，再同步索引行 |