docs(v5.4.9): expose a centralized pitfall guide

Why:
- SkillHub and first-use review showed that anti-patterns and FAQs existed but were difficult to discover from onboarding.
- Deep users had to scan multiple references before finding corrective guidance.

What:
- Add a bilingual, scannable pitfall index to the existing troubleshooting reference.
- Link the guide directly from the 60-second README path and route pitfall/FAQ intent from SKILL.md.
- Update the current SkillHub signal and add a regression that protects guide discoverability.

Scope:
- Same-version 5.4.9 documentation patch; no new lifecycle stage, schema, runtime file or workflow.
- Existing authoritative contracts remain in their original references; the guide is a routing index, not duplicated truth.

Validation:
- Full pytest 84/84 PASS.
- Full CLI release profile, public quickstarts, runtime package and Skill Creator validation PASS.
- Runtime allowlist remains 115 source files.

Author: franklinxkk

CHANGELOG.md

@@ -10,6 +10,7 @@
 - **Evidence boundary**：上述证据证明确定性合同、模型冷读和有界 Coding Agent 实现，不证明真人团队完整盲审、真实数据库/接口/IAM、AI 模型效果、性能、安全、客户签认或生产稳定性。AI Native 本轮未执行盲实现；CRM 原始评测工件在 390px 下仍有 63px 横向溢出，未包装成公共运行时已全面解决。
 - **Human-first review projection patch（同版本）**：R1/R2 右栏收敛为“总览 / 功能与流转 / 边界与验收”。复杂模块在总览展示核心流程并高亮当前页面；功能点默认使用自然语言，前端、后端与测试细节按需展开；边界页只在跨页、跨角色、跨系统或关键状态流转时显示状态/数据图，并配少量可执行正反例。稳定 ID、字段枚举与技术链路移入默认收起的“技术追溯”，简单 CRUD 不机械画图。
 - **Review-change lifecycle patch（同版本）**：评审后的“修改、删除、新增标注”必须先进入 `CHG-*` 与澄清决定，再同步 PRD、语义覆盖分母、ReviewPoint Declaration、DOM marker/card/target、验收与回归。被删除的稳定身份保留在变更记录中但退出新基线分母；新增项取得新稳定身份；可见序号按新 Declaration 重排，不能把序号当永久业务 ID。旧 baseline 的评审记录和分享定位不得静默复用于新 baseline。
+- **Pitfall discoverability patch（同版本）**：不新增流程或运行文件，将现有排障、FAQ 与反模式重构为顶部可扫读的双语“避坑指南”，集中索引简单需求过度治理、原型目标提前停止、未知项伪确认、评审态默认开启、Product Truth 过早启用、双 PRD 漂移、伪造门禁、证据越级、跨基线复用和领域来源过时等高频误用。README 60 秒入口与 SKILL 路由均可直接到达，并增加回归防止入口再次隐藏；社区评分按 2026-09-02 的 SkillHub 4.7/5 当前值更新。
 
 ## 5.4.8 - 2026-08-26
 

README.md

