name: issue-tracker description: 用户报告问题时的结构化拆解与追踪。将一个问题拆解为「产品设计类」和「技术实现类」，分别记录到对应的追踪文件，确保产品经理和技术架构师下次激活时能感知到未解决问题。触发词：「有个问题」「发现了bug」「这里不对」「用不了」「为什么会」「有个bug」。
问题追踪 Skill（Issue Tracker）
用户反馈的问题往往同时包含「产品设计层面的问题」和「技术实现层面的问题」。把它们混在一起处理，要么产品经理不知道，要么开发只修了代码但设计漏洞还在。
本 Skill 的作用：拆解 → 分类 → 记录到正确的地方 → 保证不被遗忘。
知识导航表（执行前必须理解的概念根）
| 层级 | 文档 | 需要理解的概念 |
|---|---|---|
| D0 认知根（必读） | _内部总控/认知结构/L1_系统性文档/产品理论维度/AI时代产品问题全景框架.md | §一 产品问题全景框架（产品设计类vs技术实现类的分类依据）；§十 各角色职责边界 |
| D3 规范参考 | — | 本 Skill 主要是分类路由，无特定规范参考 |
| D4 运行时数据 | 项目群/[项目]/产品经理/产品问题追踪台.md + 项目群/[项目]/技术架构师/技术问题追踪台.md | 写入目标（追踪台文件路径，与各角色领地一致） |
核心概念速查： ① 产品设计问题 = 「应该做什么」的疑问，需PM决策，写入产品问题追踪台 ② 技术实现问题 = 「怎么做」的疑问，AI可直接修复，写入技术问题追踪台 ③ 同一问题可能同时有两种属性（例：某功能体验不好=产品设计问题+可能的技术实现缺陷）
与相关 Skill 的区别
| 本 Skill（问题追踪） | 产品反馈处理 | 规范迭代审核 | |
|---|---|---|---|
| 触发 | 用户报告了现有功能的问题（不对、用不了、报错） | 用户提出改进想法（想要新功能） | 审核 AI 对比实现与规范的差距 |
| 核心动作 | 拆解根因 + 分类记录 | 评估是否值得做 | 更新开发规范 |
| 输出 | 产品问题追踪台 + 技术问题追踪台 | 产品定义更新 + 开发计划 | 开发规范.md |
激活后立即执行
Step 1 理解用户描述的具体问题现象（不要急于判断根因）
→ 问清楚：「你看到了什么？」「期望看到的是什么？」「怎么操作触发的？」
→ 如果现象描述不清晰，先追问，再继续
Step 2 拆解根因：判断这个问题属于哪一类（可多选）
□ 产品设计类：入口不对、流程断裂、用户感知歧义、功能缺失、交互误导
□ 技术实现类：代码 Bug、接口错误、数据写入失败、性能问题、边界情况未处理
Step 3 分类记录（见下方记录格式）
→ 产品设计类 → 写入「产品问题追踪台」
→ 技术实现类 → 写入「技术问题追踪台」
→ 两类都有 → 两个文件都写
Step 4 输出拆解结果给用户，说明：
「这个问题有两个层面：[产品层面]... [技术层面]...，已分别记录，下次处理对应模块时会自动看到。」
若问题属于「技术-产品冲突（技术无法实现某需求）」类型，且产品定义已被修改：
→ 提醒用户：「产品需求范围已变更，请在修改后说「做审核」重新触发关卡A，确保新版产品定义通过审核」
Step 5 判断是否需要立即处理
⚠️ 优先轴是「AI 确定/不确定」，P0/P1/P2 是辅助参考：
P0 + AI 确定修法（唯一技术方案）→ 立即处理，不等下次
P0 + AI 不确定（涉及产品设计 / 多方案权衡）→ 立即向用户呈现，等待决策
P1/P2 + AI 确定 → 记录进追踪台，可在当前轮次顺手修复
P1/P2 + AI 不确定 → 仅记录，不打断当前任务
若项目是 AI Agent 平台（如 tashan-openbrain），记录时标注架构层：
L1/L2/L3/L4/L5/FE（帮助 bug-fix-loop-coordinator 按层排序）
Step 6 【Bug 修复后必须执行】检查是否需要写入踩坑记录
每次修复完一个 Bug，在关闭追踪台条目之前，先问：
□ 这个 Bug 是一个可重复踩的模式吗？（下次遇到类似场景还会犯同样的错？）
□ 现有踩坑速查里有没有覆盖这类问题？
→ 是可重复模式 且 踩坑速查没有覆盖 → 立即追加到对应的踩坑速查文件：
前端问题 → `.cursor/skills/role-前端开发/knowledge/前端踩坑速查.md`
后端问题 → `.cursor/skills/role-后端开发/knowledge/后端踩坑速查.md`
部署问题 → `.cursor/skills/role-DevOps/knowledge/部署踩坑速查.md`
→ 已有覆盖 / 是一次性错误 → 不需要写，关闭追踪台条目即可
⚠️ **禁止「稍后统一补」**：踩坑记录必须在当次修复完成后立即写入，
不允许以任何理由推迟。推迟等于不写。
格式（追加一行到踩坑速查表）：
| FE-XX | [症状] | [根因] | [修复方案] |
记录格式
产品问题追踪台
文件路径：产品经理/产品问题追踪台.md（若不存在则创建）
## 产品问题追踪台
> 由 issue-tracker Skill 自动维护。
> 产品经理每次激活时读取此文件，处理「未解决」状态的问题。
| ID | 发现日期 | 问题描述 | 现象 | 影响范围 | 优先级 | 状态 | 处理记录 |
|---|---|---|---|---|---|---|---|
| PD-001 | 2026-03-19 | [一句话描述设计问题] | [用户看到了什么] | [哪个功能/用户流] | P0/P1/P2 | 未解决 | — |
状态值：未解决 / 处理中 / 已修复（产品定义已更新） / 已存档（不修复，附理由）
技术问题追踪台
文件路径：技术架构师/技术问题追踪台.md（若不存在则创建）
## 技术问题追踪台
> 由 issue-tracker Skill 自动维护。
> 技术架构师和开发角色每次激活时读取此文件，处理「未解决」状态的问题。
| ID | 发现日期 | 问题描述 | 现象/报错 | 涉及模块 | 优先级 | 状态 | 处理记录 |
|---|---|---|---|---|---|---|---|
| TC-001 | 2026-03-19 | [一句话描述技术问题] | [错误信息/行为] | [文件/函数/组件] | P0/P1/P2 | L1/L3/FE（架构层，AI平台项目填写）| 未解决 | — |
状态值：未解决 / 处理中 / 已修复（含 commit 或修改说明） / 已存档（已知限制，不修复）
优先级判断
| 优先级 | 定义 | 处理策略 |
|---|---|---|
| P0 | 阻塞核心用户路径（用户完全无法完成关键操作） | 立即处理，本次对话内解决 |
| P1 | 功能错误但有绕行方案，或影响主要体验 | 记录后尽快排期，下一个工作单元处理 |
| P2 | 体验问题、边界情况、非核心路径的异常 | 记录进追踪台，按优先级排队 |
追踪台状态机（谁负责关闭条目）
问题从「未解决」到「已修复」，必须有明确的角色负责关闭，否则追踪台会永远堆满「未解决」。
| 问题类型 | 谁写入（未解决） | 谁关闭（已修复） | 关闭时机 |
|---|---|---|---|
| 产品设计问题 | issue-tracker / 关卡A / 测试工程师 | 产品经理 | 产品定义已更新，问题已解决 |
| 技术实现问题 | issue-tracker / 关卡B / 测试工程师 | 前端/后端/AI工程师 | 代码已修复，测试工程师已验证 |
关闭格式：将对应行的「状态」列改为 已修复（2026-03-19，修复说明：xxx）
触发其他角色处理的规则
记录完成后，根据问题类型和优先级决定后续行为：
【产品设计类问题】→ 任何优先级都需要用户（产品经理/战略家）决策
P0 → 立即加载 role-产品经理 Skill，向用户呈现问题，等待指令
P1/P2 → 记录到产品追踪台，下次产品经理激活时呈现
【技术实现类问题】→ 原则上由 AI 直接处理，无需用户确认
P0 → 立即加载对应开发 Skill 直接修复，修复后通知用户结果
P1 → 直接修复，修复后通知用户结果
P2 → 直接修复，修复后通知用户结果
⚠️ 例外：如果有多个技术方案，必须先列出方案对比（见下方格式），等用户选择后再执行
多方案对比格式（有多个技术方案时必须输出）
## 技术方案对比：[问题描述]
| 方案 | 做法 | 优点 | 缺点 | 推荐程度 |
|---|---|---|---|---|
| 方案A | [具体实现] | [优点] | [缺点] | ⭐⭐⭐ |
| 方案B | [具体实现] | [优点] | [缺点] | ⭐⭐ |
**推荐**：方案A，因为 [一句话理由]。
请确认选择哪个方案，或直接说「按推荐」。
判断标准：以下情况构成「多方案」，需要用户选择：
- 两种方案在性能、安全、维护成本上有明显取舍
- 方案选择会影响后续扩展（选了 A 之后 B 就很难加）
- 涉及数据结构或接口格式的不可逆变更
以下情况不需要列方案，直接做：
- 只有一种合理做法
- 方案差异只是代码写法，无架构影响
- 明显有一个方案更优，无需讨论
与产品经理/技术架构师 Skill 的联动
产品经理激活时会读取 产品经理/产品问题追踪台.md，处理「未解决」问题。
技术架构师/开发激活时会读取 技术架构师/技术问题追踪台.md，处理「未解决」问题。
这两个读取步骤需要在对应 Skill 的「激活后立即执行」中注册（见下方说明）。
需要同步修改的其他 Skill
本 Skill 创建后，以下两个 Skill 需要在「激活后立即执行」加入读取追踪台的步骤：
role-产品经理/SKILL.md：
在 Step 1（Read 产品定义）之后，加入：
Step 1.5 Read: 产品经理/产品问题追踪台.md
→ 检查有无「未解决」的产品设计问题
→ 有 P0 → 优先处理，当前任务暂停
→ 有 P1/P2 → 纳入本次工作范围考量，视情况处理
role-技术架构师/SKILL.md：
在 Step 1（Read 产品定义）之后，加入：
Step 1.5 Read: 技术架构师/技术问题追踪台.md
→ 检查有无「未解决」的技术问题
→ 有 P0 → 优先处理
→ 有 P1/P2 → 纳入架构方案考量
role-后端开发/SKILL.md 和 role-前端开发/SKILL.md：
在 Step 1（Read 技术架构）之后，加入：
Step 1.5 Read: 技术架构师/技术问题追踪台.md
→ 检查涉及自己模块的未解决技术问题
变更记录
2026-03-19 01:35 — 初始创建
根因：在双模式开发中，发现系统存在多个真实问题（[continue] 路由不稳定、proxy_dialogs 写入机制在 StreamingResponse 生成器中的执行时机问题等），这些问题有些是产品设计层面，有些是技术实现层面，但没有统一机制将它们结构化记录下来，问题可能在对话结束后被遗忘，下次产品经理或技术架构师激活时也无法感知。
修改内容：
- 新增：本 Skill 全部内容（首次创建）
- 待执行：需要同步修改 role-产品经理、role-技术架构师、role-后端开发、role-前端开发 Skill，加入读取追踪台的步骤
验证结果：
- 本次为初始创建，验证将在第一次实际使用时执行（用一个已知问题测试：走 Step 1-4，确认两个追踪台文件都有新记录）
已知风险：追踪台文件路径依赖项目目录结构，新项目启动时需要确认 产品经理/ 和 技术架构师/ 目录已存在
2026-03-19 02:10 — 新增追踪台状态机章节（断点4配套）
根因：追踪台只有写入没有关闭规范，时间一长全是「未解决」。
修改内容：
- 新增：「追踪台状态机」章节，明确每类问题由谁写入、由谁关闭、何时关闭、关闭格式
2026-03-19 02:35 — 新增决策权归属规则 + 多方案对比格式
根因：用户明确指出技术问题 P1/P2 应由 AI 直接修复不需确认，只有产品设计/战略类问题需要用户决策；有多个技术方案时需要列出对比。原 Skill 缺少这个分层规则，导致 AI 把所有 P1/P2 记录后静默等待，没有自主处理。
修改内容：
- 修改：「触发其他角色处理的规则」→ 按问题类型（产品设计 vs 技术实现）而非优先级决定谁决策
- 新增：「多方案对比格式」章节，明确何时需要用户选择、何时直接做
- 同步：role-menu.mdc 强制规则第7条固化此原则
验证结果：
- 正向验证：下次发现技术 P1 问题，AI 应直接修复并通知用户结果，不等待指令
- 正向验证：下次发现多个技术方案，AI 应输出方案对比表等用户选择
- 负向验证：产品设计类问题仍需用户决策，不能 AI 自行修改产品定义
2026-03-22 — Step 4 补技术-产品冲突后 GATE-A 提醒（GAP-PD014-1 修复）
根因：scenario-sandbox-builder Phase 2 验证（PD-014沙盘）发现：技术-产品冲突记录后，系统缺少提醒「产品需求变更后需重新触发关卡A」的机制，导致修改后的产品定义可能未经审核就进入开发。
修改内容：
- 修改：Step 4 输出文字 → 若问题属于「技术-产品冲突（需求无法实现）」且涉及产品定义修改，追加：「产品需求范围已变更，请修改后说「做审核」重新触发关卡A」
验证方法：issue-tracker 处理技术-产品冲突时，应输出 GATE-A 重触发提醒 验证状态：🔵 待验证
2026-03-19 03:30 — 新增 Step 6：Bug 修复后检查踩坑记录
根因：BrainChat 的 sendMessage import 遗漏 Bug 修复完成后，没有任何机制提示 AI 把这个踩坑写入踩坑速查文件，导致同类问题可能再次发生。流程缺口：Bug 修复 → 追踪台关闭，但踩坑速查没有更新。
修改内容：
- 新增：激活后执行步骤中的 Step 6，在关闭追踪台条目前检查是否需要写踩坑记录，提供判断标准和写入格式
验证结果：
- 正向验证：下次 Bug 修复完，AI 应主动判断并更新踩坑速查，而非直接关闭追踪台
- 负向验证：问题分类、优先级判断、追踪台格式等原有逻辑不变