@captain_z/zsk-skills 0.1.0

package/sdlc/refactor-tasks/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: zsk:refactor-tasks
+description: Refactor task template (characterization + small-step atomic) —
+  Step 1 capture behavior baseline, Step 2 apply one Fowler technique per atomic
+  commit (revert on red), Step 3 Parallel Change for large refactors (Expand →
+  Migrate → Contract), Step 4 prepare behavior-unchanged evidence.
+category: resource
+domain: sdlc
+tier: core
+change_type: refactor
+related:
+  - ../refactor/SKILL.md
+  - ../dor-dod/SKILL.md
+  - ../task-evidence/SKILL.md
+  - ../task-tracking/SKILL.md
+triggers:
+  - refactor task template
+  - characterization baseline
+  - Fowler techniques
+  - Parallel Change tasks
+  - small atomic commits
+---
+
+# Refactor Tasks — Fowler 手法 + 小步原子 + Parallel Change
+
+> **用途**：重构的**任务列表模板**，直接复制到 `docs/{module}/tasks.md`
+> **适用**：不改变可观察行为、只改结构的重构
+> **硬原则**：**行为不变** — 重构中途改了外部行为就不是重构，是 feature 或 bug
+
+## 核心纪律
+
+### 重构触发必要性（至少一条）
+
+1. 即将新增的功能会被当前结构阻塞（**准备性重构**）
+2. 已验证的代码坏味（有度量证据）
+3. 性能瓶颈（有 profile 证据）
+4. 历史妥协已具备清理条件（依赖升级、测试补齐）
+
+**禁止**：
+- ❌ 借 bug 修复顺手重构
+- ❌ 借 feature 实现顺手重构
+- ❌ 无测试保护下的重构
+
+### Fowler 分级
+
+| 级别 | 场景 | 时长 | 本模板适用 |
+| --- | --- | --- | --- |
+| **小（Micro）** | rename / extract function / inline variable | 分钟级 | 用 `zsk:coding` 的 Skip 规则，**不走本模板** |
+| **中（Medium）** | extract / 拆模块 / 替换实现 | 小时级 | ✅ 本模板 |
+| **大（Large）** | 跨模块 / 架构迁移 | 迭代级 | ✅ 本模板 + Parallel Change |
+
+## 完整模板（复制到 `docs/{module}/tasks.md`）
+
+```md
+# Refactor Tasks: {简要描述}
+
+> 变更类型：Refactor
+> Fowler 分级：中 / 大
+> 关联文档：proposal.md（触发 + 证据）/ spec.md（行为不变契约）/ design.md（手法 + ADR）
+> 责任人：@{handle}
+> 日期：{YYYY-MM-DD}
+
+## 任务概述
+
+{触发条件 + 选用的 Fowler 手法 + 预期结构改进}
+
+## 行为不变声明（强制）
+
+- 本重构**不改变任何外部可观察行为**
+- Characterization Test 基线位置：{链接}
+- 验证方式：{回归测试 / 视觉快照 / 性能对照 / 包体积对照}
+
+## DoR（启动前门禁）
+
+见 `zsk:dor-dod` 的 **通用 + Refactor 专用** 清单。
+
+---
+
+## 执行流程
+
+### Step 1：Characterization（固化当前行为）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：{行为不变涉及的 FR 编号}
+
+子任务：
+- [ ] 1.1 抓取当前对外可观察行为快照：
+  - 测试：现有测试列表 + 覆盖率报告
+  - 视觉（前端）：当前页面截图 / Figma 对照
+  - 性能：baseline 指标（按栈选工具）
+  - 包体积（前端）：Bundle Analyzer baseline
+- [ ] 1.2 补齐缺失的 Characterization Test（现有测试不足时）
+- [ ] 1.3 确认所有测试全绿作为基线
+- [ ] 1.4 commit：`test(scope): add characterization tests for refactor`
+
+交付物：
+- 基线数据（测试 / 视觉 / 性能 / 包体积）
+- 新增 Characterization Test（如有）
+
+验证：
+- 所有测试全绿
+- 基线快照归档到 `docs/{module}/archive/{YYYY-MM-DD}-refactor-baseline/`
+
+---
+
+### Step 2：小步重构（严格 TDD + 原子 commit）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：无（行为不变）
+
+**循环执行，直至目标结构达成**：
+
+- [ ] 2.N.1 应用**一个** Fowler 手法（Extract / Inline / Move / Rename / ...）
+- [ ] 2.N.2 跑测试 → 全绿
+- [ ] 2.N.3 单独 commit：`refactor(scope): {手法 + 对象}`
+- [ ] 2.N.4 若红 → 立即 `git revert` 这一步，回到 2.N.1 重试
+- [ ] 2.N.5 若绿 → 继续下一个手法
+
+### 铁律
+
+- **一次只做一个重构**（混合重构会让回滚困难）
+- **测试不绿不提交**（绝不"先 stash 再修"）
+- **不改变外部可观察行为**（改了就不是重构）
+- **commit message 必须具名手法**：`refactor({module}): extract ChildX from ParentY`
+
+交付物：
+- 单一手法的原子 commit 序列
+
+验证：
+- `git log --oneline` 每个 commit 都独立且测试绿
+- Reviewer 可以 checkout 任一 commit，测试全绿
+
+---
+
+### Step 3（仅大重构）：Parallel Change / Strangler Fig
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：无
+
+**Parallel Change（三阶段）**：
+
+- [ ] 3.1 **Expand** — 新实现并存
+  - 新增 `NewImpl`，保留 `OldImpl`
+  - 新测试覆盖 NewImpl
+  - commit：`refactor(scope): add NewImpl (parallel with OldImpl)`
+- [ ] 3.2 **Migrate** — 调用方逐个迁移
+  - 调用方 A：Old → New（独立 PR）
+  - 调用方 B：Old → New（独立 PR）
+  - ... 每个调用方一次 PR，便于 diff 小 + 回滚容易
+- [ ] 3.3 **Contract** — 移除旧实现
+  - 删除 OldImpl
+  - 删除 Old 对应测试
+  - commit：`refactor(scope): remove OldImpl`
+
+**Strangler Fig**（替换大模块）：
+- 新模块从**边缘**开始替换旧模块
+- 旧模块**逐步失去职责**直至可移除
+- 整个过程**对外行为持续保持**
+
+交付物：
+- Parallel Change / Strangler Fig 的 commit / PR 序列
+
+验证：
+- 每个 phase 可独立部署 + 独立回滚
+
+---
+
+### Step 4：准备验收（交 verify 阶段审计）
+
+状态：`TODO`
+负责人：@{handle}
+覆盖 FR：兜底 —— 行为不变证据链
+
+子任务：
+- [ ] 4.1 跑所有现有测试 + Characterization Test → 全绿
+- [ ] 4.2 视觉回归对照（零差异，前端）
+- [ ] 4.3 性能对照（before vs after）
+- [ ] 4.4 包体积对照（前端，before vs after）
+- [ ] 4.5 对外契约对照（清单零变化）
+
+交付物：
+- 填写 `zsk:task-evidence` 的 **行为不变证据链** 表
+- 视觉 / 性能 / 体积对照报告
+
+验证：
+- 包体积变化 ≤ ±2%
+- 性能评分不回退
+- 对外契约清单零变化
+
+---
+
+## 任务依赖
+
+\`\`\`mermaid
+graph LR
+  S1[1. Characterization] --> S2[2. 小步重构]
+  S2 --> S3[3. Parallel Change?]
+  S3 --> S4[4. 验收证据]
+  S2 --> S4
+\`\`\`
+
+Step 3 仅大重构；中重构可 Step 2 → Step 4 直连。
+
+## 证据记录
+
+见 `zsk:task-evidence`，Refactor 重点填：
+- **行为不变对照表**
+- **校验记录**
+
+## 总工作量
+
+- T-shirt：`M`（中）/ `L` / `XL`（大，必须拆成多轮）
+- 人天：`{N}.{M}`
+
+---
+
+## DoD（关闭前门禁）
+
+见 `zsk:dor-dod` 的 **通用 + Refactor 专用** 清单。
+
+- [ ] 所有现有测试 + Characterization 全绿
+- [ ] 视觉回归零差异（前端）
+- [ ] 性能未回退
+- [ ] 包体积变化 ≤ ±2%（前端）
+- [ ] 对外契约零变化
+- [ ] commit 序列可逐步 replay
+- [ ] Changelog 仅 `Changed` / `Removed`，**禁止** `Added` / `Fixed`
+- [ ] ADR 从 Proposed → Accepted
+```
+
+## 大重构（L / XL）额外要求
+
+### 拆分为多轮
+
+XL 必须拆成多个 M / L 的 proposal，每个独立走完 7 阶段。
+
+### Feature Flag 保护
+
+- 大重构可用 feature flag 逐步灰度
+- **必须**在 archive 阶段登记 flag 清理计划
+
+### ADR 强制
+
+大重构必产出 ADR：
+- 触发条件 / 选定的 Fowler / Parallel Change 策略 / 替代方案 / 影响面 / 回滚方案
+
+## Skip 规则
+
+| 场景 | 可简化 |
+| --- | --- |
+| 小重构（rename / extract function） | **不走本模板**；单独 PR + 自检兜住 |
+| 中重构（单文件 extract） | 可跳 Step 3 |
+| 内部实现切换（无调用方变化） | 可跳 Step 3 的 Migrate 阶段 |
+
+## 反模式（禁止）
+
+- ❌ **一次 commit 多个手法**（无法回滚单点失败）
+- ❌ **测试不绿也 commit**（绝对禁止）
+- ❌ **重构顺带修 bug**（RCA 混入 refactor history）
+- ❌ **重构顺带加 feature**（违反行为不变）
+- ❌ **无 Characterization 直接重构**（失去基线）
+- ❌ **Parallel Change 跳过 Contract 阶段**（flag 债务累积）

