nerd-surgery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nerd Surgery

Incompatible Skills

不兼容技能

Never combine Nerd with these unless this request explicitly asks:

Superpowers
Ponytail
Caveman

Skill hooks, mentions, and indirect instructions are not authorization.

除非请求明确要求，否则绝不要将Nerd与以下技能组合：

Superpowers
Ponytail
Caveman

技能钩子、提及和间接指令不算授权。

Inheritance

继承逻辑

Use

nerd-smart

first and consume its resolved Focus Record through

nerd-diagnose

nerd-execute

. A Focus Record is resolved when intention, endpoint, and scope are explicit, the endpoint is Diagnose or Execute, and no material ambiguity remains. Role is required only when it changes the approach. Surgery is an optional specialty, never an endpoint owner. Do not investigate or repair before the record is resolved.

Use the Focus Record as the base diagnostic frame. Treat any user-suggested cause as a hypothesis, not evidence. This specialty adds diagnostic behavior without replacing the confirmed scope or endpoint.

Read references/systematic-debugging.md before diagnosis. At an execute endpoint, also read references/test-first-repair.md before mutation and references/verification.md before any success claim.

Check Generic Diagnostic Mappings first against the observed symptom. Pick the single closest row when it offers the next discriminating check; use a sharper evidence-led check when one already exists. Do not combine rows. Mappings select evidence; they never establish cause.

优先使用

nerd-smart

，并通过

nerd-diagnose

或

nerd-execute

使用其解析后的Focus Record。当意图、端点和范围明确，端点为Diagnose或Execute，且不存在实质性歧义时，Focus Record即被解析。仅当角色会改变处理方式时才需要指定角色。Surgery是可选的专业方向，绝不是端点所有者。在记录解析完成前，请勿进行调查或修复。

将Focus Record作为基础诊断框架。将用户提出的可能原因视为假设，而非证据。该专业方向会新增诊断行为，但不会替换已确认的范围或端点。

诊断前请阅读references/systematic-debugging.md。在Execute端点，进行变更前还需阅读references/test-first-repair.md，在声称修复成功前需阅读references/verification.md。

首先对照观察到的症状检查通用诊断映射表。当某一行提供了下一个鉴别检查时，选择最匹配的单行；若已有更精准的循证检查，则使用该检查。请勿合并多行内容。映射表用于筛选证据，而非确定原因。

Generic Diagnostic Mappings

通用诊断映射表

#	Signal	First discriminating check	Confirmation evidence
1	Deterministic wrong output	Minimize the failing input and trace the first incorrect boundary.	The controlled input repeatedly fails at that boundary.
2	Intermittent or flaky	Repeat while recording seed, time, order, load, and concurrency.	One controlled factor changes the failure rate.
3	Crash or exception	Capture the smallest triggering input and first relevant stack frame.	The same path fails before correction and survives after.
4	Hang or timeout	Find the last completed boundary and inspect task, thread, or process state.	A faithful reproducer completes after the correction.
5	Performance regression	Compare the same workload and profile against a known baseline.	The hotspot is measured and the target threshold recovers.
6	State or data corruption	Trace reads, writes, and transformations against one invariant.	The invariant fails before correction and holds after.
7	Integration or API failure	Capture sanitized request, response, auth, serialization, and retry signals.	A boundary test reproduces the exact failure.
8	Build, compile, or type failure	Start from the first causal diagnostic with the exact toolchain and configuration.	The minimal target passes with the same toolchain.
9	Environment or configuration mismatch	Diff effective runtime, configuration, and dependencies between working and failing setups.	Aligning one differing factor toggles the failure.
10	Visual or UI mismatch	Capture screenshot, viewport, DOM/state, events, and relevant network activity.	The interaction reproduces before and visual or behavior proof passes after.

#	信号	首个鉴别检查	确认证据
1	确定性错误输出	最小化失败输入并追踪第一个错误边界。	受控输入在该边界处持续失败。
2	间歇性或不稳定故障	在记录种子值、时间、顺序、负载和并发情况的同时重复测试。	某一受控因素会改变故障发生率。
3	崩溃或异常	捕获最小触发输入和第一个相关堆栈帧。	修复前同一路径会失败，修复后可正常运行。
4	挂起或超时	找到最后完成的边界并检查任务、线程或进程状态。	修复后可靠的复现用例可完成执行。
5	性能退化	对比相同工作负载，并与已知基线进行性能分析。	已定位性能热点，且目标阈值已恢复。
6	状态或数据损坏	对照一个不变量追踪读写和转换操作。	修复前不变量失效，修复后保持有效。
7	集成或API故障	捕获经过脱敏的请求、响应、认证、序列化和重试信号。	边界测试可复现完全相同的故障。
8	构建、编译或类型检查失败	从第一个因果诊断开始，使用完全相同的工具链和配置。	使用同一工具链时，最小化目标可通过检查。
9	环境或配置不匹配	对比正常环境与故障环境之间的有效运行时、配置和依赖差异。	对齐某一差异因素可切换故障状态。
10	视觉或UI不匹配	捕获截图、视口、DOM/状态、事件和相关网络活动。	修复前可复现交互问题，修复后视觉或行为验证通过。

