首页
intended-vs-implemented
phuryn/pm-skills
在代码库中发现文档化意图与实际实现之间的差异，从而捕获那些因缺乏意图模型而被通用扫描器忽略的缺陷。
...展开全部预期与实际：审计差距
目的
代码检查工具是在真空环境中扫描代码的。它能告诉你代码在内部是否一致；却无法告诉你代码是否实现了你的预期，因为它并不了解你的意图模型。 最具价值的安全和正确性缺陷就藏在这个差距之中——例如，文档中记录了权限但从未强制执行；任何人都能调用的“仅限cron”端点；以及标记为“仅限public”却泄露私有数据的字段。
这项技能正是发现该差距的方法。它也是关键的区别所在：只有在先将设计意图记录下来时（参见“发布工件”技能），它才能发挥作用，而这恰恰是通用工具无法复现它的原因。
背景
当存在已记录的意图时，请使用此技能—— permissions.md, architecture.md, variables.md等。如果相关文档缺失或过时，这种缺失本身就是第一个发现：你无法审核从未记录过的意图。建议先进行文档记录，再进行审核。
方法
确立意图。阅读
/documentation/*.md该文档集作为“应然状态”的权威依据：谁可以访问什么、哪些边界是可信的、哪些数据是公开的。将文档视为待验证的声明，而非证明。收集实现证据。阅读执行（或未能执行）每项声明的代码。证据是指明确引用的文件和行号——实际的授权检查、实际的查询过滤器、实际的数据净化器。“这可能在上游已经处理了”并非证据；代码路径才是证据。
逐个边界地将声明与代码进行比对。对于每条记录在案的规则，都要问：在服务器上，每条路径中，是否确实存在执行点来实现该规则？不要轻信诸如“仅限内部”、“仅限管理员”或“已在其他地方验证”之类的注释——必须通过代码进行验证。
根据影响程度对每处不一致进行分类。当跨越该边界会导致真实攻击者访问其不应获取的数据、资金、基础设施或其他租户时，该不一致才算重要；若唯一受影响的是攻击者自身及其自有数据，则不重要。忽略表面上的偏差；保留跨越边界的偏差。
避免含糊其辞的发现。每个发现都应明确说明：文档中记载的意图（引用文档）、实际实现情况（引用代码）、攻击者与受害者，以及具体的修复方案。如果你无法同时引用差距的双方，这只是一个需要调查的问题，而不是一个需要报告的发现。
什么才算数
- 意图：文档中记载的规则、边界、范围或公私分类。
- 实现证据：代码中引用的强制执行点（或其可证明的缺失）。
- 具有实质影响的不一致：文档所述与代码实现不符，且该差异跨越了信任、成本、数据或租户边界。
注释
- “有文档但未执行”本身即构成一项发现——应根据该差异所暴露的风险进行分级。
- “未记录但已执行”通常没问题，但需标记：文档现已过时，这会削弱下次审计的有效性。
- 此方法为安全与性能审计提供支持；它并非取代这些审计的底层分析，而是补充了它们所缺乏的“意图维度”。
- 切勿捏造意图以制造漏洞。如果文档未作说明，就如实说明文档未作说明。
---
name: intended-vs-implemented
description: Finds gaps between documented intent and actual implementation in codebases, catching bugs that generic scanners miss because they lack a model of intent.
---
# Intended vs. Implemented: Auditing the Gap
## Purpose
A linter scans code in a vacuum. It can tell you the code is *internally* consistent; it cannot tell you the code does what you *meant*, because it has no model of your intent. The highest-value security and correctness bugs live in that gap — a permission documented but never enforced, a "cron-only" endpoint anyone can call, a field marked public-only that leaks private data.
This skill is the method for finding that gap. It is the differentiator: it only works when intent has been written down first (see the **shipping-artifacts** skill), and that's exactly why commodity tools can't replicate it.
## Context
Use this when documented intent exists — `permissions.md`, `architecture.md`, `variables.md`, etc. If those docs are absent or stale, that absence is itself the first finding: you cannot audit intent you never recorded. Recommend documenting first, then auditing.
## Method
1. **Establish intent.** Read the `/documentation/*.md` set as the source of truth for what *should* be true: who may access what, which boundaries are trusted, which data is public. Treat the docs as claims to verify, not as proof.
2. **Gather implementation evidence.** Read the code that enforces (or fails to enforce) each claim. Evidence is a cited file and line — the actual authorization check, the actual query filter, the actual sanitizer. "It's probably handled upstream" is not evidence; the code path is.
3. **Compare claim to code, one boundary at a time.** For each documented rule, ask: does an enforcement point actually implement it, on the server, on every path? Distrust comments like "internal only," "admin only," or "validated elsewhere" — verify them in code.
4. **Classify each mismatch by whether it matters.** A mismatch matters when crossing it lets a real actor reach data, money, infrastructure, or another tenant they shouldn't. It does not matter when the only person affected is the actor themselves on their own data. Drop cosmetic drift; keep boundary-crossing drift.
5. **Avoid hand-wavy findings.** Every finding names: the **documented intent** (quote the doc), the **implemented reality** (cite the code), the **attacker and victim**, and the **concrete fix**. If you cannot cite both sides of the gap, it is a question to investigate, not a finding to report.
## What counts
- **Intent:** a documented rule, boundary, scope, or public/private classification.
- **Implementation evidence:** a cited enforcement point (or its provable absence) in the code.
- **A mismatch that matters:** doc says one thing, code does another, and the difference crosses a trust, cost, data, or tenant boundary.
## Notes
- Documented-but-unenforced is a finding on its own — rank it by what crossing the gap exposes.
- Undocumented-but-enforced is usually fine, but flag it: the docs are now stale, which weakens the next audit.
- This method feeds the security and performance audits; it does not replace their sink-level analysis — it adds the intent axis they lack.
- Never fabricate intent to manufacture a gap. If the docs are silent, say the docs are silent.