package/sdlc/reviewing/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: zsk:reviewing
+description: PR code review — self-checklist, reviewer checklist, Conventional
+  Comments prefixes, technical-rigor-over-performative-agreement when receiving
+  feedback, dispute escalation path. Stage 5 of the 7-stage SDLC. This is the
+  code-view (does the diff look right); the contract-view is zsk:verify.
+category: stage
+domain: sdlc
+tier: core
+stage: 5
+variants:
+  - feature
+  - bugfix
+  - refactor
+related:
+  - ../coding/SKILL.md
+  - ../verify/SKILL.md
+  - ../../frontend/review-frontend/SKILL.md
+  - ../../quality/code-hygiene/SKILL.md
+triggers:
+  - code review
+  - PR review
+  - conventional comments
+  - receiving feedback
+  - technical rigor
+  - self review checklist
+---
+
+# Stage 5: Reviewing
+
+> **阶段定位**：代码评审 - Code Review
+> **回答的问题**：**代码写对了吗**？可读、可维护、安全、契约一致、性能无隐患
+> **与 Verify 的边界**：Reviewing 看**代码视角**（diff 有没有问题），Verify 看**契约视角**（是否满足 Spec / AC / NFR）。两者**不能互相替代**。
+> **参考规范**：Google Engineering Practices（Code Review）、Conventional Comments
+> **吸收硬原则**：
+> - **技术严谨 > 性能式同意**（Superpowers `receiving-code-review`）— 分歧先验证技术事实
+> - **证据先于断言**（Superpowers `verification-before-completion`）— 声称"没问题"前先跑命令
+> **前端专属检查项**：TS / React / 视觉 / 三语 i18n 见 [`frontend/review-frontend.md`](../../frontend/review-frontend/SKILL.md)
+
+## Skill 映射
+
+| 场景 | Primary Skill |
+| --- | --- |
+| 提交评审 | `superpowers:requesting-code-review` |
+| 接收反馈 | `superpowers:receiving-code-review`（技术严谨，避免盲目同意） |
+| 自评 | `self-review` / `check` |
+| PR / MR 评审 | `review` / `merge-review` |
+| 第二意见 | `codex review` / `codex challenge` |
+| 大型评审 | `superpowers:code-reviewer`（子代理） |
+
+## 变更类型差异
+
+| 类型 | Review 侧重 |
+| --- | --- |
+| **Feature** | 契约一致（公开接口） + 测试金字塔 + 性能 hazard |
+| **Bugfix** | RCA 合理性 + 回归测试能复现 + 无相邻破坏 + Postmortem 触发判定 |
+| **Refactor** | 行为不变证据 + 原子 commit 粒度 + Parallel Change 正确 + 性能/体积对照 |
+
+## 标准流程
+
+```text
+Author: 自评清单 → 提 MR/PR → 主动列"想让 Reviewer 关注什么"
+                                                ↓
+Reviewer: 读 Spec/Design/tasks → 按评审清单扫 diff → 按 Conventional Comments 写评论
+                                                ↓
+Author: 按技术严谨原则回应 → 有分歧先验证事实 → 必要时更新 design.md ADR
+                                                ↓
+Reviewer: re-review → Approve / Request changes
+                                                ↓
+合并前检查：verify.md 的证据链已就绪 → 进入 verify 阶段
+```
+
+## 1. 自评清单（Author，推前必过）
+
+> 这是进入 Reviewer 视野前的"最后一道自滤"。凡打 ✅ 必须是已跑过 / 已看过的证据，不是"应该没问题"。
+
+### 通用
+- [ ] `docs/{module}/spec.md` / `design.md` / `tasks.md` 已更新
+- [ ] `lint` / `type-check` 零 error（`{{config.scripts.lint}}` / `{{config.scripts.type_check}}`）
+- [ ] `test` 通过 + 覆盖率达标（`{{config.scripts.test}}`；规范见 [`quality/testing-pyramid`](../../quality/testing-pyramid/SKILL.md)）
+- [ ] 无硬编码敏感信息（见 [`quality/security-owasp`](../../quality/security-owasp/SKILL.md)）
+- [ ] 回滚方案在 `design.md` 中可执行
+- [ ] Commit 信息遵循 Conventional Commits
+- [ ] PR 描述含"为什么做 + 怎么验证"
+
+> **前端项目补**：TS 红线 / React hooks 规则 / 视觉回归 / 三语 i18n 等 → 见 [`frontend/review-frontend`](../../frontend/review-frontend/SKILL.md)
+
+### Bugfix 专用
+- [ ] 有先红后绿的测试证据（Step 1 提交 + Step 2 提交分离可见）
+- [ ] RCA 指向单一根因，非"凑巧 work"
+- [ ] 相邻场景有回归用例
+
+### Refactor 专用
+- [ ] 对外契约零变化，已在 PR 描述列对照表
+- [ ] 每个 commit 原子且绿
+- [ ] 包体积变化 ≤ ±2%（有证据链接）
+
+## 2. Reviewer 评审清单（通用）
+
+### 契约一致性
+- [ ] 公开接口与 `spec.md` 一致
+- [ ] 没有悄悄扩大公开接口
+- [ ] 类型引自约定来源（见 `system/project-constraints-template`）
+
+### 边界与错误
+- [ ] loading / empty / error 都有处理
+- [ ] 异步取消 / 竞态处理
+- [ ] 网络失败 / 超时 / 权限不足 的 fallback
+
+### 测试覆盖
+- [ ] 金字塔三层按 `design.md` 的策略就位
+- [ ] Bugfix：复现测试确实能复现（`git checkout HEAD^` 应该失败）
+- [ ] Refactor：Characterization Test 基线未被删除
+
+### 安全 / 依赖
+- [ ] 无新增敏感信息硬编码
+- [ ] 新增依赖说明合理（用途 / 许可 / 体积）
+
+### 代码风格
+- [ ] 命名能自解释
+- [ ] 没有过度注释"WHAT"，注释只写"WHY"
+- [ ] 没有未被调用的新抽象（YAGNI）
+
+## 3. Conventional Comments（评论规约）
+
+评论前缀帮助 Author 快速分类优先级：
+
+| 前缀 | 含义 | 必须改？ |
+| --- | --- | --- |
+| `blocking:` | 阻塞合并，必须解决 | ✅ |
+| `issue:` | 潜在 bug / 风险 | 🟡 讨论 |
+| `question:` | 需要解释 | 🟡 回应 |
+| `suggestion:` | 可选改进 | ⚪ 可选 |
+| `nitpick:` | 风格挑剔 | ⚪ 可选 |
+| `praise:` | 亮点表扬 | ⚪ 无需改 |
+
+示例：
+
+```text
+blocking: 公开接口 onSelect 未在 spec.md 中声明，请求合并前在 spec 加入并重新评审。
+
+suggestion: 这段依赖项过多的缓存，考虑拆成两个派生值；不影响合并。
+```
+
+## 4. Author 接收反馈（技术严谨 > 性能式同意）
+
+收到评论时**禁止**以下反模式：
+
+- "好的我改"——未理解评论就改
+- "应该没问题吧"——未验证事实就拒绝
+- "这个和这个 PR 无关"——实际影响 PR 合并的问题不能这么推
+
+正确做法：
+
+1. **先分类**：blocking / issue / suggestion / nitpick
+2. **有分歧先验证**：跑命令 / 读代码 / 查文档，用事实回应
+3. **修或不修都给理由**：`✅ 已修复` 或 `❌ 不接受，因为...（事实依据）`
+4. **升级到 Design**：如果评论触及架构决策，升级到 `design.md` 的 ADR 重新评审
+
+## 5. 第二意见（Codex / Sub-agent Review）
+
+**何时请**：
+
+- 高风险改动（安全 / 数据 / 跨系统）
+- Author 自己发起 PR 时想先做独立审查
+- Reviewer 与 Author 持续分歧 → 引入第三方视角
+
+**可用工具**：
+
+- `codex review` — OpenAI Codex 独立审查，pass/fail 门禁
+- `codex challenge` — 对抗式审查，尝试破坏代码
+- `superpowers:code-reviewer` 子代理 — 里程碑级审查
+
+**纪律**：第二意见是**参考**，不是**决策**。最终合并决定仍由 Author + Reviewer 达成。
+
+## 6. 分歧升级路径
+
+```text
+1. Author + Reviewer 讨论（评论区）
+   ↓ 仍分歧
+2. 引入 codex / 第二 Reviewer（事实澄清）
+   ↓ 仍分歧
+3. 升级到 design.md ADR（架构/风格的边界决策）
+   ↓ 仍分歧
+4. 模块负责人裁决 + 更新 SYSTEM-SPEC.md（系统级决策）
+```
+
+## 质量门禁（进入 `zsk:verify` 前）
+
+- [ ] 自评清单全绿
+- [ ] 所有 `blocking:` 评论已 resolved
+- [ ] 所有 `issue:` / `question:` 已给出书面回应
+- [ ] Reviewer Approve（至少 1 人，高风险改动 ≥ 2 人）
+- [ ] 合并轮次 ≤ 3（超出需复盘沟通效率）
+- [ ] 首轮 Review 在 1 个工作日内（SLA）
+- [ ] 有第二意见（高风险改动）
+- [ ] 前端项目：`frontend/review-frontend` 的检查项全过

