Nerd Surgery

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.

Inheritance

Use nerd-smart first and consume its resolved Focus Record through nerd-diagnose or 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.

Generic Diagnostic Mappings

Surgery Discipline

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

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.

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.

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:

1. Check repository-native tests, runtimes, containers, and already-authorized integrations.
2. Create the smallest faithful reproducer in the repository language.
3. Observe inputs, outputs, logs, and assertions before the change.
4. Apply one approved correction and repeat the same signals.
5. 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.

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.

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.