用途：诊断 AI 编码智能体在评估中失败的原因，重点排查引导（guided）与无引导通过率差异，目标是让引导通过率达到 100%，无引导通过率可忽略。
核心原则：发现根因后需在当前会话中立即修复，不建跟踪 issue；只修改用例相关文件（task.md、grader.ts、expectations.md、demo 应用、guide.md），不修平台基础设施或 Playwright 测试环境，发现基础设施问题应告知用户并建议在 GitHub 提 issue；需自主循环修复、重跑、度量与回滚，多次测试确保结果稳定。
gd eval 耗时较长，需约每 30 秒向用户汇报一次进展，汇报须引用底层日志或代码块、给出可点击的日志文件链接，且不得包含时间戳。
关键文件：evals.json 查看整体与单项通过率、技能是否被激活；session-<timestamp>.json 追踪思考轨迹（须看最新运行）；index.html 检查实际产出；tasks/task.md 为提示词（仅首个列表项被执行，且须单行无换行）；grader.ts 为校验逻辑；expectations.md 仅用于生成 grader.ts，需与之一致；demo.html 与 negative-demo.html 用于评分器校准；guide.md 为参考指南。
用法：运行 gd eval <path/to/use-case> 获取通过率（只读，不会改动源文件，支持批量路径）；用 gcloud storage cp -r gs://guidance-evals/<suite_id> harness/results/ 下载远端历史结果；用 gd dev <path/to/use-case> --test-grader 验证评分器校准。
调查清单共七步：审计提示词、执行评估并检查基础应用、查看结果与工具激活、验证评分器容忍度（假阴性）、验证指南覆盖（真阴性）、追踪轨迹、最终完整性审计。
常见问题与对策：工具规避（guideUsageRate 为 0）时通过提示词引入旧技术无法满足的约束迫使检索指南，可临时附加 “use the modern web skill” 排查；搜索词不匹配时把智能体的搜索词加入指南元数据；指南歧义时改写元数据描述加以区分；智能体读后仍忽略指令时用 “MANDATORY:” 等强指令覆盖其先验。
限制：平台基础设施与 Playwright 环境不在修改范围内；主技能描述文件 modern-web-use-cases/SKILL.md 禁止修改；涉及具体环境配置与套件细节时，资料未提供完整说明。