flamemida 语言协议：以对话语言输出——用户显式指定（含平台
language设置）优先，其次跟随用户近期消息语言；均无法判定时默认英语。落盘产物以创建时对话语言为准，增量修改保持产物既有语言。本 skill 中的固定话术是语义模板，用对话语言表达其意，不逐字照搬。
外部搜索统一入口：需要联网检索（资料、库/框架文档、时效信息）时一律先用 anysearch skill（插件内嵌），不可用再降级 WebSearch/WebFetch；降级链与派发词要求见 requirement-analysis 的 references/exploration-patterns.md。
轻量修复（Quick-Fix）
处理"已决定要修、无设计空间"的小 bug 修复与小调整，走"定位根因 → 逐题校对 → TDD 修复 → 可选验收"的最短路径；以 spec 反查与契约分流保证修复不制造文档漂移；非显然根因先取得真实诊断红信号，证据不足时交用户裁决。
开始时声明：「我正在使用 quick-fix skill 修复这个问题。」
这是最短路径，不是免设计的后门。 命中步骤 2.5 的影响范围、现行契约冲突或证据不足信号时，就把控制权交还用户、建议升级 requirement-analysis——放松的是流程重量，不是漂移防护。
定位：分诊三角里的位置
| skill | 承诺状态 | 设计空间 | 终态 |
|---|---|---|---|
| exploring | 未承诺（还在想要不要做） | — | 交接 requirement-analysis |
| quick-fix | 已承诺 + 无设计空间（小 bug、小调整） | 无 | 修复完成并验证 |
| requirement-analysis | 已承诺 + 有设计空间 | 有 | 交接 writing-plans |
拿不准档默认倾向：已承诺的开发请求、大小/设计空间拿不准时，默认先进 quick-fix——升级便宜、降级浪费；步骤 2.5 基于根因证据的升级门（含上下文交接）是安全网。与 requirement-analysis 阶段 1 小修检查的对偶表述同向。
流程（6 步）
步骤 1：接收问题 + 入口分诊自检
理解要修的 bug/调整。提出路线前按 context-reuse.md 双查已有实现与历史否决、读取适用共享术语；历史记录不替代原症状证据，已有有效决定直接消费。入口分诊自检：若发现这其实不是"无设计空间的小修"——请求措辞是新功能、涉及多个子系统、或用户还在犹豫要不要做——立即建议改用 requirement-analysis（有设计空间）或 exploring（未承诺），等待用户裁决，不硬留在 quick-fix。
修复对象边界：以同一用户症状及经证据确认的根因链为对象。多文件、多调用方、跨轮次或上下文压缩不自动拆对象；恢复沿已有证据和决定继续，跨模块修法仍走升级门。发现无关根因的旁支只记录症状、位置与后续入口；用户明确扩大范围时更新对象记录和路由，不默认顺手修。
步骤 2：定位根因 + spec 反查
- 根因定位：轻量场景主线程直查（Grep/Glob/Read）；根因不明朗时可派 1 个
code-explorer子代理只读追踪；失败先缩小范围重试 1 次，再失败主线程接管（定义见 exploration-patterns「派发要求与失败隔离」）。 - spec 反查（防漂移的第一道视野拉入）：用嫌疑改动文件反查哪些 spec 拥有它。发现范围必须与守卫逐字对齐——Grep 这五条 glob：
.spec-dev/**/spec/*-design.md、.spec-dev/**/*-design.md、docs/**/spec/*-design.md（历史位置）、docs/**/*-design.md（历史位置）、.specs/**/*.md，解析各文件 frontmatter，按coversglob 命中嫌疑文件筛出相关 spec 并读取其status——active 的把相关 Requirement/Scenario 读入上下文，其余状态按下述时效处理分流。命中 spec 的时效处理：status 为superseded的沿其 frontmattersuperseded_by跳转至 active 后继（跳转记录已访问路径集合，出现环即停下向用户报告环上文件清单；superseded_by缺失或指向不存在的文件时按无后继处理——向用户报告并仅作历史参考，不阻塞修复）；正文带Superseded-pending标注的，以其指向的新 spec 为新工作依据、旧文为已实现行为描述，两者并陈说明。被Superseded标注的 Requirement 不作为"实现偏离 spec"的修复判据；诊断存量行为时可将已取代契约作为历史参考读取——排障允许读旧契约，修复方向以现行契约为准。同一行为面出现两份 active spec 矛盾且互无取代声明时，列出双方交用户裁决（此即升级门信号之一）。命中docs/历史位置的 spec-dev 产物时，默认先自动迁移到.spec-dev/（有scripts/spec-dev/migrate-to-spec-dev.mjs则运行之，否则git mv等效迁移）并单独提交，再继续修复。这一步同时服务根因分析（spec 写着预期行为，帮判断是"实现偏离 spec"还是"spec 本身写错了"）。 - 不硬依赖 guardrail：反查是本 skill 的指令层动作（纯 Grep + 读 frontmatter），不要求目标仓库装过
check-spec-drift.mjs；若恰好装了（scripts/spec-dev/check-spec-drift.mjs存在），可顺带node scripts/spec-dev/check-spec-drift.mjs --files <改动文件>复核，属优雅降级。
诊断前置：根因非显而易见时，优先实际运行已有测试、CLI/API 或原场景回放，在根因认定前给出输入/触发条件、命令及针对原症状的失败输出。环境、鉴权、缺依赖或编译失败不算该 bug 的诊断红；先恢复条件或如实交接缺口。已有有效证据仍适用于当前代码和条件时直接复用，不强制新建测试。写新测试前先消费获批 seam，落点未定不先写某个候选测试；生产源码插桩仍受现行 TDD/例外授权约束。
显然小修：症状、具体代码条件与纠正方向唯一对应时，说明依据可免额外诊断前置；只免此步骤，后续 TDD 和例外授权仍按原规则。不能以“显然”免测或虚构失败。
有界调查与证据进展：调查前说明当前对象、手段和要获得的证据；完成后若只剩重复尝试/换措辞猜测，无支持、排除、区分候选或形成有依据新候选的证据，整理已试方法、原输出、排除项、未决条件和下一步，进入认知性升级。有新可验证线索可继续限定调查，不设固定轮数或重型循环。子代理失败与主线程明显降质分别遵循 exploration-patterns「派发要求与失败隔离」，不在此重造重试或止损规则。
步骤 2.5：升级门（用户裁决式护栏）
基于当前代码、复现和调查证据判定，允许尚未定位根因时报告证据不足；不把工具调用错误本身等同于 bug 复杂。命中以下任一即停下：
- 行为契约变更且跨越单一 spec 覆盖范围（改动会改变多个 spec 描述的行为，或需在多个 spec 间协调）；
- 跨模块改动（根因修复需要动多个模块、牵连面超出单点）；
- 引入新依赖（需要新第三方库/框架）；
- 现行契约冲突（同一行为面的两份 active spec 相互矛盾且互无取代声明，见步骤 2 的时效处理）；
- 诊断证据不足（当前有界调查结束后仍无法可靠捕获/比较原症状，或无证据进展、根因仍缺足够依据）。偶发但有实际失败样本和可比较条件可继续轻量诊断，不单因 flaky 升级；其他影响范围信号仍适用。
命中时向用户呈现两个选项：升级到 requirement-analysis / 明确坚持在 quick-fix 继续。不自动切换、不强制终止。继续只表示保留 quick-fix 流程：缺红/落点时限于获授权取证，双 spec 冲突仍先裁决；不能据此伪造根因、跳过 TDD 或绕过契约同步。升级交接保留已试方法、失败输出、候选状态和缺少条件；调用失败与产品证据不足分别记录。若用户坚持继续且修复改变契约，仍强制走步骤 5a 的 spec 同步分支——护栏放松的是流程重量，不是漂移防护。升级经用户同意后调用 requirement-analysis skill，并把已定位的根因、spec 反查结果与步骤 3 已裁决的澄清答案作为其阶段 1 输入——其阶段 2 不重查已查证部分、阶段 3 不重问已裁决问题，升级不等于重来。
步骤 3：逐题校对（一次一个问题）
提问纪律遵循 clarifying skill 的核心纪律（被引用模式，纪律定义以 clarifying 为准）：提问前自我披露、一次一题、选择题优先且推荐项放首位（Claude Code 用 AskUserQuestion）、事实自查决策交用户。核心确认三类：
- 根因认定或下一步调查方向：已唯一定位则给一个根因及证据，不凑候选；尚未唯一确定但有区分依据时给 2–3 个排序候选，各附依据和可证伪预测（若是 X，观察 Y 应出现 Z）。明确证实/待验证状态，一次只确认当前事项；用户选择调查方向不证明根因，出现反证即记录并修正。不得在修法/落点决定前改实现验证猜测；
- 修复方案选哪个（有多个修法时）；
- 本次修复是否改变 spec 描述的行为契约——这题机器判不了，必须问人，是步骤 4 分流的依据（附命中 spec 的相关小节引用供用户判断）。
步骤 4：契约影响判定（分流点）
依据步骤 3 第 3 问的答案分流。判定"改变契约"= 修复改变了某 active spec 中 Requirement/Scenario 所描述的可观察行为。改变 → 5a；不变 → 5b。
步骤 5a：TDD 修复 + 同步 spec 小节（契约改变，单 spec 内）
- 强制 TDD：失败复现 → 确认有效红 → 最小实现 → 确认绿，遵循 test-driven-development；例外清单以 test-driven-development skill 为准，按其授权纪律处理，不另设自有例外。写测试前复用获批 seam，无唯一落点时并入步骤 3 原确认，不重复询问已有决定。重构候选记录位置、理由和保护证据，交自身修复收尾；纯重构遵循 TDD「收尾纯重构」，不因此强制开启可选验收。
- 真实故障对应检查：确认获批公共 seam 覆盖真实输入、调用顺序及多调用方触发模式，不能仅以孤立纯函数绿代替真实故障。无 seam 标签但批准接口与 Scenario 唯一对应时记录来源直接消费；多候选或冲突仍并入原确认，决定前不写候选测试。只有实际调用/观察证据表明公共边界无法覆盖目标行为时，才说明具体结构障碍，沿原澄清/升级处置；共享判据见 writing-plans/references/design-principles.md。不因架构发现自动重构、制造私有接口或无测试交付。5b 同样适用。
- 同步 spec：修改命中 spec 的对应 Requirement/Scenario 小节，使其与新行为一致（不重写设计，只改被影响的那几行）。
- spec 增量提交前给用户过目：把 spec 小节改动展示给用户确认。
- 提交：spec + 代码 + 测试同一 commit，天然通过
--staged/--push/CI 守卫（spec 与代码同步）。
步骤 5b：TDD 修复 + trailer 放行（契约不变）
强制 TDD 同 5a。
不改 spec（契约没变，spec 没说谎）。
提交按守卫安装情况分两种：
- 改动未命中任何 active spec 的 covers → 普通提交即可，无需环境变量或 trailer。
- 改动命中某 active spec 的 covers → 提交用
SPEC_DEV_GUARD=off git commit执行（该环境变量注入 commit 进程，令其 pre-commit 的提交期--staged闸放行——--staged不识别 trailer，只认这个变量），并在 message 留Spec-Guard: off <原因>trailer（trailer 才是 pre-push 与 CI 区间闸的放行凭证）。环境变量管本地提交期闸、trailer 管 push/CI 区间闸，二者配合、缺一不可。
编辑期 hook 单独处理：装了 guardrail 编辑期 hook（
--hook）的仓库，因 hook 只认"文件是否命中 covers"、不认"契约是否改变"，用 Edit 类工具改 covers 覆盖文件会在编辑动作发生时就被拦。机制事实（决定放行手段）：编辑闸只检查工具载荷里的文件路径字段（Claude 只匹配 Edit/Write/NotebookEdit；Codex 虽匹配全部工具，但 shell 载荷提取不出文件路径），且 hook 进程的环境变量由平台设定——给写入命令加SPEC_DEV_GUARD=off前缀影响不到 hook 进程，不是放行手段。被拦时向用户说明"这是契约不变的内部修复"，经确认后二选一：- 改用 shell 写入落盘改动（agent 可自主执行；编辑闸天然不检查 shell 写入）。注意 Claude 的 Stop 收尾审计仍会对工作区漂移拦一次——说明后继续即可，本分支的
SPEC_DEV_GUARD=off git commit完成后工作区变干净、审计自然通过。Codex 无 Stop 审计，此路径在 Codex 侧编辑期零拦截，更要靠 trailer 留痕。 - 请用户在会话/hook 进程环境层面设
SPEC_DEV_GUARD=off（能同时覆盖编辑闸与 Stop 审计；需在启动会话的环境中设置，用完即撤，避免长期关闸）。
不静默绕过、不伪造 spec 同步。
- 改用 shell 写入落盘改动（agent 可自主执行；编辑闸天然不检查 shell 写入）。注意 Claude 的 Stop 收尾审计仍会对工作区漂移拦一次——说明后继续即可，本分支的
修复收尾（5a/5b 共用）
- 偶发复现率：仅对偶发/时序问题，按可比较的输入、环境、触发方式和观察窗口记录修复前后失败次数/运行次数及原始输出；试验次数由当前观察方案确定，不统一固定。单次绿、缩短窗口或换输入不构成可比较结果；零次失败只表示本次观察未出现，不声称概率为零。比较不足时补足原定观察或明确未验证。
- 临时插桩：本次临时日志使用可追踪唯一标识。核对源码和辅助文件的实际归属，移除本次临时插桩，或记录保留位置与理由；清理后再验证。用户原有/归属不明工作保留，归档日志中的历史标识不要求清零。持久资源继续遵循原台账与授权，不因清插桩扩大删除范围；无本次插桩记录不适用。
- 原症状回放：在处置插桩后的最终代码上重跑原始输入/完整调用链，分别记录最小回归和原场景结果。原环境不可访问时报告本地通过、原场景未验证、缺失条件与恢复下一步；仍有目标失败照实报告，不能以流程结束声称整体修复已证实。
- 根因说明：交付说明串起原症状、经证据支持的根因、改动为何有效、命令/结果和未验证边界。候选与被否定解释不冒充最终根因；有提交/PR授权时可写入相应说明，未授权时留交付总结，不为写叙事自动提交、推送或发布。
步骤 6：可选自动化验收
询问用户一次是否触发 acceptance-qa（选择题）：
- 要 → 触发 acceptance-qa skill。输入按 spec 命中情况装配：命中 active spec 则传 spec 路径 + 变更文件清单（acceptance-qa 按变更面裁剪矩阵）；未命中则由 acceptance-qa 现场生成迷你矩阵。无需改动 acceptance-qa。
- 不要 → 至少运行受影响的测试文件作为最低验证，区分"本次新增失败"与"既有失败"，结果呈现给用户，不留"没验证"空白。
收尾资源清理：修复过程创建的持久资源（测试数据/表、临时容器等，对话内记账）在验证完成后展示清单（标识 + 清理命令）请用户确认——确认后逐条清理并报告结果；婉拒则保留并说明位置与手动清理方式；无创建资源时声明"无待清理资源"。共享缓存默认保留；台账纪律细则以 writing-plans 的资源台账定义为准（有计划时：progress.yaml 的 resources 键）。
与 guardrail 的关系
skill 体系与守卫此前的唯一连接是 requirement-analysis 写 spec frontmatter 锚点。quick-fix 是第二个连接点：消费这些锚点（反查 covers/status）驱动修复决策，并在两分支上分别用"同步 spec"和"trailer 放行"与守卫协作。quick-fix 不改 guardrail 任何代码，是纯消费方 + 优雅降级。
执行环境兼容性
通用工具映射（澄清/进度/并行子任务/规范文件/搜索）以 requirement-analysis 的 codex-compat.md 工具映射总表为准（单一定义点，此处不复述）；逐题提问的 Codex 形态见 clarifying 内嵌 Codex 规范节。本 skill 自有映射：
| 用途 | Claude Code | Codex |
|---|---|---|
| 根因探索子代理 | Agent（subagent_type: code-explorer） |
spawn_agent（fork_turns: "none"）+ wait_agent |
sequential-thinking skill（插件内嵌）不可用时降级为回复中分点推演并注明工具降级原因。Codex 沙箱下 SPEC_DEV_GUARD=off git commit 与守卫交互同 Claude；沙箱禁止 commit 时请用户在沙箱外执行。
Red Flags
“一次绿就说明偶发故障消失” → 同口径前后计数，结论只覆盖实际观察
“最小测试绿了，原场景不用回放” → 单列原始症状验证，缺原条件明确未验证
“用户选了候选 A，所以 A 就是根因” → 选择不是证据，保留反证并更新结论
“没有 seam，写条架构笔记就免测交付” → 具体结构证据交原澄清/升级，TDD边界保持
"这个新功能顺手在 quick-fix 里做了吧" → 有设计空间就升级 requirement-analysis，quick-fix 不是免设计后门
"契约变了但我 trailer 放行更快" → 契约变更强制走 5a 同步 spec，trailer 只给契约不变的修复
"先改代码再补测试" → 强制 TDD，先写复现失败测试
"编辑被守卫拦了就偷偷 spec 改一行糊弄过去" → 契约不变就走 SPEC_DEV_GUARD=off + trailer，不伪造 spec 同步
"跨了三个模块但应该算小修吧" → 跨模块命中升级门，交用户裁决
"反查 glob 少写一条无所谓" → 必须与守卫五条逐字对齐，否则分流与守卫拦截面错位