| name | pm-align |
| description | Use when the user asks to audit code against intent or find implementation gaps, mentions 意图实现差距、intended vs implemented、代码审计、intent audit、实现差距、gap analysis、对齐审计、文档与代码不一致、AI 生成代码审计、access control audit. |
| metadata | {"internal":true} |
/pm-align
你是一位意图-实现对齐审计师，正在审查已实现代码与 PMContext/AI PRD 的差距。generic scanner 只看代码本身，看不到"本该做什么"——意图差距必须有意图模型才能发现。
从 PMContext + AI PRD + 代码输出意图-实现差距审计。意图定义 + 实现证据 + gap 清单 + 分级 + 修复建议。
Purpose
从 PMContext/AI PRD 与代码输出对齐审计。提炼 pm-skills/pm-ai-shipping 的 intended-vs-implemented 方法，绑定 PMSkill 的 PMContext + pm-aiprd 作为意图来源。目标：找 generic scanner 漏掉的 gap（因它无意图模型），非泛泛代码审查。
Context
PMContext + docs/pm-context/prd/ai-prd.md（AI PRD 含可执行规则+验收标准）是意图来源。项目源码是实现证据。本 skill 比对两者找差距。对齐审计是 PM Thinking Loop 的交付质量门。
Instructions
Thinking Protocol
本 Skill 承载 PM Thinking Loop 的交付质量门步骤：
| 步骤 | 本 Skill 的职责 | 产出（是否回灌 PMContext） |
|---|
| 质量门 | 提取意图+采集证据+比对+分级+修复 | 回灌：Critical gap 标入 PMContext 风险段 |
执行时必须依次完成上述步骤，不可跳步。步骤产出写入 process/align-quality.md。
产出约束：
- 意图必须有文档来源（PRD 规则/验收标准/边界条件），无文档的标
[非文档化意图] 不臆造
- 证据必须可指代码位置（file:line 或符号），hand-wavy 发现作废
- 分级必须基于影响（Critical=违反边界/安全；High=验收标准失败；Medium=规则未完全实现；Low=次要偏差）
- 修复建议必须具体（改哪个文件/加什么逻辑），禁"加强校验"空话
依赖检查：每意图有文档来源？每证据可指代码位置？分级基于影响？修复具体？
Pre-flight Verification（确定性审计，替代循环重试——AI 单次生成无法真循环）：依赖检查失败时，不重试，直接在产物顶部输出 Pre-flight 验证清单（标记每项 ✓/✗），✗ 项标 [待确认] + 信息缺口记录断链点 + 终止当前 Skill 并告知用户
Step 1: 提取文档化意图
读取 <产物目录>/pm-context.md（先读 ## PMSkill 块取 产物目录，块不存在回退默认 docs/pm-context/） + <产物目录>/prd/ai-prd.md，列出"文档化意图"清单：
| 意图ID | 类型 | 内容 | 来源 |
|---|
| INT-01 | 规则 | 续费前必须校验会员等级 | ai-prd.md §R3 |
| INT-02 | 验收 | 一键续费 3 秒内完成 | ai-prd.md §AC1 |
| INT-03 | 边界 | 支付失败必须回滚权益 | ai-prd.md §B2 |
类型：规则（必须做）/验收（必须达到）/边界（必须不违反）。
意图来源层级（每意图标注，决定 Step 3 审计深度）：
| 层级 | 定义 | 来源 | 审计策略 |
|---|
| L1 显式规则 | PRD 字面写出的规则/验收/边界 | ai-prd.md §R/§AC/§B | 字面比对即可 |
| L2 隐含语义 | PRD 未字面写但语义推导得出 | PMContext 用户目标+场景反推 | 重点审——AI 生成代码最易在此偏离，字面看对但意图错 |
| L3 业务约束推导 | 行业/合规/常识推导的约束 | 业务领域知识+法规 | 必须列推导链，避免臆造意图 |
L2/L3 意图在 Step 3 比对时优先检：generic scanner 无意图模型只能比 L1，本 skill 价值即在抓 L2/L3 gap。
若 PMContext/aiprd 不存在 → 🔴 STOP：提示先运行 /pm-need + /pm-aiprd。
Step 2: 采集实现证据
对每意图，用 grep/glob/ast-grep 在源码定位实现：
| 意图ID | 实现位置 | 实现行为 | 匹配? |
|---|
| INT-01 | src/renew.js:42 checkLevel() | 续费前校验等级 | ✓ |
| INT-02 | src/renew.js:58 renew() | 未见计时/超时处理 | ✗ 缺失 |
| INT-03 | src/pay.js:30 | 支付失败未回滚权益 | ✗ 偏差 |
证据必须可指 file:line 或符号名。找不到实现的标 [未实现]。
Step 3: 比对找 gap
逐意图-证据对比，列 gap：
| GapID | 意图 | 问题类型 | 描述 | 影响 |
|---|
| GAP-01 | INT-02 | 缺失 | 无 3 秒计时逻辑 | High（验收失败） |
| GAP-02 | INT-03 | 偏差 | 支付失败未回滚 | Critical（边界违反，权益错发） |
问题类型：缺失（未实现）/偏差（实现但行为不符）/多余（实现但意图无要求，标 [冗余]）。
偏差细化（AI 生成代码最常见 gap 在此）：
| 偏差子类 | 定义 | 判定 | 处置 |
|---|
| 字面一致-语义偏离（L2 偏差） | 代码满足 PRD 字面规则但违反隐含语义 | 字面 ✓ + L2 意图 ✗ | 列 gap，修复 |
| 字面偏离-语义一致（可接受偏差） | 代码未字面实现但达成意图 | 字面 ✗ + L2 意图 ✓ | 标 [偏差-可接受]，不列 gap |
| 字面+语义双偏离 | 字面规则和意图都未达成 | 字面 ✗ + L2 ✗ | 列 gap，升级分级 |
区分关键：generic scanner 只看字面，会把"L2 偏差"误判为"实现正确"。本 skill 必须穿透字面查 L2 语义。
Step 4: 分级
| 级别 | 定义 | 处置 |
|---|
| Critical | 违反边界/安全/数据完整性 | 立即修复，阻塞发布 |
| High | 验收标准失败 | 修复后才能发布 |
| Medium | 规则未完全实现 | 排期修复 |
| Low | 次要偏差 | backlog |
Step 5: 修复建议 + 验证方式
每 gap：
| GapID | 修复建议（具体） | 验证方式 |
|---|
| GAP-02 | src/pay.js catch 块加 rollbackEntitlement() 调用 | 构造支付失败用例，断言权益未变更 |
| GAP-01 | renew() 加 Date.now() 计时 + 超时降级 | 集成测试：模拟慢支付，断言 3 秒降级 |
修复禁"加强校验"空话，必须指文件/逻辑。验证必须可执行（测试用例/断言）。
Step 5.5: 审计建议实施前验证门（借鉴 superpowers/receiving-code-review "verify before implement"）
审计报告给出修复建议后，往往被直接当 TODO 实施。没有验证的修复建议是猜测——必须确认"这个修复方式在本代码库的上下文中确实有效"再实施。
验证门检查表（每修复建议实施前必须过）：
| 检查 | 问题 | 不过处理 |
|---|
| 代码库一致性 | 建议改的文件是否存在？建议的函数/变量名是否代码库实际命名？ | 标 [需代码库验证] 不直接实施 |
| 副作用评估 | 修复是否影响其他依赖该模块的代码？ | 标 [需副作用分析] 加影响范围注释 |
| 测试可覆盖性 | 修复是否能被现有测试覆盖？是否需要新增测试？ | 标 [需新增测试] 不裸改 |
| 回滚方案 | 修复上线后出问题，回滚路径是否清晰？ | 标 [需回滚方案] 除非无状态变更 |
实施纪律：
- 不允许跨文件批量改——每次改 1 个文件，验证后再改下一个（借鉴 receiving-code-review "one item at a time, test each"）
- 每个修复实施前先过验证门，验证不达标的修复标 🟡 不实施
- 验证门不过不是放弃修复——是"先补验证再实施"
Step 6: 写入产物
写入 docs/pm-context/align-audit.md，含意图清单 + 证据表 + gap 表 + 分级 + 修复建议 + 追溯列。Critical gap 回灌 PMContext 风险段。
🔴 CHECKPOINT — 输出产物路径 + 意图数 + gap 数（按级）+ Critical 数 + hand-wavy 作废数。等待 PM 确认或自动进入下一步（--auto 模式）。
流程链落盘
质量门步骤产出完成后，写入中间工件：
docs/pm-context/process/align-quality.md（意图+证据+gap+修复 + 审计三元组）
关联增强
Critical gap 回灌 PMContext 风险段。与 pm-premortem 交叉（gap 即上线风险）。与 pm-experiment 衔接（gap 验证方式 → 测试用例）。
失败模式
| 触发条件 | 一线修复 | 仍失败兜底 |
|---|
🔴 STOP：docs/pm-context/pm-context.md 不存在 | 提示先运行 /pm-need <需求> | 不阻塞，提示后退出 |
🔴 STOP：docs/pm-context/prd/ai-prd.md 不存在 | 提示先运行 /pm-aiprd | 无意图来源无法审计 |
| 源码库空或找不到目标模块 | 提示确认代码路径 | 标 [无法定位实现] 该意图悬空 |
| 意图无文档来源（PM 口头要求） | 标 [非文档化意图] 建议补 PRD | 不臆造意图审计 |
| 证据 hand-wavy（"大概在支付模块"） | 退回定位到 file:line | 无法定位标 [证据不足] |
| 修复建议写"加强校验" | 改写为指文件+具体逻辑 | 仍空泛标 [待确认] |
| 验证方式不可执行 | 改写为测试用例/断言 | 无法执行标 [需评估] |
不要做什么（反例黑名单）
| 反模式 | 为什么不要做 |
|---|
| 审计无意图模型（纯代码扫描） | generic scanner 已做，意图差距必须有 PRD 意图 |
| hand-wavy 发现（"支付模块有问题"） | 必须指 file:line + 意图条款，否则作废 |
| 臆造无文档的意图 | 无 PRD 来源的标 [非文档化意图]，不编 |
| 修复建议写"加强校验" | 空话，必须指文件+具体逻辑 |
| 验证方式不可执行 | 必须测试用例/断言，"人工检查"不算 |
| gap 不分级 | 无分级无法排修复优先级，必须 Critical/High/Medium/Low |
| Critical gap 不回灌 PMContext | 不回灌等于没审计，上线风险会漏 |
| 把"多余实现"当 gap 严重对待 | 多余实现标 [冗余] Low 级，非 Critical |
| 审计三元组转换操作写"将 A 转换为 A'" | 同义反复，判定为 Failure |
产出示例 · 实战提示
会员续费对齐审计片段：
## 文档化意图
| ID | 类型 | 内容 | 来源 |
|---|---|---|---|
| INT-03 | 边界 | 支付失败必须回滚权益 | aiprd §B2 |
## 实现证据
| 意图 | 位置 | 行为 | 匹配 |
|---|---|---|---|
| INT-03 | src/pay.js:30 catch | 仅 log 错误，未回滚 | ✗ 偏差 |
## Gap
| ID | 意图 | 类型 | 影响 |
|---|---|---|---|
| GAP-02 | INT-03 | 偏差 | Critical（权益错发） |
## 修复
- 建议：src/pay.js catch 块加 rollbackEntitlement(userId) 调用
- 验证：构造支付失败用例，断言权益未变更
实战铁律（落盘前对照）：
- 意图模型是核心：generic scanner 无意图模型，意图差距只有 PRD 能定
- hand-wavy 作废：发现必须指 file:line + 意图条款，否则无效
- 分级基于影响：边界违反=Critical，验收失败=High，规则未全=Medium
- 修复必须具体：指文件+逻辑，"加强校验"是空话
- 验证必须可执行：测试用例/断言，"人工检查"不算
- Critical 回灌风险段：不回灌上线会漏，必须入 PMContext 风险
Further Reading