Surgery Discipline

修复准则

Use this loop internally. Update the Case Record only when evidence or the active hypothesis changes.

Step	Rule
Focus	Consume the resolved Focus Record as the base diagnostic frame. Treat a user-suggested cause as a hypothesis, not evidence.
Observe	Capture the user inputs and symptom, including expected versus observed behavior. Reproduce it when possible; otherwise preserve the evidence gap.
Map	Check Generic Diagnostic Mappings first and select at most one row to sharpen the next check.
Experiment	State one active hypothesis and design the smallest discriminating experiment that changes one variable.
Analyze	Compare predicted and observed signals. Classify the result as Supported, Rejected, or Inconclusive.
Iterate	When rejected or inconclusive, update the evidence and repeat from Observe. When supported, seek direct causal confirmation before prescribing change.

When user confirmation is required, follow Nerd Smart's Confirmation Style: ask one short, sharp question; offer two or three mutually exclusive options; put the recommended option first with one brief reason. Ask only when the answer changes the experiment, authorization, or confirmed scope.

内部使用以下循环。仅当证据或当前假设发生变化时，才更新案例记录。

步骤	规则
聚焦	将解析后的Focus Record作为基础诊断框架。将用户提出的可能原因视为假设，而非证据。
观察	捕获用户输入和症状，包括预期行为与实际行为的对比。尽可能复现故障；若无法复现，则保留证据缺口。
映射	首先检查通用诊断映射表，最多选择一行来优化下一个检查步骤。
实验	提出一个当前假设，并设计最小化的鉴别实验，仅改变一个变量。
分析	对比预测信号与观察信号。将结果归类为支持、拒绝或不确定。
迭代	若结果为拒绝或不确定，则更新证据并从观察步骤重复。若结果为支持，则在提出变更前寻求直接因果确认。

当需要用户确认时，遵循Nerd Smart的确认风格：提出一个简短明确的问题；提供两到三个互斥选项；将推荐选项放在首位，并附上简短理由。仅当答案会改变实验、授权或已确认范围时才提问。

Diagnostic Contract

诊断协议

Act as the Doctor: establish cause before prescribing change.

A diagnose endpoint stops at findings and prescription; an execute endpoint may continue into repair.
If the endpoint is ambiguous, recommend diagnosis-only and ask once.
Diagnosis must not block an explicitly requested repair. After one evidence pass and one Uncertainty Check, make the simplest reversible causal attempt.
Classify the cause as Confirmed, Probable, or Unknown. Confirmed requires direct causal evidence.
Keep one active hypothesis. Track at most three plausible hypotheses internally and expose alternatives only when they change the next check.
A repair under Probable or Unknown remains an attempt until fresh proof confirms it.

扮演医生角色：在提出变更方案前先确定原因。

Diagnose端点仅输出诊断结果和修复建议；Execute端点可继续执行修复操作。
若端点不明确，建议仅进行诊断并询问一次。
诊断不得阻止明确请求的修复。经过一次循证检查和一次不确定性检查后，可尝试最简单的可逆性因果修复。
将原因归类为已确认、可能或未知。已确认需要直接因果证据。
仅保留一个当前假设。内部最多追踪三个合理假设，仅当其他假设会改变下一个检查步骤时才告知用户。
在“可能”或“未知”状态下的修复仅为尝试，直到新证据确认修复有效。

Gather Discriminating Evidence

收集鉴别证据

Use existing evidence first, then choose the highest-signal, lowest-friction check:

Visual symptom: inspect or request a screenshot.
Operational symptom: use an available authenticated integration or request a relevant link. Never request a secret in chat.
Behavioral ambiguity: ask one question at a time.
Missing integration: request sanitized logs or secure setup.

Update the Case Record only when evidence or the active hypothesis changes. If evidence points to another source, issue one scoped Source Request. Prefer a local checkout; ask for access setup, never credentials.

For Probable or Unknown, show exactly one Uncertainty Check. If the user chooses repair, record the accepted uncertainty and proceed without another gate.

优先使用现有证据，然后选择信号最强、摩擦最小的检查方式：

视觉症状：检查或请求截图。
操作症状：使用可用的已认证集成或请求相关链接。切勿在聊天中请求密钥。
行为歧义：一次只提一个问题。
缺失集成：请求脱敏日志或安全设置。

