@culeo/specx 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@culeo/specx",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Install specx skills to AI coding agents (Claude Code, Codex, etc.)",
   "type": "module",
   "bin": {

package/skills/specx-fix/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: specx-fix
+description: specx 流程的 bug 修复 skill — 自动判断验收 bug（场景 A）和独立 bug（场景 B），提供根因分析、修复方案、归档沉淀
+category: software-development
+tags: [specx, bugfix, debugging]
+---
+
+# specx-fix：Bug 修复
+
+## 触发条件
+
+当用户反馈 bug 相关问题时触发本 skill。不需要用户说特定的关键词，通过上下文自动判断走哪条路径。
+
+## 场景判断（自动）
+
+| 信号 | 场景 A（验收 bug） | 场景 B（独立 bug） |
+|------|-------------------|-------------------|
+| 当前有活跃子需求 `t-xxx/` | ✅ | — |
+| 当前 git 分支是 feature / 需求分支（如 `t-xxx-*`） | ✅ | — |
+| 问题在最近修改的代码范围内 | ✅ | — |
+| 问题在当前子需求的新功能范围内 | ✅ | — |
+| 当前 git 分支是 `fix/*` 或 `hotfix/*` | — | ✅ |
+| 当前 git 分支是 `main` / `master` / `maintenance` | — | ✅ |
+| 没有进行中的子需求 | — | ✅ |
+| 问题在完全不同的模块 | — | ✅ |
+
+**判断逻辑：**
+
+```
+IF 有活跃子需求 t-xxx/ AND
+   (问题在最近改动范围内 OR git 分支是需求分支 OR 问题在新功能范围内):
+  → 场景 A（验收 bug）
+ELSE：
+  → 场景 B（独立 bug）
+```
+
+---
+
+## 场景 A：验收 Bug（开发过程）
+
+### 适用条件
+
+当前正在执行 specx 流程，子需求已实现但验收时发现问题。根因可能在 spec、design 或代码实现中。
+
+### 流程
+
+#### Step A1️⃣ 定位根因环节
+
+判断问题出在哪个环节：
+
+| 根因位置 | 判断依据 | 修复动作 |
+|----------|---------|---------|
+| **spec 遗漏** | 需求定义本身就没覆盖这个场景 / 边界条件 | 更新 `02-spec.md`，然后补 design，重新执行 |
+| **design 遗漏** | spec 定义了但设计方案没覆盖 | 更新 `03-design.md`（或模板定义的文件），重新执行 |
+| **代码实现错** | spec 和 design 都对，代码写错了 | 直接修代码 |
+
+#### Step A2️⃣ 修复
+
+1. 根据根因回退到对应环节修复
+2. 更新下游文档（如果上游改了，下游必须同步）
+3. 在子需求目录下创建 bug 修复记录文件：
+
+```
+t-xxx/
+├── 00-子需求.md
+├── ...
+├── 04-tasks.md
+└── fix-001-{简短描述}.md    ← 新建
+```
+
+如果已有 `fix-001`，编号递增为 `fix-002`。
+
+##### fix-{编号}-{描述}.md 模板
+
+```markdown
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+
+# {Bug 描述}
+
+## 发现场景
+{验收时发现的问题}
+
+## 根因分析
+{定位过程}
+
+### 根因环节
+- [ ] spec 遗漏
+- [ ] design 遗漏
+- [ ] 代码实现错
+
+## 修复内容
+{描述改了哪些代码或文档}
+
+## 验证
+- [ ] 复现步骤不再触发
+- [ ] 相关功能正常
+```
+
+#### Step A3️⃣ 回到执行
+
+修复完成后，回到 `specx-executing-plans` 继续执行修改后的任务。
+
+### 场景 A 不做什么
+
+- 不创建新目录
+- 不走独立 bug 的完整文档流程
+- 不归档到 wiki（如果值得归档，等子需求完成时走 archive 流程统一沉淀）
+
+---
+
+## 场景 B：独立 Bug（线上/历史/日常）
+
+### 适用条件
+
+- 无当前需求上下文
+- 线上报障、历史代码问题、日常发现
+- 与当前进行中的需求无关
+
+### 流程
+
+#### Step B1️⃣ 创建 bug 工作空间
+
+```
+docs/specx/fixes/
+└── {yyyyMMdd}-{简短描述}/
+    ├── 00-bug-report.md       # bug 描述 & 复现步骤
+    ├── 01-root-cause.md       # 根因分析
+    ├── 02-fix-plan.md         # 修复方案
+    └── 03-fix-done.md         # 修复验证 & 归档
+```
+
+**命名规则：** `{yyyyMMdd}-{3-5单词描述}`，全小写连字符
+
+#### Step B2️⃣ 00-bug-report.md：Bug 描述
+
+```markdown
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+
+# {Bug 描述}
+
+## 发现时间
+{YYYY-MM-DD}
+
+## 发现场景
+{在哪发现的，如：线上报障、QA 提测、日常使用}
+
+## 复现步骤
+1. {步骤1}
+2. {步骤2}
+3. {步骤3}
+
+## 预期行为
+{应该是什么}
+
+## 实际行为
+{实际是什么}
+
+## 影响范围
+- [ ] 阻塞（无临时方案，必须修复）
+- [ ] 重要（有临时方案但影响体验）
+- [ ] 轻微（不影响主要流程）
+
+## 截图/日志（如有）
+```
+
+#### Step B3️⃣ 01-root-cause.md：根因分析
+
+```markdown
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+
+# 根因分析
+
+## 复现验证
+- [ ] 已确认复现
+
+## 定位过程
+{排查步骤记录}
+
+## 根因
+
+### 直接原因
+{最接近表象的原因，如：空指针、类型不匹配、边界条件缺失}
+
+### 根本原因
+{为什么会引入这个 bug，如：spec 未定义边界情况、对 API 行为假设错误、重构遗漏}
+
+## 涉及的代码位置
+- {文件路径}:{行号} — {说明}
+```
+
+#### Step B4️⃣ 02-fix-plan.md：修复方案
+
+```markdown
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+
+# 修复方案
+
+## 修复策略
+{描述修复方式}
+
+## 文件变更
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| {路径} | 修改/新增 | {说明} |
+
+## 影响分析
+- [ ] 修复会影响其他模块？哪些？
+- [ ] 需要补充单元测试？
+- [ ] 需要补充集成测试？
+
+## 回滚方案
+{如果修复有问题，如何回滚}
+```
+
+#### Step B5️⃣ 修复执行
+
+1. 按修复方案修改代码
+2. 验证修复
+3. 提交代码（建议使用 `fix/` 分支）
+
+#### Step B6️⃣ 03-fix-done.md：修复验证 & 归档
+
+```markdown
+---
+status: archived
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+  - "v2: 修复完成"
+---
+
+# 修复验证
+
+## 修复内容
+{描述实际改了哪些代码}
+
+## 验证结果
+- [ ] 复现步骤不再触发
+- [ ] 相关测试通过
+
+## 归档到 wiki
+
+### wiki 条目
+docs/specx/wiki/fixes/{slug}.md
+
+```markdown
+# {Bug 描述}
+
+**发现时间：** {YYYY-MM-DD}
+**根因类型：** {逻辑错误 / 边界遗漏 / 类型不匹配 / 并发问题 / 性能 / 其他}
+
+## 根因
+{一句话描述根因}
+
+## 修复方式
+{一句话描述修复方式}
+
+## 涉及文件
+- {文件}:{行号}
+```
+
+### 自检清单
+- [ ] bug-report 和 root-cause 已提炼为 wiki 知识
+- [ ] fix-done 状态为 `archived`
+- [ ] 相关文档状态已更新
+- [ ] 代码已提交
+```
+
+#### Step B7️⃣ 更新 fixes 目录索引
+
+首次使用 `fixes/` 时，在 `docs/specx/fixes/README.md` 创建索引：
+
+```markdown
+# Bug 修复记录
+
+| 日期 | 描述 | 根因类型 | 影响范围 | 状态 |
+|------|------|---------|---------|------|
+| {YYYY-MM-DD} | {描述} | {类型} | {阻塞/重要/轻微} | ✅ |
+```
+
+后续每次修复完成，在表格顶部插入新行。
+
+---
+
+## 公共检查清单
+
+修复完成后确认：
+
+- [ ] bug 已修复并验证
+- [ ] 根因已明确记录（区分直接原因和根本原因）
+- [ ] 修复不会引入新的问题
+- [ ] 相关测试已补充（如有必要）
+- [ ] 场景 B 已归档到 wiki
+
+## 与现有 specx skill 的关系
+
+| 当前流程 | 对应动作 |
+|----------|---------|
+| executing-plans 发现代码实现错 → 场景 A 走代码修复 | 直接在当前子需求修复 |
+| 验收发现 spec 遗漏 → 场景 A 走 spec 回退 | 更新 clarify/spec/design |
+| 验收发现 design 遗漏 → 场景 A 走 design 回退 | 更新 design 文档，重新执行 |
+| 用户报线上 bug → 场景 B | 完整流程 |
+| 日常发现历史代码 bug → 场景 B | 完整流程 |
+
+## 重要提示
+
+- **场景 A 不要过度流程化** — 验收中发现的代码小 bug，定位到根因后快速修掉，不需要走完整 fixes/ 目录。记录到当前子需求即可
+- **场景 B 必须归档到 wiki** — 独立 bug 是项目知识的重要组成部分
+- **区分直接原因和根本原因** — 直接原因是"表象"（空指针），根本原因是"为什么会引入"（spec 未定义边界）
+- **频繁出现同类 bug** → 考虑用 specx-create-rule 建立编码规范
+- **场景判断有歧义时** → 走场景 B（独立 bug 流程更完整，多走流程比漏走好）