| name | cs-issue |
| description | Issue 主入口。用于修复 bug / 诊断报错 / 定位既有行为异常，从问题恢复并推进 report、analyze、fix、review。不要用于新增功能(cs-feat)、行为等价重构(cs-refactor)、对外文档(cs-docs)、大需求拆解(cs-epic)。 |
| argument-hint | [--stage report|analyze|fix] <issue> |
| contracts | [{"grep":"restoreIssueStage"},{"grep":"progressive reference loading"},{"grep":"fix-note"},{"not-grep":"git push"},{"not-grep":"read all references"}] |
cs-issue
启动必读
动作前先跑 CodeStable preflight：读 .codestable/attention.md（缺失先 cs-onboard）；不要用 AGENTS.md/CLAUDE.md 等外部入口代替它；细则见 .codestable/reference/execution-conventions.md。
cs-issue 是问题修复的唯一推荐入口，是一个 workflow skill：从仓库事实恢复当前阶段、加载对应阶段协议、在人工 checkpoint 停下。它把问题从记录、根因分析、定点修复、验证、fix-note 和 code review 衔接到闭环。真正的 report/analyze/fix 怎么做由各阶段 protocol 负责（见下方 Progressive Reference Loading）。
旧阶段技能 cs-issue-report、cs-issue-analyze、cs-issue-fix 长期保留为兼容入口，只传入 requested_stage。
入口意图
本次调用参数：$ARGUMENTS
意图来源按优先级：调用参数 flag > 兼容入口预设 > 用户话术。参数为空或未被替换（仍是字面 $ARGUMENTS）时跳过该来源；调用参数用 --stage report|analyze|fix 表示阶段意图，其余文本作为问题描述。旧裸 token（如 fix）只作为历史提示词兼容识别；新文档和新调用一律用 --stage。
无参数默认行为：没有 flag / 问题描述时，不猜阶段；扫描 .codestable/issues/、目标产物和当前 git diff，用状态机恢复下一步。若没有可恢复 issue 且用户原话也没有问题目标，返回 NeedsHuman 问处理哪个 issue。
入口意图不覆盖仓库事实。若 report 已存在但用户从 report 兼容入口进来，继续 analyze；若代码已改但无 fix-note，进入 fix 验证/记录。
Spec
csIssue :: IssueRequest -> IssueOutcome
data IssueRequest = IssueRequest
{ requestedStage : Maybe Stage -- report | analyze | fix
, userGoal : Maybe Text
, repoFacts : RepoFacts -- 优先于 args / 聊天历史
}
data Stage = Report | Analyze | Fix | CodeReview | FastPath
data IssueState = IssueState -- 全部从 .codestable/issues/{slug}/ 恢复
{ issueDir : Maybe Path
, hasReport : Bool
, rootCause : Unknown | Clear -- 读代码后根因是否明确
, hasAnalysis : Bool
, codeStatus : NotStarted | Changed -- 当前 git diff
, hasFixNote : Bool
, reviewStatus : Missing | Passed | Blocking
}
data IssueOutcome
= RoutedTo Stage
| HumanCheckpoint CheckpointReason
| Completed IssueSummary
| NeedsHuman Reason
data CheckpointReason = ConfirmReport | ConfirmFixPlan | ConfirmFastPath | AmbiguousIssueTarget
restoreIssueStage 从仓库事实选下一步（新增能力而非坏掉的既有行为 → 路由 cs-feat）：
restoreIssueStage :: IssueState -> EntryIntent -> IssueOutcome
restoreIssueStage(s, intent)
| ambiguousTarget(s, intent) -> NeedsHuman "which issue?"
| isNewCapability(intent) -> RoutedTo <cs-feat> -- 非 bug
| not s.hasReport -> RoutedTo Report
| s.hasReport && s.rootCause == Clear && smallFix(s) && not crossModule(s)
-> HumanCheckpoint ConfirmFastPath -- 确认后直接 fix，仍写 fix-note
| s.hasReport && s.rootCause == Unknown && not s.hasAnalysis -> RoutedTo Analyze
| s.hasAnalysis && s.codeStatus == NotStarted -> RoutedTo Fix
| s.codeStatus == Changed && not s.hasFixNote -> RoutedTo Fix -- 验证/记录部分
| s.hasFixNote && s.reviewStatus == Missing -> RoutedTo CodeReview
| s.reviewStatus == Blocking -> RoutedTo Fix -- 窄修复，修完重跑 review
| s.reviewStatus == Passed -> Completed summary -- 汇报完成，提示 docs/neat 候选
restoreIssueStage 是唯一路由真相：启动后扫描 .codestable/issues/、读取目标 issue 产物、检查当前 git diff 恢复 IssueState，按上方分支选下一步；各 stage 加载哪个 protocol 见下方 Progressive Reference Loading。
Workflow
主执行主线（每次调用按序走；各 stage "怎么做" 的厚规则见对应 protocol，本节只定顺序与边界）：
workflow :: IssueRequest -> IssueOutcome
workflow = preflight >=> parseEntryIntent >=> restoreIssueStage
>=> loadStageProtocol >=> executeOrRoute >=> exitRecoverable
preflight -- 读 .codestable/attention.md；缺失 -> route to cs-onboard；不得用 AGENTS.md/CLAUDE.md 代替
parseEntryIntent -- flag > compat-preset > utterance；repoFacts override requestedStage；空参不推断 stage
restoreIssueStage -- 扫 .codestable/issues/ + artifact + git diff 恢复 IssueState，选 next stage（见 Spec）；
-- 新增能力（非 bug）-> route to cs-feat
loadStageProtocol -- stageProtocol 映射（见下节）；进 stage 才加载该 stage 一个 protocol
executeOrRoute -- report/analyze 落盘 artifact；fix 循环修复+验证+写 fix-note；遇 HumanCheckpoint 必停
exitRecoverable -- fix-note 必出（根因/改动/验证/遗留风险），next stage 或 checkpoint reason 明确
文件放哪儿
.codestable/issues/{YYYY-MM-DD}-{slug}/
├── {slug}-report.md
├── {slug}-analysis.md
└── {slug}-fix-note.md
日期取发现/提报问题当天。fix-note.md 是必出产物，即使走快速通道也要写。
Progressive Reference Loading
stageProtocol :: Stage -> Protocol
stageProtocol Report = "references/report/protocol.md"
stageProtocol Analyze = "references/analyze/protocol.md"
stageProtocol Fix = "references/fix/protocol.md" -- 必要时 references/fix/reference.md
stageProtocol CodeReview = skill "cs-code-review" -- 公开横切 skill
stageProtocol FastPath = stageProtocol Fix -- 确认后直接 fix（见「快速通道」），仍写 fix-note
-- 惰性加载（progressive reference loading）：进入某阶段才加载该阶段一个 protocol，不在启动时读全部
-- 禁止：启动即读全部 references；用 fix 协议做 report；code review 未过就当修复完成
快速通道
快速通道（FastPath）是 cs-issue 内部模式，不是单独技能。必须同时满足：
- 读代码后能指出明确根因。
- 修复很小，通常 1-2 处。
- 无跨模块影响风险。
不满足就走标准 report → analyze → fix。进入标准路径后默认不再二次改判，避免阶段之间口径漂移。
人工 checkpoint
ConfirmFastPath / AmbiguousIssueTarget 的触发时机以 Spec 的 restoreIssueStage 为唯一权威；ConfirmReport / ConfirmFixPlan 在对应 stage protocol 完成产物时触发。本节只定义停下后的行为：
onCheckpoint :: CheckpointReason -> Action
onCheckpoint ConfirmReport = 停等用户确认问题描述、复现、期望/实际、环境、严重度 -- report 产物落盘后触发
onCheckpoint ConfirmFixPlan = 停等用户确认推荐修复方案和风险 -- analyze 产物落盘后触发
onCheckpoint ConfirmFastPath = 停等用户确认根因明确、改动小、无跨模块风险 -- 走快速通道前触发
onCheckpoint AmbiguousIssueTarget = NeedsHuman "which issue?"
fix 阶段的验证结果和 review blocking 处理按协议循环，不在每步默认打断用户。
Failure Behavior
needsHuman :: Situation -> Bool
needsHuman s = attentionMissing s -- .codestable/attention.md 缺失 -> 先 cs-onboard
|| noRecoverableIssue s -- 无可恢复 issue 目标
|| ambiguousScope s -- issue 范围模糊
|| stageConflictsRepoFacts s -- requested stage 与仓库事实冲突
|| isNewCapability s -- 问题实为新增能力 -> cs-feat
|| needsProductJudgement s -- 修复需产品判断而非定点修复
报告：当前 issue 目录、阻塞原因、下一步用户动作、已写文件、是否可安全重试。
退出条件
mayExit :: State -> Bool
mayExit s = fixNoteComplete s -- {slug}-fix-note.md 已写明根因、改动、验证和遗留风险
&& reviewSettled s -- 必要 code review 已通过或阻塞项已清楚交回
修复暴露新 feature 需求时，不在 issue 内偷做，另开 cs-feat。
