issue-tracker

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 应主动判断并更新踩坑速查，而非直接关闭追踪台
• 负向验证：问题分类、优先级判断、追踪台格式等原有逻辑不变