feat(skills): type-prefixed work documents and epic sub-design linking

Dogfood feedback: work/ entries like paseo-native-session-bridge.md give no clue whether they are a feature, issue, or epic when it is time to compress them. Two rules, zero new mechanism: - work docs are named with a type prefix (feat-/issue-/refactor-/epic-), so ls classifies and wrap-up knows the destination per type - epic sub-designs are inline-first: a few lines under the item entry; only risk-escalated items get their own work/feat-{slug}.md, carrying 'epic: {slug}' frontmatter with a backlink from the epic item row — flat files with two-way pointers, no subdirectories. Epic wrap-up now also sweeps its sub-item work docs. Docs (WORKFLOW/README zh+en) synced. 96 passed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-19 09:03:09 +08:00 · 2026-07-31 09:51:06 +08:00
parent 9efc569a61
commit a05ec95312
8 changed files with 14 additions and 13 deletions
@@ -158,7 +158,7 @@ CodeStable models real coding work as a set of **entities** and **flows**.
 |------|--------|
 | **attention** | A small set of project facts needed every session, kept to at most 25 entries |
 | **lessons** | One file per pitfall, technique, or research result, retrieved by keyword when relevant |
-| **work** | Active cross-session or multi-agent work; ordinary tasks create none, completed work is removed |
+| **work** | Active cross-session or multi-agent work, filenames carry a type prefix feat-/issue-/refactor-/epic-; ordinary tasks create none, completed work is removed |
 | **Project docs / ADRs** | The canonical owner for requirements, domain models, public contracts, and long-lived decisions |

 ### Flows
@@ -161,7 +161,7 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成
 |------|--------|
 | **attention** | 每次会话都要知道的少量项目事实，保持在 25 条以内 |
 | **lessons** | 一条一文件的踩坑、技巧和调研结论，靠关键词检索后按需加载 |
-| **work** | 跨会话或多人交接的活动任务；普通任务不创建，完成后清理 |
+| **work** | 跨会话或多人交接的活动任务，文件名带类型前缀 feat-/issue-/refactor-/epic-；普通任务不创建，完成后清理 |
 | **项目文档 / ADR** | 需求、领域模型、公开契约与长期技术决策的 canonical owner |

 ### 流程
@@ -40,7 +40,7 @@ a durable record; remove it when complete unless the owner asks to retain it.
 .codestable/
 ├── attention.md    # a small set of facts needed every session, at most 25 entries
 ├── lessons/        # one Markdown file per reusable lesson, searched by keyword
-└── work/           # active cross-session work, removed on completion
+└── work/           # active cross-session work, filenames carry a type prefix feat-/issue-/refactor-/epic-, removed on completion
 ```

 Skill-specific context and helpers belong to the owning skill's `references/` and `scripts/`.
@@ -35,7 +35,7 @@ bug / 行为异常    -> cs-issue ----------> cs-review（高风险或按需）
 .codestable/
 ├── attention.md    # 每次会话需要的少量项目事实，最多 25 条
 ├── lessons/        # 一条经验一个 Markdown 文件，按关键词检索
-└── work/           # 活动中的跨会话任务，完成即清
+└── work/           # 活动中的跨会话任务，文件名带类型前缀 feat-/issue-/refactor-/epic-，完成即清
 ```

 skill 专属 context 与 helper 分别由 owning skill 的 `references/` 和 `scripts/` 提供。项目
@@ -16,18 +16,19 @@ argument-hint: "[大需求描述]"

 ## Epic 文档

-epic 天然跨会话，全程维护一个 `.codestable/work/{slug}-epic.md`：
+epic 天然跨会话，全程维护一个 `.codestable/work/epic-{slug}.md`（work 文档一律带类型前缀）：

 ```markdown
 # {epic 名}
 目标 / 边界与取舍 / 验收标准

 ## 子项
- [ ] {子项一句话}（类型：feat/issue/refactor；依赖；验收要点）
+- [ ] {子项一句话}（类型：feat/issue/refactor；依赖；验收要点；设计要点就写在此条目下）
+- [ ] {高风险子项} → 设计独立落盘 [work/feat-{slug}.md](feat-{slug}.md)
 - [x] {已完成子项} → 结果一句话
 ```

-需要正式 requirement 文档时沿用项目已有位置（如 `.codestable/requirements/`），epic 文档里放指针，不复制两份。
+子项设计**就近优先**：默认写在子项条目下（几行要点即可）；只有触发风险升级信号的子项才独立落 `work/feat-{slug}.md`，其 frontmatter 标 `epic: {epic-slug}`，子项行回链——双向指针，平铺不建子目录。需要正式 requirement 文档时沿用项目已有位置（如 `.codestable/requirements/`），epic 文档里放指针，不复制两份。

 ## 硬门槛

