Back to Details

fix-it

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fix It

Fix It

Operating contract

操作契约

Shared by every DecisionNerd/dev-skills skill. Canonical copy: 
handbook/concepts/14-operating-contract.md
.
  • Define done first. Before using tools, write the finish line in one or two lines: the acceptance criteria (existing issue AC, BDD scenarios, tests, or contract when they exist; otherwise propose them and say where they should live) and the evidence that will prove them. Re-check it before reporting done. Never report done on work you did not verify.
  • Requested scope sets the finish line. A question ("is it ready?", "why is it broken?", "what next?") ends with the answer and a 
    Next:
    line naming the exact next invoke. An outcome request ("fix", "finish", "land", "#42") continues through the chain (diagnose → fix → test → check-readiness → merge-it) until the outcome or a real blocker. Do not end a turn with "Do you want me to…?" for in-scope, in-repo work.
  • Stop only for real blockers. Stop and ask only when you cannot continue without the user, or before: deleting data or unmerged work, force-push or history rewrite, changing anything outside this repository (GitHub objects, deployments, live data, production or paid resources, external services), or leaving the requested scope, unless the user's request already named that exact action. Keep the harness's permission prompts for risky commands. Otherwise keep going and put status notes in the same message as the next action.
  • Ask well, once. For a genuine question use the harness's structured question tool when it has one (Claude Code: 
    AskUserQuestion
    ; Codex: 
    request_user_input
    when the current mode supports it) with concrete options; otherwise plain text with numbered options. Treat the answer as settled; do not re-open earlier verdicts, plans, or answers unless asked.
  • Fan out when work is parallel. Use subagents for independent reads (repo survey, evidence gathering, per-option research, per-area audits) and for independent verification (a reviewer that did not write the change). Writes stay single-owner per path set and sequential. Brief every child with goal, done-when, constraints, must-not, and return shape; verify each child's result before consolidating. Use Claude Code's 
    Workflow
    tool only for orchestration across many subagents that truly needs it; it is expensive.
  • Pick the model tier per child; defer to routing config. If the harness or user config already routes subagents (Claude Code 
    CLAUDE_CODE_SUBAGENT_MODEL
    or a CLAUDE.md rule; Codex 
    agents.default_subagent_model
    or a role's 
    agents.<name>.config_file
    ; Cursor a custom subagent's 
    model:
    frontmatter), follow it and do not pass a model. Otherwise: mechanical search or inventory → fast/cheap (Claude Code 
    haiku
    ); implementation and evidence gathering → mid (
    sonnet
    ); planning, review, adversarial verification → top (
    opus
    or 
    fable
    ). In Claude Code set it with the 
    Agent
    tool 
    model
    param or agent frontmatter 
    model:
    ; in Codex pass a spawn model or set 
    model
    in the role's config file; in Cursor set 
    model:
    (default 
    inherit
    ) in 
    .cursor/agents/*.md
    . Where the harness cannot choose, children inherit the parent model or the harness picks one (Cursor's built-in Explore/Bash/Browser subagents pick per subtask); say which in the status note.
  • Keep a checklist on long runs. For more than about five steps or work that crosses skills, keep 
    TASKS.md
    at the repo root and tick items as they finish. Do not commit it unless the repo already tracks one.
  • Close every run with three headings. 
    Blocked on me
    (the one genuine question or blocker, else "none"); 
    Changed
    (files, commits, GitHub objects, deploys, else "nothing"); 
    Found
    (evidence, verdict, and 
    Next: <exact invoke>
    ).
所有DecisionNerd/dev-skills技能通用。标准副本：
handbook/concepts/14-operating-contract.md
。
  • 先定义完成标准。 使用工具前，用一两行写明终点：验收标准（若存在现有issue的AC、BDD场景、测试或契约，则使用这些；否则提出验收标准并说明应存放的位置）以及证明达标的证据。报告完成前重新核对。未经验证的工作绝不能报告完成。
  • 请求范围决定终点。 问题类请求（「是否就绪？」「为什么损坏？」「下一步是什么？」）以答案和明确指定下一个调用的
    Next:
    行结束。结果类请求（「修复」「完成」「上线」「#42」）会沿着链路（诊断→修复→测试→check-readiness→merge-it）持续推进，直到达成结果或遇到真正的阻塞。对于范围内的仓库内工作，不要以「你是否需要我……？」结束本轮回复。
  • 仅因真正的阻塞停止。 只有在没有用户参与就无法继续时，或在以下操作前才停止并询问：删除数据或未合并的工作、强制推送或历史重写、修改本仓库外的任何内容（GitHub对象、部署、线上数据、生产或付费资源、外部服务），或超出请求范围——除非用户的请求已经明确指定了该操作。对于风险命令，保留运行框架的权限提示。否则继续推进，并将状态说明与下一步操作放在同一条消息中。
  • 一次问清楚，问到位。 对于真实问题，若运行框架有结构化提问工具（Claude Code：
    AskUserQuestion
    ；Codex：当前模式支持时使用
    request_user_input
    ），则使用该工具并提供具体选项；否则使用带编号选项的纯文本。将答案视为最终结论；除非被要求，否则不要重新讨论之前的结论、计划或答案。
  • 并行工作时拆分任务。 使用子Agent执行独立读取任务（仓库调研、证据收集、各选项研究、各领域审计）和独立验证任务（未编写变更的评审者）。写入操作按路径集保持单一负责人且串行执行。向每个子Agent简要说明目标、完成条件、约束、禁止事项和返回格式；合并前验证每个子Agent的结果。仅在确实需要编排大量子Agent时使用Claude Code的
    Workflow
    工具；该工具成本较高。
  • 为每个子Agent选择模型等级；优先遵循路由配置。 如果运行框架或用户配置已经设置了子Agent路由（Claude Code的
    CLAUDE_CODE_SUBAGENT_MODEL
    或CLAUDE.md规则；Codex的
    agents.default_subagent_model
    或角色的
    agents.<name>.config_file
    ；Cursor自定义子Agent的
    model:
    前置元数据），则遵循该配置，不要传递模型参数。否则：机械搜索或盘点→快速/低成本（Claude Code 
    haiku
    ）；实现和证据收集→中等（
    sonnet
    ）；规划、评审、对抗性验证→顶级（
    opus
    或
    fable
    ）。在Claude Code中通过
    Agent
    工具的
    model
    参数或Agent前置元数据的
    model:
    设置；在Codex中传递生成模型或在角色配置文件中设置
    model
    ；在Cursor中在
    .cursor/agents/*.md
    中设置
    model:
    （默认
    inherit
    ）。若运行框架无法选择，子Agent将继承父模型或由运行框架选择（Cursor内置的Explore/Bash/Browser子Agent会按子任务选择）；在状态说明中注明使用的模型。
  • 长流程运行时保留检查清单。 对于超过约五个步骤或跨技能的工作，在仓库根目录维护
    TASKS.md
    ，完成项后打勾。除非仓库已经跟踪该文件，否则不要提交它。
  • 每次运行结束时包含三个标题。 
    Blocked on me
    （一个真实问题或阻塞项，否则为「none」）；
    Changed
    （文件、提交、GitHub对象、部署，否则为「nothing」）；
    Found
    （证据、结论和
    Next: <具体调用>
    ）。

Goal

目标

Turn a diagnosis into a decision-complete implementation plan that another agent or engineer can execute confidently. Bridge between diagnosis (
troubleshoot-app
/ 
diagnose-bug
) and code work.
Use lightweight BDD / contracts as the repair oracle (
handbook/concepts/13-quality-trace.md
). State what should happen, where that expectation lives, whether to use/refine/create it, and how tests/evals prove it. Prefer existing DocSlime REQUIREMENTS/TESTING, issue BDD, schemas, and tests over inventing a parallel definition.
Name the quality regime for evidence (
handbook/concepts/11-quality-regimes.md
): A = contracts/golden tests; B = journeys/a11y/data-plane; C = traces/evals (hand agent/LLM product bugs to 
agents
+ Langfuse when the failure is generative). Debt labels name interest — they do not demote the pain (
12-bugs-and-debt.md
).
将诊断结果转化为决策完备的实施计划，让其他Agent或工程师可以放心执行。在诊断（
troubleshoot-app
/ 
diagnose-bug
）与代码工作之间架起桥梁。
使用轻量级BDD/契约作为修复的判定标准（
handbook/concepts/13-quality-trace.md
）。说明预期行为、该预期的存放位置、是否使用/优化/创建该预期，以及测试/评估如何证明其达标。优先使用现有的DocSlime REQUIREMENTS/TESTING、issue BDD、模式和测试，而不是凭空创建一套并行的定义。
明确证据所属的质量等级（
handbook/concepts/11-quality-regimes.md
）：A级 = 契约/黄金测试；B级 = 用户旅程/无障碍/数据平面；C级 = 链路追踪/评估（如果是生成式相关的故障，将Agent/LLM产品故障提交给
agents
+ Langfuse）。债务标签标注的是利息——它们不会降低问题的严重程度（
12-bugs-and-debt.md
）。

When NOT to use

不适用场景

  • Pure structure cleanup with no behavior change → 
    refactor-it
  • "Add tests only" with no repair → 
    test-it
  • No failing contract yet / exploring options → 
    research-it
    or 
    recon issue
  • Runaway agent thrash → 
    agents slap
    first
  • 不改变行为的纯结构清理 → 
    refactor-it
  • 仅「添加测试」而不修复 → 
    test-it
  • 尚无失效契约/正在探索选项 → 
    research-it
    或
    recon issue
  • Agent失控乱转 → 先使用
    agents slap

Required Input

所需输入

Require at least one of:
  • a prior 
    troubleshoot-app
    or 
    diagnose-bug
    diagnosis in the conversation;
  • a failing URL, screenshot, or browser-visible symptom (regime B);
  • failing inputs/tests, logs/traces/metrics, or data-plane evidence (regime A/C as applicable);
  • a clearly stated broken workflow/invariant and expected behavior.
If no concrete symptom or diagnosis exists, ask for the missing evidence before planning. Do not require a GitHub issue number.
至少需要以下一项：
  • 对话中已有
    troubleshoot-app
    或
    diagnose-bug
    的诊断结果；
  • 失效的URL、截图或浏览器可见的症状（B级）；
  • 失效的输入/测试、日志/链路/指标，或数据平面证据（根据情况为A/C级）；
  • 明确说明的故障工作流/不变量及预期行为。
如果没有具体症状或诊断结果，在规划前先询问缺失的证据。不需要必须提供GitHub issue编号。

Plan Mode

计划模式

This skill is Plan Mode friendly.
  • In Plan Mode, inspect repo and provider context read-only, then produce a plan. Do not edit code, write data, create branches, commit, push, post comments, or open PRs.
  • Outside Plan Mode the plan is execution context: continue into implementation in the same run unless the user asked for plan only.
  • If the user invokes this skill outside Plan Mode but asks for planning only, still provide the plan without mutating anything.
本技能支持计划模式。
  • 在计划模式下，以只读方式检查仓库和提供商上下文，然后生成计划。不得编辑代码、写入数据、创建分支、提交、推送、发表评论或创建PR。
  • 在计划模式外，计划是执行上下文：除非用户仅要求计划，否则在同一次运行中继续推进实施。
  • 如果用户在计划模式外调用此技能但仅要求规划，仍提供计划且不修改任何内容。

Workflow

工作流

  1. Ground in the evidence.
    • Restate the observed symptom, expected behavior, and regime (A / B / C / hybrid).
    • Carry forward the contract from diagnosis when available.
    • If diagnosis did not identify a definition, search DocSlime / requirements / TESTING / schemas / BDD / tests / issues / PRs before planning.
    • Classify the definition source as 
      Use Existing
      , 
      Refine Existing
      , or 
      Create New
      .
    • If refining or creating a definition, include the proposed Given/When/Then (or invariant) and where it should live.
    • Separate confirmed facts from inference.
    • Include relevant layers: browser/session and data-plane when UI; repro input/test + logs/traces when backend; LLM/tool traces/scores when generative.
    • If a live data source is unavailable, state what is missing and why.
  2. Inspect the repository read-only.
    • Use 
      rg
      , 
      rg --files
      , and targeted file reads to find the likely routes, components, API handlers, resolvers, jobs, schema, auth/authorization checks, telemetry, and tests.
    • Search for existing behavior definitions using relevant nouns, routes, visible labels, provider names, error text, invariant language, and test names.
    • Identify existing project conventions for validation, error handling, analytics/audit events, privacy boundaries, and test commands.
    • Check current branch/status only for planning branch steps; do not switch branches in Plan Mode.
  3. Define the repair objective.
    • State the user-visible behavior that must work after the fix.
    • Link the objective to the chosen requirement, BDD scenario, or test definition. If a new/refined definition is needed, make adding or updating that definition part of the repair objective.
    • Identify non-goals and boundaries, especially around authorization, billing, privacy, data repair, or destructive operations.
    • Call out any one remaining blocker as an Open Question; raise it through the structured question tool with options. If no blocker exists, proceed with stated assumptions.
  4. Plan implementation.
    • Prefer the smallest fix that restores the intended workflow.
    • Include the requirement/BDD/test definition update before or alongside code changes when the current definition is missing, stale, or too vague to verify.
    • Include all required code, data/model, UI, observability, documentation, and test updates.
    • Name likely files or directories only when useful for implementation safety.
    • Include any data repair or backfill as explicit planned steps, and mark whether it is live-data mutating.
    • Preserve fail-closed authorization and tenant boundaries unless the user explicitly changes the product rule.
    • Implementation fan-out: use one subagent per non-overlapping file set (mid tier) for parallel implementation; then an independent reviewer subagent (top tier) checks the diff against the Expected Behavior Definition before check-readiness.
  5. Plan validation.
    • Include tests to add or update, not only commands to run.
    • Map each linked or proposed BDD scenario to concrete evidence: automated test, manual browser verification, data-plane query, log/audit evidence, CI check, or documentation review.
    • Cover the failure mode from the diagnosis, the successful path, and security/privacy boundary cases.
    • Include manual QA when the issue is browser-visible.
    • Do not consider the plan complete unless the validation proves the linked/refined/new behavior definition.
  6. Lifecycle routing.
    • Outside Plan Mode, continue from the plan into implementation in the same run unless the user asked for plan only.
    • In Plan Mode, the harness's plan approval is the gate; do not add a textual one.
    • After implementation, run 
      check-readiness
      (read-only) as the next step.
    • After readiness, the normal shipping path is 
      merge-it
      .
  1. 基于证据落地。
    • 重述观察到的症状、预期行为和质量等级（A/B/C/混合）。
    • 若诊断中有契约，沿用该契约。
    • 如果诊断未找到定义，在规划前搜索DocSlime / 需求 / TESTING / 模式 / BDD / 测试 / issue / PR。
    • 将定义来源分类为
      Use Existing
      （使用现有）、
      Refine Existing
      （优化现有）或
      Create New
      （新建）。
    • 如果要优化或创建定义，包含提议的Given/When/Then（或不变量）及其应存放的位置。
    • 区分已确认的事实与推断。
    • 包含相关层面：UI相关时包含浏览器/会话和数据平面；后端相关时包含复现输入/测试 + 日志/链路；生成式相关时包含LLM/工具链路/评分。
    • 如果线上数据源不可用，说明缺失的内容及原因。
  2. 以只读方式检查仓库。
    • 使用
      rg
      、
      rg --files
      和针对性文件读取，查找可能的路由、组件、API处理器、解析器、任务、模式、认证/授权检查、遥测和测试。
    • 使用相关名词、路由、可见标签、提供商名称、错误文本、不变量表述和测试名称，搜索现有的行为定义。
    • 识别项目现有的验证、错误处理、分析/审计事件、隐私边界和测试命令的约定。
    • 仅在规划分支步骤时检查当前分支/状态；在计划模式下不要切换分支。
  3. 定义修复目标。
    • 说明修复后必须正常工作的用户可见行为。
    • 将目标与选定的需求、BDD场景或测试定义关联。如果需要新建/优化定义，将添加或更新该定义作为修复目标的一部分。
    • 明确非目标和边界，尤其是在授权、计费、隐私、数据修复或破坏性操作方面。
    • 将剩余的任何一个阻塞项作为「开放问题」提出；通过结构化提问工具带选项提出。如果没有阻塞项，基于陈述的假设继续推进。
  4. 规划实施。
    • 优先选择能恢复预期工作流的最小修复方案。
    • 当当前定义缺失、过时或过于模糊无法验证时，在代码变更之前或同时包含需求/BDD/测试定义的更新。
    • 包含所有必需的代码、数据/模型、UI、可观测性、文档和测试更新。
    • 仅在有助于实施安全时指明可能的文件或目录。
    • 将任何数据修复或回填作为明确的计划步骤，并标记是否会修改线上数据。
    • 保留默认拒绝的授权和租户边界，除非用户明确更改产品规则。
    • 实施拆分：对每个不重叠的文件集使用一个子Agent（中等模型等级）进行并行实施；然后由独立评审子Agent（顶级模型等级）在check-readiness前对照预期行为定义检查差异。
  5. 规划验证。
    • 包含要添加或更新的测试，而不仅仅是要运行的命令。
    • 将每个关联的或提议的BDD场景映射到具体证据：自动化测试、手动浏览器验证、数据平面查询、日志/审计证据、CI检查或文档评审。
    • 覆盖诊断中的故障模式、成功路径以及安全/隐私边界场景。
    • 如果问题是浏览器可见的，包含手动QA。
    • 除非验证能证明关联的/优化的/新建的行为定义，否则不认为计划是完整的。
  6. 生命周期路由。
    • 在计划模式外，除非用户仅要求计划，否则在同一次运行中从计划继续进入实施阶段。
    • 在计划模式下，运行框架的计划审批是门禁；不要额外添加文本式的审批询问。
    • 实施完成后，下一步运行
      check-readiness
      （只读）。
    • 就绪后，正常的上线路径是
      merge-it
      。

Output Format

输出格式

Use this shape unless the user asks otherwise:
markdown
**Observed Symptom**
<What the user sees and where.>

**Regime**
<A | B | C | hybrid — and why>

**Evidence**
- Browser/session (B): <facts or n/a>
- Repro input/test (A): <facts or n/a>
- App data/provider / logs/traces/scores: <facts or unavailable>
- Code path: <likely source files/functions>

**Diagnosis**
<Root cause and confidence. Clearly distinguish inference from confirmed evidence.>

**Expected Behavior Definition**
- Source: <existing docs/test/BDD/issue/PR path or URL, or "No suitable existing definition found">
- Decision: <Use Existing | Refine Existing | Create New>
- Scenario: <Given/When/Then summary, including where a new/refined definition should live when applicable>

**Objective**
<1-3 sentences describing the intended repaired behavior.>

**Requirements**
- <Requirement>

**Implementation Plan**
1. <Ordered implementation step with likely files/directories>
2. <Ordered implementation step>

**Observability**
- <Analytics, audit, logs, metrics, or why none are needed>

**Security And Privacy**
- <Auth/authz/tenant/billing/privacy risks and mitigations>

**Documentation**
- <Docs to update, or why none are expected>

**Testing**
- <Tests to add/update, validation commands, and BDD scenario-to-evidence mapping>

**Breakage Risks**
- <Risk plus mitigation/detection>

**Open Questions**
- <Only blockers/material ambiguities, or "None">
除非用户另有要求，否则使用以下格式：
markdown
**Observed Symptom**
<What the user sees and where.>

**Regime**
<A | B | C | hybrid — and why>

**Evidence**
- Browser/session (B): <facts or n/a>
- Repro input/test (A): <facts or n/a>
- App data/provider / logs/traces/scores: <facts or unavailable>
- Code path: <likely source files/functions>

**Diagnosis**
<Root cause and confidence. Clearly distinguish inference from confirmed evidence.>

**Expected Behavior Definition**
- Source: <existing docs/test/BDD/issue/PR path or URL, or "No suitable existing definition found">
- Decision: <Use Existing | Refine Existing | Create New>
- Scenario: <Given/When/Then summary, including where a new/refined definition should live when applicable>

**Objective**
<1-3 sentences describing the intended repaired behavior.>

**Requirements**
- <Requirement>

**Implementation Plan**
1. <Ordered implementation step with likely files/directories>
2. <Ordered implementation step>

**Observability**
- <Analytics, audit, logs, metrics, or why none are needed>

**Security And Privacy**
- <Auth/authz/tenant/billing/privacy risks and mitigations>

**Documentation**
- <Docs to update, or why none are expected>

**Testing**
- <Tests to add/update, validation commands, and BDD scenario-to-evidence mapping>

**Breakage Risks**
- <Risk plus mitigation/detection>

**Open Questions**
- <Only blockers/material ambiguities, or "None">

Blocked on me

Blocked on me

<the one genuine question or blocker, else "none">
<the one genuine question or blocker, else "none">

Changed

Changed

<files, commits, GitHub objects, deploys, else "nothing">
<files, commits, GitHub objects, deploys, else "nothing">

Found

Found

<evidence, verdict, and 
Next: check-readiness
or the appropriate next step>

Keep the plan concrete and implementation-ready. Avoid restating large raw logs, secrets, private payloads, or sensitive user data.
<evidence, verdict, and 
Next: check-readiness
or the appropriate next step>

保持计划具体且可直接实施。避免复述大量原始日志、密钥、私有载荷或敏感用户数据。

Related commands

相关命令

After diagnosis/planning, use 
issues create
if work should be tracked, 
pulls create
/ 
merge-it
to land the fix, and 
issues document
/ 
pulls document
when docs are part of the repair.
诊断/规划完成后，如果需要跟踪工作，使用
issues create
；使用
pulls create
/ 
merge-it
上线修复；如果文档是修复的一部分，使用
issues document
/ 
pulls document
。

Grounding

基础依据

This skill's TTPs are grounded in current engineering baselines (DORA, GitHub Docs, Fowler/Beck, Google SRE & SWE book, OpenTelemetry, OWASP LLM / NIST AI RMF, Diátaxis — see handbook 
sources.md
).
Smallest real repair after diagnosis (DORA small batches); evidence matches the regime (
11-quality-regimes.md
); BDD/contract from the quality trace (
13-quality-trace.md
).
Handbook card: 
handbook/practices/fix-it.md
.
本技能的TTPs基于当前工程基线（DORA、GitHub Docs、Fowler/Beck、Google SRE & SWE书籍、OpenTelemetry、OWASP LLM / NIST AI RMF、Diátaxis——参见手册
sources.md
）。
诊断后进行最小化真实修复（DORA小批量原则）；证据与质量等级匹配（
11-quality-regimes.md
）；来自质量追踪的BDD/契约（
13-quality-trace.md
）。
手册卡片：
handbook/practices/fix-it.md
。