# Issue Tracker

> 用户报告问题时的结构化拆解与追踪。将一个问题拆解为「产品设计类」和「技术实现类」，分别记录到对应的追踪文件，确保产品经理和技术架构师下次激活时能感知到未解决问题。触发词：「有个问题」「发现了bug」「这里不对」「用不了」「为什么会」「有个bug」。

- Skill: `tashangkd/issue-tracker` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add tashangkd/issue-tracker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tashangkd/issue-tracker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: TashanGKD (https://skillmd.com/u/tashangkd)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tashangkd/issue-tracker

---


# 问题追踪 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`（若不存在则创建）

```markdown
## 产品问题追踪台

> 由 issue-tracker Skill 自动维护。
> 产品经理每次激活时读取此文件，处理「未解决」状态的问题。

| ID | 发现日期 | 问题描述 | 现象 | 影响范围 | 优先级 | 状态 | 处理记录 |
|---|---|---|---|---|---|---|---|
| PD-001 | 2026-03-19 | [一句话描述设计问题] | [用户看到了什么] | [哪个功能/用户流] | P0/P1/P2 | 未解决 | — |
```

**状态值**：`未解决` / `处理中` / `已修复（产品定义已更新）` / `已存档（不修复，附理由）`

---

### 技术问题追踪台

**文件路径**：`技术架构师/技术问题追踪台.md`（若不存在则创建）

```markdown
## 技术问题追踪台

> 由 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 → 直接修复，修复后通知用户结果
  ⚠️ 例外：如果有多个技术方案，必须先列出方案对比（见下方格式），等用户选择后再执行
```

### 多方案对比格式（有多个技术方案时必须输出）

```markdown
## 技术方案对比：[问题描述]

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