| name | claim-vs-reality-margin |
| description | 声明≠现实——任何「X 已配置 / 已声明 / 已建立」必须配 margin 量化 + detection 机制，否则把声明当现实。Use when 设计依赖外部能力的方案（vendor partnership / TTL refresh / cron schedule / health check / 配额申请 / SLA 承诺）；或评审「我们已经 X」「客户说会 X」「config 配好了」类陈述；或排查「明明配了为什么没生效」类问题。 |
| provenance | user-authored |
Claim ≠ Reality — Margin 显式化
When to Use
- 设计依赖外部能力的方案：vendor partnership、TTL/refresh、cron schedule、health check、配额、SLA
- 评审陈述：「我们已经 X」「客户说会 X」「config 配好了」「partnership 已签」
- 排查「明明配了为什么没生效」「按理应该 work 啊」类问题
- 写对外承诺前（提案 / SOW / Solution Doc）
核心定律
「声明 X = 实现 X」是默认错觉。
每次说「X 已 OK」都必须强制问两件事：
- margin 在哪？——从声明到失败之间的安全余量是多少？
- detection 在哪？——失败时谁先发现？多久发现？
没有这两个 → 声明只是声明，不是现实。
三个典型映射
| 声明 | margin 应在哪 | detection 应在哪 | Source fact |
|---|
| Vendor partnership ≠ infra capability | capability gap 表（partnership 提供什么 vs 实际所需） | 集成阶段先做 capability matrix POC 验证，不是上线后才发现缺 | fact_50 |
| Refresh interval ≈ TTL ≠ 永远不过期 | interval ≤ TTL / 2（至少留一次重试余量） | refresh 失败 alert + token 过期前 X 分钟主动探活 | fact_39 |
| Cron 已配置 ≠ 在跑 | last-run 时间戳监控 + 漏跑阈值 | 主动 health check（不是等用户发现没收到报告） | fact_52 |
Workflow（声明前自检）
对每个「我们已经 X / 已配 X / X 会发生」的陈述：
1. X 失败的具体形态是什么？（timeout / quota exceeded / token expired / cron skipped）
2. 失败到被察觉之间有多久？（margin）
3. 谁第一个看到失败？（detection 主体）
4. 1-3 任一答不上来 → 这条声明不能落地
Gotchas
- ❌ 「partnership 已签」当作「能力具备」——签是商务，能力是工程，两件事
- ❌ TTL 1h / refresh 50min ≈ "够了" → race condition 概率 = (refresh 抖动)/(TTL margin)，不留 50% margin 必爆
- ❌ Cron schedule 写对了 ≠ 它在跑——launchd unload / daemon crash / disable flag 都让它静默死
- ❌ 「客户说会做 X」当作 X 已发生——直到看到 PR / 工单关闭 / 实测才是 observed
- ❌ 配置文件 commit 了 ≠ 配置生效了——很多 reload 是 SIGHUP only / 重启 only
与其他纪律的关系
truth-ladder → margin / detection 是 attempted → observed → confirmed 三级跳的具体保障；本 skill 是「为什么需要三级」，truth-ladder 是「怎么写三级」vendor-api-param-validation → vendor 边界悲观验证是本 skill 在 API 集成场景的特化vendor-doc-actionability → 对外文档里每个动作要配 margin 也要配 detection（谁触发 / 谁验收）execution-discipline § 边界处悲观 / 副作用留据 → 本 skill 是「悲观」的可操作化
One-liner
没有 margin + detection 的声明，等于赌博。
