/cs-epic

name: cs-epic
description: 大需求或系统级能力的路线发现、拆解与长程推进。单个功能走 cs-feat，bug 走 cs-issue。
argument-hint: "[大需求描述]"

cs-epic

把一个大需求从路线迷雾收敛成可执行契约，再逐个完成可交付子项，并让用户始终看得到全景。

开工

• 有 `.codestable/attention.md` 就先读。
• 按任务关键词在存在的 `.codestable/lessons/`、项目文档以及 v1 只读知识目录 `.codestable/roadmap/`、`.codestable/features/`、`.codestable/issues/`、`.codestable/refactors/`、`.codestable/goals/`、`.codestable/compound/`、`.codestable/audits/`、`.codestable/brainstorms/`、`.codestable/feedback/` 中 grep；命中要报告来源路径。上述 v1 目录只读，不得继续生成、原地改写或批量迁移；新结论毕业到永久 Epic、项目文档、ADR 或 lesson。
• `.codestable/requirements/` 仅在 `.codestable/attention.md` 明确记录为 canonical requirement 位置时才可维护；owner 首次指定时先把该项目事实写入 attention。未记录时只读，不存在时不新建 `.codestable/requirements/`；新项目沿用项目自身文档结构，归宿未定的稳定契约先留在永久 Epic。
• 有匹配的 `.codestable/work/epic-{slug}.md` 时先恢复：读取其永久 Epic 指针、`phase`、

`approved_revision`、`item_progression`、`milestone_commit` 与 `remote_publish`，核对 active 永久文档的 当前 SHA-256。游标未命中时，先在项目已有明确的 Epic、RFC 或 initiative 归宿中按任务关键词扫描 `status: proposed` 的在途 Epic；存在 `.codestable/epics/` 时也按相同条件扫描其中候选。两类归宿并存 时都纳入候选，项目已有归宿优先。唯一命中时只补回缺失的 planning 游标并恢复。命中多个时按 slug、 任务关键词与永久文档指针消歧；仍不能唯一确定时列出候选并请 owner 选择，不自动合并、补游标或 新建 Epic。仓库事实优先于聊天历史；hash、策略字段或仓库事实不一致时先修复或请求上下文，不创建 重复 Epic。

• 起草 proposed 永久 Epic 文档时，同时创建或复用对应 work 游标并保持 `phase: planning`、`approved_revision: pending`、`current_item: null`。
• 同一会话由 `cs` 交入且带已确认 handoff 时，直接消费目标入口、原始诉求、目标或期望行为、范围/非目标、验收、已核实仓库事实及来源、owner 已确认的术语与决策、未决风险、canonical 资产指针或资产候选；packet 精确范围内已确认的事项不重复询问。handoff 只证明当前会话共识，不扩大实现、commit、发布或写入授权，也不替代本 skill 的 review、验证与确认门槛；字段缺失、仓库事实冲突、出现会改变结果的新风险、缺少会改变方向的事实或超出已确认边界时再按本 skill 规则确认。
• handoff 只用于起草 proposed 永久 Epic 文档，不替代 fresh design review、批准 hash 或第一道 owner gate。
• 澄清需求：只问会改变拆解方向的问题（目标边界、优先级、验收口径），一次最多 3 个，形成共识即停。
• 新词、重载词或相邻概念边界会改变目标、范围、事实权威、生命周期、验收或子项契约时，读取

`references/shared-language.md`；即使不触发完整路线发现，也必须达到其中可判定的 Language Clear 条件。已有单义术语不增加章节或提问。

• 完成有界仓库调查和当前最多 3 个方向性澄清后，若仍因多个相互依赖的路线级决策而无法写出

可审查的 proposed Epic，且预计不能在当前会话收敛，路线尚不清晰时才读取 `references/wayfinding.md`。路线已清晰、只是单个局部技术未知，或仅因高风险、文件多、跨会话时跳过。

持续学习

检索到 lesson 后先做 read-repair。只做一次有界、最低成本的定向核实，优先读取已有代码、测试或 canonical 文档；不得仅为核实 lesson 运行大范围测试或反复复现。仍不足时跳过该 lesson，不阻塞正常任务。 只有 scope 符合、未退役、当前事实成立，并真实改变计划或验证，或明确排除一个具体且合理的错误路径 的条目才算有效命中；按 `经验命中：{path}（{status}）；核验：{fact}；影响：{plan_or_check}` 报告。`retired` 不应用； `observed` / `validated` 先核实再用；旧 lesson 缺 `status` 按 `observed` 读取，不批量迁移。只是相关 但没有改变行为时不制造复用证据；当前事实明确反证时立即停止应用，证据不足时不猜。

任务内只在内存保留最多 3 条候选，按新证据替换低价值项，不暂停或询问。强信号只包括：owner 纠正实际改变方案/代码/术语/验证；可复现证据推翻根因；同一路径失败两次后更换假设； blocking/important finding 暴露未编码不变量；新 red -> green 捕获可复发失败；lesson 真实改变本次行为 或被反证；重复 workaround；方法显著降低重试、成本或风险。

候选还必须同时有可追溯证据、能写成未来动作、适用于本次精确 diff 之外、且没有现成 canonical owner。网络波动、拼写、泛化口号、活动记录，以及已被机械 owner 完整覆盖的事实直接丢弃。