package/sdlc/spec/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: zsk:spec
+description: Behavioral contract writing after proposal approval — User Stories
+  (INVEST), FR / NFR / AC numbering, BDD scenarios, edge cases, term glossary.
+  Stage 2 of the 7-stage SDLC.
+category: stage
+domain: sdlc
+tier: core
+stage: 2
+variants:
+  - feature
+  - bugfix
+  - refactor
+related:
+  - ../proposal/SKILL.md
+  - ../design/SKILL.md
+  - ../dor-dod/SKILL.md
+  - ../../frontend/spec-frontend/SKILL.md
+  - ../../meta/philosophy/SKILL.md
+triggers:
+  - writing spec
+  - user stories
+  - acceptance criteria
+  - FR NFR numbering
+  - BDD given when then
+  - behavior contract
+  - characterization test baseline
+---
+
+# Stage 2: Spec
+
+> **阶段定位**：需求设计 - Requirements Specification
+> **回答的问题**：做什么、用户会看到什么、什么算验收通过
+> **参考规范**：IEEE 830 / ISO/IEC/IEEE 29148、INVEST User Stories、Gherkin BDD
+> **与 Proposal 的边界**：Proposal 定"为什么"，Spec 定"做什么"；不进入"怎么实现"（Design 职责）
+> **前端专属扩展**：Props / Event / UE 状态矩阵 / NFR 六类见 [`frontend/spec-frontend.md`](../../frontend/spec-frontend/SKILL.md)
+
+## Skill 映射
+
+| 场景 | Primary Skill |
+| --- | --- |
+| 写规格 / 计划 | `superpowers:writing-plans` |
+| GSD 心智 | Organize（整理） |
+| 深度思考 | `think` / `sc:reflect` |
+
+## 变更类型差异
+
+| 类型 | Spec 侧重 |
+| --- | --- |
+| **Feature** | User Stories + BDD 验收 + FR/NFR/AC 编号 |
+| **Bugfix** | Expected vs Actual 行为矩阵 + 受影响的契约项 + 回归覆盖范围 |
+| **Refactor** | **行为不变**契约（Characterization Test 基线） + 公开接口保留声明 |
+
+## 标准结构
+
+1. 模块映射与事实源
+2. 术语表（Glossary） — 消除模块特有概念的歧义
+3. Why（承接 Proposal）
+4. 用户故事（User Stories, INVEST）
+5. 功能需求（FR）
+6. 非功能需求（NFR）
+7. 行为场景（BDD: Given / When / Then）
+8. Acceptance Criteria（AC）
+9. Edge Cases & Error Handling
+10. Impact
+
+## 核心要求
+
+### 1. User Stories 用 INVEST
+
+格式：`As a {角色}, I want {行为}, so that {价值}`
+
+INVEST 检查：**I**ndependent / **N**egotiable / **V**aluable / **E**stimable / **S**mall / **T**estable
+
+### 2. 验收用 BDD Given/When/Then
+
+```gherkin
+Scenario: {名称}
+  Given {前置}
+  When {动作}
+  Then {结果}
+  And {附加断言}
+```
+
+每个 P0 功能至少 1 条 Happy Path + 1 条 Edge Case。
+
+### 3. 术语表
+
+模块特有概念在首次出现或集中定义；消除"适当的 / 一些 / 可能 / 待定"等模糊词。通用术语引用 [`system/glossary.md`](../../system/glossary/SKILL.md)。
+
+### 4. 编号纪律（交叉引用追溯的基础）
+
+所有可被下游引用的条目必须**稳定编号**：
+
+- 用户故事：`US-1`、`US-2`……
+- 功能需求：`FR-1`、`FR-2`……（按 P0 → P1 → P2 顺序，不跳号）
+- 非功能需求：`NFR-1`、`NFR-2`……
+- 验收标准：`AC-1`、`AC-2`……
+
+编号一旦发布**只增不改**：
+
+- 删除功能 → 标 `FR-3 (废弃)` 而非移除编号
+- 合并功能 → 新 `FR-N` 注明 `合并自 FR-3 + FR-5`
+- 拆分功能 → 保留原编号并注明 `拆分为 FR-N, FR-N+1`
+
+这样 `design.md` 的实现映射表、`tasks.md` 的"覆盖 FR"列、后续 bugfix 的"受影响契约"才有稳定锚。
+
+### 5. NFR 基线继承
+
+NFR 章节继承 [`system/nfr-baseline.md`](../../system/nfr-baseline/SKILL.md) 的系统基线，只声明**偏离或加严**项。
+
+## Feature 型模板（通用骨架）
+
+```md
+# {模块} 规格（Specs）
+
+> 模块唯一标识：`{module-id}`
+> 变更类型：Feature
+> 原始需求文档：`{{config.paths.srs}}`
+
+## 模块映射
+## 术语表（模块特有）
+
+## Why
+## 用户故事
+- **US-1**：As a {角色}, I want {行为}, so that {价值}
+
+## 功能需求
+| 编号 | 功能 | 说明 | 优先级 | 对应 US |
+| --- | --- | --- | --- | --- |
+| FR-1 |  |  | P0 | US-1 |
+
+## 非功能需求（NFR）
+> 继承 `system/nfr-baseline.md`；此处只列偏离项。
+
+| 编号 | 类别 | 要求 | 验证方式 |
+| --- | --- | --- | --- |
+
+## 行为场景（BDD）
+### Scenario: {Happy Path}
+- Given ...
+- When ...
+- Then ...
+
+## Acceptance Criteria
+- [ ] AC-1：
+- [ ] AC-2：
+
+## Edge Cases & Error Handling
+| 场景 | 预期行为 |
+| --- | --- |
+
+## Impact
+| 受影响模块 | 影响描述 |
+| --- | --- |
+```
+
+> **前端模块**（组件 / 页面）：补 Component Public Contract + UE 状态矩阵，见 [`frontend/spec-frontend.md`](../../frontend/spec-frontend/SKILL.md)。
+
+## Bugfix 型模板
+
+```md
+# Bugfix Spec: {简要描述}
+
+> 变更类型：Bugfix
+> 关联 Proposal：`docs/{module}/proposal.md`
+> 严重度：P0 / P1 / P2 / P3
+
+## 受影响契约项
+- 涉及的 Spec 编号：`FR-X`、`NFR-Y`、`AC-Z`（引用原 spec.md 编号，稳定追溯）
+
+## Expected vs Actual（行为矩阵）
+| 场景 | 预期 | 实际（当前 bug） |
+| --- | --- | --- |
+
+## 回归测试覆盖范围
+- [ ] 本 bug 的直接场景
+- [ ] 相邻状态 / 边界场景
+- [ ] 历史回归用例是否还全绿
+
+## BDD（bug 场景）
+\`\`\`gherkin
+Scenario: {bug 场景名}
+  Given {bug 触发条件}
+  When {用户动作}
+  Then {修复后的正确行为}
+  And {不应出现的旧错误行为}
+\`\`\`
+
+## Acceptance
+- [ ] 原复现步骤走通后无 bug
+- [ ] 相邻场景未引入回归
+```
+
+## Refactor 型模板
+
+```md
+# Refactor Spec: {简要描述}
+
+> 变更类型：Refactor
+> 关联 Proposal：`docs/{module}/proposal.md`
+> Fowler 分级：小 / 中 / 大
+
+## 行为不变契约（强制）
+
+### 公开接口保留
+| 接口项 | 重构前 | 重构后 | 变化 |
+| --- | --- | --- | --- |
+
+### Characterization Test 基线
+- 基线测试位置：
+- 基线快照 / 截图：
+- 验证方式：全部保留且继续通过
+
+## 新增 / 移除的内部结构
+- 新增（内部）：...
+- 移除（内部）：...
+- 以上**不改变外部观察**
+
+## Acceptance
+- [ ] 所有现有测试全绿
+- [ ] 新增 Characterization Test 全绿
+- [ ] 视觉 / 性能 / 体积对照无回退
+```
+
+## 质量门禁
+
+- [ ] 变更类型声明明确
+- [ ] User Stories 满足 INVEST（Feature）
+- [ ] 至少 1 条 BDD Happy Path + 1 条 Edge Case（Feature）/ bug 场景（Bugfix）/ 行为不变断言（Refactor）
+- [ ] **FR / NFR / US / AC 已编号，且 P0 功能编号不跳号**
+- [ ] NFR 章节声明继承 `system/nfr-baseline.md`
+- [ ] 术语表覆盖模块特有概念
+- [ ] 无"适当 / 一些 / 可能 / 待定"模糊词
+- [ ] 前端模块：已补 `frontend/spec-frontend.md` 对应字段（Props / UE 状态矩阵）