/cs-issue

name: cs-issue
description: 诊断或修复 bug、报错、性能回退或既有行为异常。不用于新功能（cs-feat）或行为等价重构（cs-refactor）。
argument-hint: "[问题描述]"

cs-issue

把问题诊断清楚；获得修复授权时，再修根因并证明它修好了。

开工

• 有 `.codestable/attention.md` 就先读。
• 按错误信息与相关模块关键词检索 `.codestable/lessons/`、项目文档，以及存在的 v1 只读知识目录：`.codestable/roadmap/`、`.codestable/features/`、`.codestable/issues/`、`.codestable/refactors/`、`.codestable/goals/`、`.codestable/compound/`、`.codestable/audits/`、`.codestable/brainstorms/`、`.codestable/feedback/`；这个坑可能踩过，命中要报告来源路径。上述 v1 目录不得继续生成、原地改写或批量迁移，新结论按归属进入 v2 Epic、项目文档、ADR 或 lesson。
• 同一会话由 `cs` 交入且带已确认 handoff 时，直接消费目标入口、原始诉求、目标或期望行为、范围/非目标、验收、已核实仓库事实及来源、owner 已确认的术语与决策、未决风险、canonical 资产指针或资产候选；packet 精确范围内已确认的事项不重复询问。handoff 只证明当前会话共识，不扩大实现、commit、发布或写入授权，也不替代本 skill 的 review、验证与确认门槛；字段缺失、仓库事实冲突、出现会改变结果的新风险、缺少会改变方向的事实或超出已确认边界时再按本 skill 规则确认。
• 对照检查：目标（期望行为）、现场（复现条件与环境）、边界（哪些不能动）、验收（怎么算诊断清楚或修好）。缺少会改变诊断或修复方向的事实时先问用户，一次最多 3 个问题，形成共识即停。
• 诉求其实是新增能力而不是坏掉的行为时，转 `cs-feat`，不在 issue 里偷做。

模式与证据

• 用户只要求定位、分析、解释或排查时，执行只诊断；只有用户明确要求或既有授权包含修复时才改动。

诊断结论不扩大为修复授权。

• 只诊断不改产品代码、测试或配置，不创建 commit；跨会话 work 游标仍按既有规则处理。

diagnose 不新增审查阶段，无产品 diff 时不触发 change review。

• 需要新建临时 harness、日志或埋点时，先停下说明目标、路径、影响与清理方式，获得用户确认再动；

优先使用仓库外临时目录。生产或其他受控环境的临时埋点同样必须先确认。

• 两种模式都先钉住预期、实际、触发条件和环境，建立覆盖用户实际症状、可再次执行的失败信号。

diagnose 优先运行既有只读检查；新增回归测试只属于已获授权的 fix。

• 诊断只交付 `已证实根因` / `可证伪假设` / `证据不足`。`已证实根因` 必须给出至少实际运行一次、

可再次执行的命令及红色输出，或已与用户确认并至少实际完成一次的手工复现步骤及失败观察；还要用 区分性证据定位有效状态首次变无效的地方，否则降级结论。

• 没有失败信号时不猜根因、不改代码。无法建立时列明已尝试，以及所缺的日志、trace、环境访问或

临时埋点授权，再给出下一项最低成本核验。

• diagnose 终止前清理临时产物并核对工作树与仓库外临时路径，报告任何残留文件与保留理由；未清理

的诊断 diff 不得混入 fix review。同会话直接授权修复不算诊断终止，保留并沿用同一失败信号， 清理义务顺延到 fix 收尾。用户要求保留的诊断文件须列为单独 change candidate，重新确认 scope 后 审查。复杂问题的升级与可核验清理方式见 `references/debug.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` 处理，不重复确认。普通任务 只在强信号成立时展示最高价值一条，首行固定 `晶化候选：{rule}`，并给出证据、范围和建议归宿；无 强信号完全不显示模板，没有记忆写入授权时不落盘。

保障选择

`执行流程 = 最小闭环 + 每个未排除风险所要求的最少保障`。最小闭环是理解事实 → 最小完整改动 → 最窄权威验证 → 交付。选择它之前，基于目标及预计/实际触及的路径、符号、信任边界和代码外副作用， 对风险做一次静默、有界核对；不生成产物或逐项报告。一次最低成本定向核实后仍不能排除时先按风险 存在处理，或继续定向诊断到能够判定。不得以“没有注意到风险”作为降级依据。

每个新增门槛都要说明“风险事实 → 增加的保障”。一个风险只增加与它直接对应的保障，不自动启用 整套 design、全量回归、独立 review、work 文档或 Epic final acceptance 路径。行数、文件数、 文案/代码类型和 task kind 都不是风险的替代指标。用户指出“流程太重 / 只是小改动 / 文档比代码多” 时，这是重新核对风险和保障的触发信号，不是无条件跳过安全门槛。停止继续增加产物并重算；仍需 保留门槛时只说明阻止降级的具体风险。