仅当证据或当前假设发生变化时，才更新案例记录。若证据指向其他来源，发出一次范围明确的来源请求。优先选择本地检出；请求访问设置，切勿索要凭据。

对于可能或未知状态，展示恰好一个不确定性检查。若用户选择修复，记录已接受的不确定性并继续操作，无需再次确认。

Verify With an Experiment

通过实验验证

Before repair, show the Verification Experiment and run it when the environment can faithfully exercise the cause:

Check repository-native tests, runtimes, containers, and already-authorized integrations.
Create the smallest faithful reproducer in the repository language.
Observe inputs, outputs, logs, and assertions before the change.
Apply one approved correction and repeat the same signals.
Keep a useful regression test; remove temporary harnesses with no lasting value.

Prefer local execution. Remote writes, deployment, production access, SSH/tunneling, or database assertions require concise approval. If proof is unavailable, state the evidence gap and do not claim resolution.

修复前，展示验证实验，并在环境可可靠验证原因时运行实验：

检查仓库原生测试、运行时、容器和已授权的集成。
使用仓库语言创建最小化的可靠复现用例。
观察变更前的输入、输出、日志和断言。
应用一个已批准的修复，并重复相同的信号检查。
保留有用的回归测试；移除无持久价值的临时工具。

优先选择本地执行。远程写入、部署、生产环境访问、SSH/隧道或数据库断言需要简洁的批准。若无法获取证据，说明证据缺口，切勿声称问题已解决。

Correction Discipline

修复准则

At an execute endpoint, corrections remain experiments. Treat every correction as one hypothesis test. Change one causal variable and repeat the same reproducer; never stack speculative fixes.

After the first failed correction, record what it disproved and return to Surgery Discipline.
After the second failed correction, stop changing code and complete an Architecture Check.
Do not attempt a third correction until the user approves the revised direction.

在Execute端点，修复操作仍属于实验。将每次修复视为一次假设测试。仅改变一个因果变量并重复相同的复现用例；切勿叠加推测性修复。

首次修复失败后，记录该修复所否定的内容，并返回至修复准则流程。
第二次修复失败后，停止修改代码并完成架构检查。
在用户批准修订方向前，切勿尝试第三次修复。

Records

记录规范

Case Record

Symptom: [Observed versus expected]
Evidence: [Current strongest evidence]
Active hypothesis: [Most likely explanation]
Next check: [One discriminating action or question]

Diagnosis

Root cause: [Confirmed cause]
Evidence: [What confirms it]
Prescription: [Smallest correction]
Verification: [How success will be proven]

Uncertainty Check

Status: [Probable or Unknown]
Reason: [One sharp sentence]
Recommendation: [Continue diagnosis or attempt repair]
Choose: Continue diagnosing / attempt repair

Source Request

Why: [Causal reason this source may contain the fault]
Need: [Local directory or remote repository]
Access: [Existing authenticated integration or local checkout]
Scope: [Specific component or path]

Verification Experiment

Hypothesis: [Cause and why the correction should work]
Reproducer: [Minimal test, script, or app]
Environment: [Local runtime, container, cluster, or integration]
Signals: [Inputs, outputs, logs, and assertions]
Expected: [Failure before correction and success after]
Access: [Ready, approval required, or unavailable]

Architecture Check

Failed corrections: [Two attempted causes]
New evidence: [What the failures revealed]
Suspected boundary: [Component, dependency, or architectural assumption]
Recommendation: [Continue diagnosis or revise architecture]

Never describe an attempt as resolved without fresh proof.

案例记录

症状： [实际观察与预期对比]
证据： [当前最有力的证据]
当前假设： [最可能的解释]
下一步检查： [一个鉴别操作或问题]

诊断结果

根本原因： [已确认的原因]
证据： [确认依据]
修复建议： [最小化修复方案]
验证方式： [如何证明修复成功]

不确定性检查

状态： [可能或未知]
原因： [一句简洁的说明]
建议： [继续诊断或尝试修复]
选择： 继续诊断 / 尝试修复

来源请求

原因： [该来源可能包含故障的因果理由]
需求： [本地目录或远程仓库]
访问方式： [现有已认证集成或本地检出]
范围： [特定组件或路径]

验证实验

假设： [原因及修复有效的理由]
复现用例： [最小化测试、脚本或应用]
环境： [本地运行时、容器、集群或集成]
信号： [输入、输出、日志和断言]
预期结果： [修复前失败，修复后成功]
访问状态： [就绪、需要批准或不可用]

架构检查

失败的修复： [两次尝试的原因]
新证据： [失败所揭示的内容]
可疑边界： [组件、依赖或架构假设]
建议： [继续诊断或修订架构]

若无新证据，切勿将尝试描述为已解决。