@@ -37,5 +38,5 @@ epic 天然跨会话，全程维护一个 `.codestable/work/{slug}-epic.md`：

 ## 收尾

- 验收通过后压缩收尾：稳定结论进项目文档 / requirements，经验进 lessons，然后删除 epic work 文档（用户要求留档则保留）。
+- 验收通过后压缩收尾：稳定结论进项目文档 / requirements，经验进 lessons，然后删除 epic work 文档**及其全部子项 work 文档**（按 frontmatter `epic:` 归属收拢；用户要求留档则保留）。
 - 本轮若踩坑或被纠偏，推荐用 cs-keep 沉淀一条；用户拒绝即跳过。
@@ -21,7 +21,7 @@ argument-hint: "[功能描述]"

 ## 风险升级信号

-出现任何一条，走设计对齐再动手：把方案要点（改什么、契约变化、取舍、影响面——影响面分**必须修改 / 需要验证 / 仍待调查**三层）写入 `.codestable/work/{slug}.md` → 用 `cs-review` 的 design review 做独立审查（修复-复审最多 3 轮，超限连分歧一起上交）→ 交用户确认后动手。存在会卡死方案的技术风险时，先按风险降序垂直打通主路径再铺开（穿刺协议见 `references/code-design.md`）。信号清单：
+出现任何一条，走设计对齐再动手：把方案要点（改什么、契约变化、取舍、影响面——影响面分**必须修改 / 需要验证 / 仍待调查**三层）写入 `.codestable/work/feat-{slug}.md` → 用 `cs-review` 的 design review 做独立审查（修复-复审最多 3 轮，超限连分歧一起上交）→ 交用户确认后动手。存在会卡死方案的技术风险时，先按风险降序垂直打通主路径再铺开（穿刺协议见 `references/code-design.md`）。信号清单：

 - 公开 interface、持久化 schema 或跨模块协议变化；
 - 权限、信息安全、数据迁移、并发或不可恢复副作用；
@@ -39,6 +39,6 @@ argument-hint: "[功能描述]"
 ## 收尾

 - 报告：做了什么、改动文件、验证结果、遗留事项。
- 高风险任务的 work 文档在设计对齐时已建立；其余任务需要跨会话继续、多人交接或用户要求留痕时补建 `.codestable/work/{slug}.md`。work 文档含目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节，随进展更新（"状态与未决"记录进度与待用户确认项，供跨会话恢复）；完成后压缩要点进项目文档或 lessons 并删除，用户要求留档则保留。
- 属于某个 epic 的子功能时，完成后回报 `cs-epic` 更新其 items 状态。
+- 高风险任务的 work 文档在设计对齐时已建立；其余任务需要跨会话继续、多人交接或用户要求留痕时补建 `.codestable/work/feat-{slug}.md`（work 文档一律带类型前缀 feat- / issue- / refactor- / epic-，整理时按前缀分流去向）。work 文档含目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节，随进展更新（"状态与未决"记录进度与待用户确认项，供跨会话恢复）；完成后压缩要点进项目文档或 lessons 并删除，用户要求留档则保留。
+- 属于某个 epic 的子功能时：work 文档 frontmatter 标 `epic: {epic-slug}` 并在 epic 文档的子项行回链；完成后回报 `cs-epic` 更新其子项状态。
 - 本轮若踩坑或被纠偏，推荐用 cs-keep 沉淀一条；用户拒绝即跳过。
@@ -30,5 +30,5 @@ argument-hint: "[问题描述]"

 - 修复完成后默认用 `cs-review` 做独立审查，仅单行级微小修复可说明后跳过。
 - 报告：根因一句话、改动文件、验证结果。
- 需要跨会话继续时写 `.codestable/work/{slug}.md`（目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节）。
+- 需要跨会话继续时写 `.codestable/work/issue-{slug}.md`（目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节；work 文档一律带类型前缀）。
 - 本轮若踩了新坑或被用户纠偏，推荐用 cs-keep 沉淀一条；用户拒绝即跳过。
@@ -28,5 +28,5 @@ argument-hint: "[重构目标]"
 ## 收尾

 - 报告：改了什么结构、等价性证据（验证输出）、遗留事项。
- 需要跨会话继续时写 `.codestable/work/{slug}.md`（目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节）。
+- 需要跨会话继续时写 `.codestable/work/refactor-{slug}.md`（目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节；work 文档一律带类型前缀）。
 - 本轮若踩坑或被纠偏，推荐用 cs-keep 沉淀一条；用户拒绝即跳过。