创建、改写规则/scope、晋升、删除与跨项目反馈仍须用户显式授权。为不中断 read-repair，仅对已有且 有效命中的 lesson 开放两种窄维护：`observed -> validated` 仅在独立后续任务确实采用并验证成功时 发生，只补一次代表性证据；必须记录 lesson 实际改变的计划或验证，或明确排除的具体且合理错误路径， 以及本次通过的验收证据。`observed|validated -> retired` 仅在当前仓库事实直接反证或发现已有 canonical owner 时发生，只写原因与替代/反证指针。窄维护不新建事实、不改规则、不扩 scope、不新增 gate，随当次代码、证据和 游标进入同一语义原子 milestone；稳定 validated 命中不写文件。需要改写结论或证据不足时只给 候选，新结论不得通过复活 retired 条目获得 validated 身份；窄维护必须在最终报告列出文件变化。

当前任务范围内能直接落成 red -> green 测试/checker 的约束优先机械化，不另写重复 lesson；会扩大 范围时只给候选。用户已明确说“记住 / 更新 / 退役”时，同轮按 `cs-keep` 处理，不重复确认。Epic 子项不展示、不询问；每个子项至多把一条去重候选写入既有游标证据区，使用 `晶化候选：{rule}` marker，最终毕业清单一次处理并复用最终 owner gate。

双层 Epic 文档

Epic 天然跨会话，但稳定上下文和活动状态不得混写：

• **永久 Epic 文档**：项目已有明确 Epic、RFC 或 initiative 归宿时沿用；否则首次创建时按需建立 `.codestable/epics/{slug}.md`，`cs-onboard` 不预建该目录。永久 Epic 文档就是唯一路线文档，proposed 阶段就是低分辨率文档内路线地图；它是起点、目标、范围、非目标、验收标准、条件式共享语言与概念边界、带稳定 ID/依赖/验收要点的子项契约、关键决策、最终交付索引、整体验收、遗留风险与长期 `status` 的唯一 owner。路线发现期间还暂存带依赖的 `待决策` 与 `尚未明确`，不新增独立 issue、map 或第三套状态。
• **执行游标**：`.codestable/work/epic-{slug}.md` 只保存永久文档指针、`approved_revision`、执行 `phase`、当前子项 ID、各 ID 进度、下一步、`blocked_by`、`item_progression`、`milestone_commit`、`remote_publish`、parallel 策略下的 `active_items` 恢复记录、临时决策及证据/commit 指针；不得复制目标、验收、子项定义或最终结论。

永久文档最小结构：

带条件注释的小节按条件创建，未触发时整节不写入。

---
status: proposed
created: YYYY-MM-DD
work: ../work/epic-{slug}.md
---
# {epic 名}
起点 / 目标 / 范围 / 非目标 / 验收标准
## 共享语言与概念边界
<!-- 仅在术语歧义会改变路线时创建；链接已有 canonical 定义，只补本 Epic 的局部边界与关系 -->
## 关键决策
- **DEC-1 · {可读名称}**：{结论与理由；证据或资产指针}
## 待决策
- **DEC-2 · {可读名称}** `[AFK|HITL]`
  - question: {一个现在能精确陈述、且会改变路线的问题}
  - depends_on: [{完整决策名称} | none]
  - method: research | owner-dialogue | prototype | prerequisite
  - evidence: {pointer | pending}
<!-- 仅在触发路线发现时创建；route clear 冻结前移除本节 -->
## 尚未明确
<!-- 仅在触发路线发现时创建；暂时无法精确陈述的路线级迷雾不分配 DEC 名称或依赖；route clear 冻结前移除本节 -->
## 子项契约
- ITEM-1：{owning skill；可交付结果；依赖；验收要点；必要的设计约束}
## 最终交付索引
## 整体验收
## 遗留风险

work 游标最小结构：

---
epic: ../epics/{slug}.md
phase: planning
approved_revision: pending
current_item: null
next_action: {one concrete next action}
blocked_by: null
item_progression: pending
milestone_commit: pending
remote_publish: pending
---
## 子项进度
- [ ] ITEM-1
## 临时决策与证据

永久 `status` 只允许 `proposed -> active -> accepted`，owner 放弃或用后继 Epic 取代时转 `cancelled` / `superseded`；work `phase` 只允许 `planning -> executing -> acceptance`，阻塞只写 `blocked_by`。

路线发现沿用 `proposed + planning + approved_revision: pending`，不新增状态；route clear 前不得保留未解决的 HITL 节点；仍有效的节点必须由 owner 明确解决或确认移入 `非目标`，只有因已确认上游决策而机械失效的节点可带依据删除，agent 不得单方判定其超出范围或失效。会改变路线的术语必须已经单义化、定义或链接到 canonical owner，子项契约使用同一词汇；未清的产品含义或概念边界仍按 HITL 处理。路线清晰、可审查、可执行时，清退 `待决策` 与 `尚未明确` 两节：只把剩余 AFK 局部未知写入对应子项契约，仅把已解决决策和下放 AFK 局部未知带来的剩余风险写入 `遗留风险`，再冻结完整 proposed Epic 并进入现有 design review。route clear 不是新的 owner gate，也不代表所有局部实现细节都已决定；判断标准见 `references/wayfinding.md`。

拆解确认本身不等于版本控制授权；首次 owner gate 同时一次性确定 `item_progression: continuous | per-item | parallel`、`milestone_commit: authorized | manual` 与 `remote_publish: each-milestone | final | manual`，说明选择 `manual` commit 会逐项暂停，并写入 work 游标。`parallel` 仅在子项契约存在依赖互不阻塞、可并行交付的子项时提供；`item_progression: parallel` 只能搭配 `milestone_commit: authorized`。`milestone_commit: manual` 只能搭配 `item_progression: per-item`；`milestone_commit: