analysis-core

Analysis Core

内部共享技能。用于 PDCA 修复工作流中分析阶段方法的唯一事实来源。工作流保留各自的编排方式（退出条件、手动／自动模式、OpenSpec/Jira 工件存储位置、有意的差异）。

前置条件检查：此技能在 frontmatter 中声明了强依赖。加载时，请验证每项依赖均可用；如果有任何一项缺失，请中止并打印安装命令（npx skills add FuDesign2008/open-skills -g --skill '*' --yes）。不得静默回退。

占位符约定

此技能由阶段编号不同的工作流共享。此处不得硬编码工作流的阶段编号或标题。

占位符	含义	由谁映射
{next-stage}	分析退出门槛通过后／完成检测后要进入的阶段	引用此技能的工作流，在引用行中映射（编号 + 名称）
{root-cause step} / {impact-assessment step} / {upstream-eval step}	known-issue-research 在分析阶段内的步骤编号	同一引用行（现有的 known-issue-research 约定）

1. 临时改动许可与回滚门槛

默认情况下，分析阶段为只读。仅允许进行分析辅助改动；这些改动必须登记，并在进入 {next-stage} 前全部回滚。修复实现属于工作流的执行阶段，而非此处。

允许（仅限分析辅助）：

• 检测、临时日志、复现脚本
• 假设验证改动（例如，切换某个条件以观察行为）——验证后恢复

禁止： 以实现修复为目的的改动。

登记（强制）： 每项临时改动都必须立即记录：文件 + 位置 + 原始内容 + 目的（回滚依据）。

退出门槛（进入 {next-stage} 前必须完成）：

1. 根据登记逐项恢复原内容（登记记录具有权威性；git diff 仅用于辅助确认登记项已清理——工作树中可能已有用户改动）
2. 输出「临时改动清单 + 回滚验证」
3. 如果仍有任何改动未回滚，不得进入 {next-stage}；如需保留某项改动，必须获得用户明确确认
4. 在阶段输出末尾附上 §5 分析门槛输出块（其中的临时改动行应包含此清单）

工具限制（分析阶段）： ✅ Read/Grep/SemanticSearch；✅ WebSearch（研究路由／快速搜索／上游评估／runtime-evidence-debug 例外处理）；✅ Edit/Write 仅用于上述分析辅助改动；✅ Bash 仅用于只读验证命令——运行应用进行调试或执行复现步骤仍需用户确认（见 §3）。

2. 分析阶段骨架

1. 存在性检查（关卡——始终先做）

   • 使用 Read/Grep/SemanticSearch 定位相关代码
   • 根据判定采取行动：

   判定	行动
   ✅ 问题存在	继续步骤 2 → 3–8
   ❌ 问题已消失	说明问题可能已修复或逻辑已更改，引用位置，停止并等待用户
   ⚠️ 描述与代码不符	报告不符之处，返回工作流的问题澄清阶段

2. 研究路线——加载 known-issue-research 并遵循其流程（分类 + 已知问题快速搜索 + 行业范围评估）。引用该工作流的行会提供 {root-cause step} / {impact-assessment step} / {upstream-eval step} 映射。报告模板：known-issue-research/reference.md。如果预期结果是用户可见或可操作的结果，在将该行为视为已确认之前，加载 competitive-research，并运行其精简的分层选择路径。问题应明确用户操作和可观察结果。如果要将该行为作为目标采用，还应包含重复操作、退回一级、达到零，以及与已发布行为的交互。不要复述该技能的方法。如果加载失败，则使用安装命令中止。如果结果对用户不可见，则跳过此加载。

3. 现象——复现条件/步骤；如果问题可通过浏览器复现，优先使用 browser-debug-toolkit 进行复现并观察运行时状态（不限于 UI/CSS/DOM；如果浏览器自动化不可用，则遵循该技能的降级路径）。

4. 定位——文件路径 + 行号、关键函数/类。

5. 可复现失败循环关卡（在提出多个根因假设之前）

   • 可复现失败循环 = 一种确定性的、可由 Agent 运行的失败复现（命令、测试或等效的已观察到的失败），且已在此分析阶段至少运行过一次并观察到失败。
   • 用户报告的症状（粘贴的日志、口头描述、截图）不算作 Agent 观察到的失败。
   • 如果缺少：不得输出推测性的多假设“可能根因”列表。首先建立该循环（复现步骤、§3 中的检测）。如果无法建立可由 Agent 运行的循环，则退出时必须明确交接给用户——根据 runtime-evidence-debug 中的人机分工，将检测手段和复现步骤交给用户——或者停止并说明缺失项；绝不能悄然通过。
   • **如果具备：**继续步骤 6。阶段输出以 §5 分析关卡输出块收尾（包含失败循环行）。

6. 根因——数据流和调用链分析；只有满足步骤 5 后，才能提出可证伪的假设。

7. 上游依赖修复评估（可选）——如果根因是上游依赖缺陷，或步骤 2 找到了已修复该问题的上游版本，则加载 upstream-dependency-debug 并遵循其流程。结果：低风险升级 → 在解决方案探索中建议升级；有风险 → 将升级与变通方案一并列出；尚未修复 → 将变通方案标记为临时方案。

8. 影响——受影响的模块/功能。

如果存在性检查失败或描述与代码不符，则不要继续探索解决方案。

分析阶段警示

• 研究路线为 🔵/🟣，但跳过已知问题快速搜索；或为 🟢，快速搜索触发条件已满足，却以“先读代码”为由跳过 WebSearch
• 根因中提到了第三方库/框架，却未先检查其上游 Changelog/Release Notes 就开始罗列变通方案
• 借“分析”之名提交修复——超出假设验证范围的临时编辑，或未回滚就进入 {next-stage}
• 未登记临时编辑，或进入 {next-stage} 前缺少「临时改动清单 + 回滚验证」
• 在没有可复现失败循环的情况下提出多个根因假设（或未明确告知用户无法建立该循环）

3. 埋点调试（运行时观察——默认入口）

基于状态的触发条件（满足任意一项；优先在进入 {next-stage} 之前触发）：

• 静态分析受阻——大致了解了模块，但无法通过阅读代码确认具体机制或路径
• 重试／继续——应用了基于静态分析的修复，但问题仍然存在
• 静默失败——调用链和日志看起来都正确，但行为有误
• 修复验证需要运行时前后证据

默认入口：任何触发条件成立时，首先加载 runtime-evidence-debug，并遵循其生命周期（升级决策 → 埋点设计 → 重现 → 证据等级 → 置信度门控 → 退出方案 → 修复验证）。入口是一个状态判断（“需要运行时观察”），而不是对自身置信度的评判；该技能自身的“优先静态分析”升级决策仍具有权威性。

按需组合场景（每项均保留自身的权威性）：

• 可通过浏览器重现 → 埋点时将工具选择委托给 browser-debug-toolkit；如果现象步骤已经通过浏览器重现，则只有在静态分析仍受阻时才继续执行
• 混合应用（原生外壳 + WebView/WKWebView/Electron + H5）→ 埋点前请参考 hybrid-debug，进行分层定位
• 真机观察 → 组合使用通道启用工具（例如，使用 android-webview-debug 建立连接）；由 runtime-evidence-debug 决定观察内容、证据等级以及何时达到足够的置信度

执行细节、置信度门控和退出方案均以各技能当前的 SKILL.md 为准——调用前请先阅读。

工具限制： ✅ 使用 Read/Grep 选择埋点位置；埋点和验证编辑遵循 §1（AI 可以添加埋点，但必须登记）；❌ 未经用户确认，不得执行重现步骤。

4. 调试验证循环（验证阶段）

如果分析阶段使用了调试技能查找根因，工作流的验证阶段必须使用同一技能验证修复（不能只依赖测试）：

• 可通过浏览器重现（browser-debug-toolkit）→ 使用同一技能；对比修复前后的运行时状态（DOM / computed style / box model / console / network）；确认异常已消失
• 运行时证据（runtime-evidence-debug）→ 重新检查原埋点位置；对比修复前后的证据；确认异常行为已消失
• 混合应用（hybrid-debug）→ 验证受影响的层（L1–L4）；确认没有新的跨层副作用

5. 分析关卡输出块（必需的阶段结束块）

此块是唯一可信来源。每个引用该块的工作流，都必须在进入 {next-stage} 前以该块结束分析阶段的输出。工作流只需用简短指针引用此块，绝不重复其字段。

【Analysis gate / 分析门控】
Red loop: ✅ <command + one-line red evidence observed this stage> / ❌ <why unestablished + handoff already proposed: instrumentation/repro steps handed to the user>
Debug entry: runtime-evidence-debug loaded (trigger: static stalled / retry / silent failure / before-after verification) / not needed (one-line Tier 1–2 evidence)
Scenario supplements: browser-debug-toolkit / hybrid-debug / channel enabler (e.g. android-webview-debug): engaged(<which>) / not needed
Temporary changes: none / <registered list + rollback verified>

规则：

• 缺少该块或块内未填写内容时，不得进入 {next-stage}——填写完整是进入的条件；若无法填写某一行（例如红色循环），这本身就是升级信号。
• 可以填写“不需要”，但必须附上一行证据；留空或含糊其辞均不可接受。
• 红色循环行遵循 §2 第 5 步（用户粘贴的证据不满足要求）；调试入口行遵循 §3（基于状态的触发条件）。

集成指南（用于引用工作流）

• 在 frontmatter dependencies 中声明 analysis-core；如果缺失，则在工作流启动时中止。
• 精简引用形式（推荐）： 使用一个简短的「委托 analysis-core」区块，包含 {next-stage} + 已知问题研究步骤映射（仅编号 + 名称）；不要重述 §§1–3 的正文，也不要重新列出分析步骤框架。
• 在工作流正文中保留： 仅编排内容——退出方式/模式、OpenSpec/Jira 接收端、刻意差异（形似神异）、难度/路径表。
• 验证阶段： 用一行指向 §4——不要粘贴调试验证要点。
• reference.md： 指向此技能以说明方法论；保留工作流专属的输出模板；不要重复门禁说明。
• 不要将刻意差异（覆盖率门禁强度、测试套件确保机制的阻断作用、行业评估 Jira 门禁等）归入此技能。