@@ -18,10 +18,11 @@
 | 平台 / Platform | 当前数据 / Current signal | 详情 / Details |
 |---|---:|---|
 | ClawHub | **2,200+ 次下载/使用 / downloads & uses** | [版本、下载量与安全审计 / Versions, usage and security audit](https://clawhub.ai/franklinxkk/skills/ai-delivery-spec) |
-| SkillHub | **4.8 / 5** | [评分与安全扫描报告 / Rating and security scan](https://skillhub.cn/skills/user_12c92261/ai-delivery-spec) |
+| SkillHub | **4.7 / 5** | [评分与安全扫描报告 / Rating and security scan](https://skillhub.cn/skills/user_12c92261/ai-delivery-spec) |
 
-> 社区数据核对于 2026-08-28，会随平台实时变化。如果它帮你少开一次“补规则”的会，欢迎到 [GitHub 点个 Star ⭐](https://github.com/franklinxkk/ai-delivery-spec)。  
-> **English:** Community figures were checked on 2026-08-28 and may change. If the Skill saves your team one rule-repair meeting, please consider giving the project a [GitHub Star ⭐](https://github.com/franklinxkk/ai-delivery-spec).
+> 社区数据核对于 2026-09-02，会随平台实时变化。如果它帮你少开一次“补规则”的会，欢迎到 [GitHub 点个 Star ⭐](https://github.com/franklinxkk/ai-delivery-spec)。
+>
+> **English:** Community figures were checked on 2026-09-02 and may change. If the Skill saves your team one rule-repair meeting, please consider giving the project a [GitHub Star ⭐](https://github.com/franklinxkk/ai-delivery-spec).
 
 ## 它先解决谁的什么关键问题｜Who It Helps and Why
 
@@ -70,6 +71,10 @@ openclaw skills install @franklinxkk/ai-delivery-spec
 四个入口是意图别名，不是四套新流程。部分宿主会在消息到达模型前拦截未知命令，因此不宣称跨宿主原生注册；此时改用 `/ai-delivery-spec /dig …`、`$ai-delivery-spec /dig …`，或直接说“使用 ai-delivery-spec 深度澄清这个需求”。  
 **English:** These are intent aliases, not four separate workflows. Some hosts intercept unknown slash commands before the model sees them. In that case, use an explicit Skill form such as `/ai-delivery-spec /dig …` or `$ai-delivery-spec /dig …`, or simply say “Use ai-delivery-spec to clarify this requirement deeply.” Native registration is not claimed across all hosts.
 
+> **第一次深入使用前 / Before deeper use:** 花 3 分钟扫一遍[避坑指南与 FAQ](references/troubleshooting.md)，先避开“简单需求跑重流程、P0 未关闭就冒充基线、默认生成评审态、静态 PASS 冒充真实验收”等高频错误；不需要通读全部参考文档。
+>
+> Spend three minutes on the [Pitfall Guide and FAQ](references/troubleshooting.md) before team handoff. It prevents the most common mistakes without requiring you to read every reference.
+
 ### 3. 它会自动控制轻重｜It Automatically Controls Delivery Weight
 
 如果你只说一句“帮我做一个企业约谈 HTML”，Skill 会记住 HTML 是最终目标，先分批确认会改变范围、规则、权限、状态、指标或数据的关键决定；P0 关闭后继续生成可实施原型，**不会停在一张需求清单**。若只是想先看方向，请明确说“先做概念原型，允许合理假设”；假设和 GAP 会被显式标出，不冒充开发基线。  

SKILL.md

@@ -48,7 +48,7 @@ description: Use for creating, changing, reviewing, reverse-engineering or accep
 | 可见评审投影（仅确认后） | `references/review-workspace.md` |
 | 变更、追溯、验收 | `references/change-acceptance.md` |
 | 大输入、切片、Agent 交接 | `references/context.md` |
-| 工具适配或故障 | `references/tool-adapters.md` / `references/troubleshooting.md` |
+| 工具适配、避坑、FAQ 或故障 | `references/tool-adapters.md` / `references/troubleshooting.md` |
 | 领域证据 | `scripts/query_domain.py --domain <pack> --section "<heading>"` |
 
 不要加载 README、`maintainer/`、全部模板/示例/领域包或整个仓库。材料规模、链路数量或上下文预算触发切片时读取 `references/context.md`，不要用固定文件大小机械升级。细反例只进脱敏维护回归，不注入日常上下文。

maintainer/checks/check_v540_readme_commands.py

@@ -12,6 +12,8 @@
 ROOT = Path(__file__).resolve().parents[2]
 CLI = ROOT / "scripts" / "ai_delivery_spec_cli.py"
 README = (ROOT / "README.md").read_text(encoding="utf-8")
+SKILL = (ROOT / "SKILL.md").read_text(encoding="utf-8")
+TROUBLESHOOTING = (ROOT / "references" / "troubleshooting.md").read_text(encoding="utf-8")
 MINIMAL = ROOT / "examples" / "minimal-v5"
 MINIMAL_README = (MINIMAL / "README.md").read_text(encoding="utf-8")
 MINIMAL_CARD = MINIMAL / "requirement-card.md"
@@ -42,6 +44,13 @@ def run(*args: str) -> subprocess.CompletedProcess[str]:
 for marker in ("route-stage", "ADS:*", "resume_context", "两个本地依赖"):
     if marker not in README:
         failures.append(f"README misses progressive-disclosure marker: {marker}")
+if "[避坑指南与 FAQ](references/troubleshooting.md)" not in README:
+    failures.append("README does not expose the pitfall guide from onboarding")
+if "避坑、FAQ 或故障" not in SKILL:
+    failures.append("SKILL routing does not load troubleshooting for pitfall/FAQ requests")
+for marker in ("## 高频避坑指南", "## 集中 FAQ", "## 反模式"):
+    if marker not in TROUBLESHOOTING:
+        failures.append(f"troubleshooting misses consolidated guidance: {marker}")
 
 badge_match = re.search(r"version-([0-9]+\.[0-9]+\.[0-9]+)-", README)
 expected_version = badge_match.group(1) if badge_match else None

maintainer/evals/evidence/release-status.yaml

@@ -27,6 +27,7 @@ release_evidence:
     browser_review_linkage: marker_card_target_bidirectional_passed
     release_gate: passed
     public_quickstart_and_badcases: passed
+    pitfall_guide_discoverability: readme_skill_route_and_sections_passed
     trace_input_badcases: passed
     runtime_package_check: 115_source_files
     maintainer_budget: 55_files_under_475000_bytes

references/troubleshooting.md

@@ -1,7 +1,29 @@
-# 排障、恢复与反模式 / Troubleshooting, Recovery And Anti-Patterns
-
-仅在命令失败、大任务中断或用户询问阻断原因时加载本文件。Ultra-Light 或 Standard
-顺利执行时不要加载，避免无谓占用上下文。
+# 避坑、FAQ、排障与恢复 / Pitfalls, FAQ, Troubleshooting And Recovery
+
+用户询问“怎么正确使用、有哪些坑、为什么被阻断、如何恢复”，或准备把产物交给团队但不确定是否误用时，
+加载本文件。普通 `direct` / `standard` 任务顺利执行时不要自动加载，避免无谓占用上下文。
+
+Load this file when the user asks how to use the Skill correctly, wants a pitfall/FAQ check, needs a gate diagnosis,
+or must recover interrupted work. Do not load it automatically for an ordinary successful task.
+
+## 高频避坑指南｜Pitfall Guide
+
+这张表是入口索引，不是第二套需求合同；具体规则以“去哪里看”所指文档为准。
+Use this table as a routing index, not as a duplicate contract. Follow the linked reference for authoritative details.
+
+| 高频误用 / Pitfall | 为什么有问题 / Why it fails | 正确动作 / Correct action | 去哪里看 / Read |
+|---|---|---|---|
+| 小改也跑完整生命周期<br>Running the full lifecycle for a small edit | 工件和澄清成本超过改动风险<br>Process cost exceeds change risk | 走 `direct`，只交差异、边界、正反验收和未证明项<br>Use `direct`; deliver only the bounded delta and acceptance | `references/stages.md` |
+| 一句话要 HTML，却停在需求清单<br>Stopping at a checklist after the user asked for HTML | 把中间澄清误当最终目标<br>Clarification replaced the requested outcome | 记住原型停止点，分批关闭原型阶段 P0 后继续；只有用户明确允许才先画概念候选<br>Keep the prototype target; close blocking P0s, then continue | `SKILL.md` §2；`references/stages.md` |
+| 把未知指标、权限或规则写成已确认<br>Turning unknown metrics, permissions, or rules into facts | 流畅文本掩盖了业务决策缺口<br>Fluent prose hides a missing decision | 登记 `UNK-*`、责任人、影响、阻断阶段和退路，不替用户猜值<br>Record an owned unknown and fallback; never invent the value | `references/discover.md`；`references/specify.md` |
+| 默认生成评审态或用注释破坏产品态<br>Generating review mode by default or damaging product mode | 客户确认与研发交接是不同任务<br>Confirmation and engineering handoff are different jobs | 默认产品态；用户明确要求或交开发前确认后再加评审投影<br>Default to product mode; add review projection only after request/confirmation | `references/prototype.md`；`references/review-workspace.md` |
+| 普通项目过早启用 Product Truth<br>Enabling Product Truth too early | 多分片治理会吞掉简单需求的收益<br>Fragment governance overwhelms simple work | 只有持续变更、多投影、血缘或强审计确有需要时启用<br>Use it only for sustained change, multiple projections, lineage, or strong audit | `references/stages.md`；本文件“Product Truth 长任务避免死锁” |
+| 分别维护“人类 PRD”和“AI PRD”<br>Maintaining separate human and AI PRDs | 同一规则会漂移，双方都不再可信<br>The two truths inevitably drift | 一份权威基线，同源投影人类正文、工程附录和机器 handoff<br>Keep one authority and derive human, engineering, and machine views | `references/specify.md` |
+| 为过门禁补空标题、假 ID 或假按钮<br>Adding empty sections, fake IDs, or fake controls to pass a gate | 结构变绿但业务仍不可实施<br>Structure turns green while behavior remains undefined | 回到来源或责任人补真实语义；无法确认就保留 GAP/UNK<br>Fix the source contract or keep an explicit gap/unknown | 本文件“三分钟恢复”；`references/specify.md` |
+| 把静态 PASS 当成已实现、合规或已验收<br>Treating static PASS as implementation, compliance, or acceptance | 证据等级被越级宣传<br>Evidence is overstated | 报告命令、退出码和 `not_proven`，按需补浏览器、真实系统、领域或客户证据<br>Report the gate and its limits; add higher evidence only when executed | `references/change-acceptance.md` |
+| 评审后直接改序号或复用旧基线记录<br>Renumbering points or reusing old-baseline review records | 可见序号不是稳定业务身份，历史意见会串线<br>Visible numbers are not stable identities | 先建 `CHG-*`；修改保留稳定 ID，删除退出新分母，新增取得新 ID，记录按 baseline 隔离<br>Version the change and isolate review records by baseline | `references/review-workspace.md`；`references/change-acceptance.md` |
+| 把内置领域包当成当前项目权威<br>Treating a built-in domain pack as project authority | 法规、标准和现场规则可能已变化或不适用<br>Sources may be stale or inapplicable | 核对适用范围、发布日期和当前权威源；冲突时保留证据状态并让责任人决定<br>Verify applicability and current authority; never let a pack override project evidence | `references/discover.md`；领域包来源登记 |
+| 一次加载 README、全部参考和全部领域包<br>Loading every document and domain pack at once | 上下文被历史细节挤占，弱模型更易漏执行<br>Context is crowded and execution degrades | 只读取当前阶段、风险和领域所需切片<br>Load only the slice required by the current stage and domain | `SKILL.md` §3；`references/context.md` |
 
 ## 三分钟恢复