独立 change review 不再默认发生。改变权限、安全、隐私或其他信任边界，持久化数据、schema 或迁移路径，并发、顺序或一致性语义，以及不可恢复的代码外副作用时触发；破坏兼容性、多消费者 契约、性能敏感路径或广传播面只在影响/正确性仍不确定或失败代价重大时触发；用户明确要求时也触发。 review 实际触发后才应用 `审查协议` 中的 reviewer 创建、目标冻结、lineage、findings 与轮次条款。

按风险事实最小增加保障：

• 目标、根因或实现方向仍不确定，或存在会改变结果的真实取舍 → 定向诊断、提问或 design；需要

owner 选择时确认。

• 破坏兼容性或改变多消费者依赖的公开契约 → 契约确认、对应契约测试与 canonical 文档；兼容范围

或消费者影响仍不确定时独立 review，不把所有公开 interface 改动自动视为高风险。

• 改变权限、安全、隐私或其他信任边界 → 定向威胁/安全证据与独立 review；改变 owner 授权边界时确认。
• 改变持久化数据、schema 或迁移路径 → 兼容/迁移验证、适用的备份与回滚/恢复证据、独立 review；

破坏性或不可逆时确认。

• 改变并发、顺序或一致性语义 → 对应竞态/顺序验证与独立 review；语义存在取舍时确认。
• 产生不可恢复的代码外副作用 → 执行前确认，提供适用的 dry-run、幂等、补偿或恢复证据，并独立 review。
• 性能回退或性能敏感路径变化 → 定向 profile、基线或前后对比；SLO、成本或传播范围重大/不确定时

再增加独立 review。

• 改动影响面广或失败可跨模块传播 → 扩大到受影响回归；只有消费者或失败范围仍不确定、高失败代价

等独立风险存在时才做全量验证或独立 review。

design 被触发时，最低内容写清改什么、契约变化或不变、真实取舍，并把影响面分为必须修改 / 需要验证 / 仍待调查；没有的条目明确写无。task packet 形式也必须包含这些内容。

连续性需要不是风险门槛：跨会话、多人交接或用户要求留痕只增加单一临时 work 游标。普通改动选择 成本最低且足够权威的验证；已有定向测试足够时不叠加全量套件、浏览器 smoke 与独立 review。

硬门槛

• **没有稳定、快速、能明确变红的验证，不许猜根因、不许改代码。** 优先失败测试；无法自动化时与用户确认一个手工复现步骤。
• diagnose 下“优先失败测试”指优先运行既有失败或只读检查，不新建测试文件；这里的“不许猜根因”是

指不得把假设宣称为已证实根因，diagnose 仍可按结论分级交付可证伪假设。

• 声称修复完成前，**那条变红的验证必须变绿**，并附运行输出；相关既有测试不得变红。
• **根因是有效状态第一次变成无效的地方，不是报错处**；只消除因果断点，不在症状处堆特殊分支。
• 同一修复路径失败两次，停下来重新审视根因假设，不要变着花样重试；升级手段（可证伪假设、一次一个变量）与"怀疑结构"信号见 `references/debug.md`。
• 修复中发现根因超出已授权 scope（例如必须重构或新增功能）时，先报告影响与最小选项并请 owner

决定；不得借修复擅自扩大改动。

审查协议

以下 reviewer 创建、目标冻结、lineage、findings 与轮次条款仅在 review 被触发后生效；commit / 里程碑 授权门槛始终生效。

• 当前主流程创建 reviewer 前，先发现当前会话可调用的 subagent 创建与管理能力。项目上下文有显式创建方式/model 约束时先遵守。达到审查质量基线后，优先选择与实现者异构的 agent，并显式指定最强稳定 `model`；创建方式依次使用受管理的结构化委派能力、宿主 subagent、本机有界 agent CLI 回退，不得只扫 PATH。
• 没有合格异构候选时回退同构最强模型。把最终创建方式、agent/model 与回退原因写入 task packet，禁止依赖默认模型。
• 审查前冻结一个明确目标（diff review 优先 staged diff，也可用明确 range/patch；design review 冻结对应文档版本，合法形式是仓库内已有 design 文档版本，或 task packet 内原样全文 + SHA-256；audit 冻结 commit + 范围标识），把目标标识写入 task packet。packet 形式首轮把全文与 hash 原样交给 reviewer，reviewer 审查的目标就是该文本；finding-driven follow-up 携带最新全文、前后 hash 与修复摘要。reviewer 返回前不改目标或对应工作树。有 blocking 或未被用户明确接受的 important 时不提交当前候选，也不得创建正式里程碑 commit；处理后重跑验证并重新冻结完整审查目标。
• 仅在跨会话恢复、agent 交接或隔离 reviewer 需要不可变基线时，且已有 commit 授权，才可在私有工作分支创建明确标记的 WIP/checkpoint commit；它不代表 review 通过或任务完成，交付前按仓库策略 fixup/squash。
• 本 skill 的确认与验证门槛均满足、blocking 清零且其余 important 已处理或被用户明确接受后，已有 commit 授权时才创建语义原子的正式里程碑 commit；未获授权则只报告可提交状态，不自行提交。
• 一个独立审查阶段由单一审查目的界定；design review、change review、contract review 与 Epic final acceptance 是不同阶段。只有为本阶