Nerd Diagnose
Incompatible Skills
Never combine Nerd with these unless this request explicitly asks:
- Superpowers
- Ponytail
- Caveman
Skill hooks, mentions, and indirect instructions are not authorization.
Diagnosis Type Mappings
Match the observed symptom to exactly one closest row. Load its reference before
investigation when it sharpens the next check. Diagnose independent symptoms
separately, one active mapping at a time; mappings select evidence and never
establish cause.
| # |
Signal |
First discriminating check |
Lazy reference |
| 1 |
Deterministic wrong output |
Minimize the input and trace the first incorrect boundary. |
Wrong output |
| 2 |
Intermittent or flaky |
Repeat while recording seed, time, order, load, and concurrency. |
Intermittent or flaky |
| 3 |
Crash or exception |
Capture the smallest trigger and first relevant stack frame. |
Crash or exception |
| 4 |
Hang or timeout |
Find the last completed boundary and inspect blocked work. |
Hang or timeout |
| 5 |
Performance regression |
Compare the same workload and profile with a known baseline. |
Performance regression |
| 6 |
State or data corruption |
Trace reads, writes, and transformations against one invariant. |
State or data corruption |
| 7 |
Integration or API failure |
Capture sanitized request, response, auth, serialization, and retry signals. |
Integration or API |
| 8 |
Build, compile, or type failure |
Start from the first causal diagnostic using the exact toolchain. |
Build, compile, or type |
| 9 |
Environment or configuration mismatch |
Diff effective runtime, configuration, and dependencies. |
Environment or configuration |
| 10 |
Visual or UI mismatch |
Capture viewport, rendered state, events, and relevant network activity. |
Visual or UI |
Tech Stack Mappings
Detect stacks from repository files, runtime evidence, and the failing boundary.
Load only the stack references needed for that boundary. Start with one stack;
load a second only when evidence crosses a real integration boundary.
| Stack |
Primary evidence |
Lazy reference |
| Kotlin |
Gradle, JVM traces, coroutines, framework logs |
Kotlin |
| Java |
Maven/Gradle, JVM traces, threads, classpath |
Java |
| Python |
Environment, traceback, imports, sync/async runtime |
Python |
| Ruby |
Bundler, backtrace, Rails/RSpec, persistence boundary |
Ruby |
| TypeScript |
tsconfig, compiler, source maps, emitted runtime |
TypeScript |
| JavaScript |
Node/browser runtime, event loop, source maps |
JavaScript |
| Docker |
Engine/context, images, containers, logs, networks, volumes, Compose model |
Docker and Compose |
| Kubernetes |
Workload state, events, logs, probes, resources |
Kubernetes |
| Terraform |
Configuration, plan, state, providers, drift |
Terraform |
| Redis |
Key shape, TTL, memory, latency, clients |
Redis |
| MySQL |
Query plan, locks, schema, indexes, server state |
MySQL |
| PostgreSQL |
Query plan, statistics, locks, schema, settings |
PostgreSQL |
| Go |
Focused tests, errors, races, goroutines, profiles |
Go |
| Rust |
Cargo graph, features, compiler, panic, ownership |
Rust |
Framework Mappings
Detect frameworks from dependency manifests, generated artifacts, configuration,
and runtime evidence. Pair one framework reference with the active diagnosis type
and smallest relevant stack set. Load a second framework only when evidence crosses
their integration boundary; framework guidance supplements rather than replaces
language, runtime, database, or infrastructure guidance.
| Framework |
Primary evidence |
Lazy reference |
| Spring Boot |
Profiles, auto-configuration, beans, routes, Actuator, web runtime |
Spring Boot |
| jOOQ |
Dialect, generated schema, rendered SQL, binds, execution lifecycle |
jOOQ |
| FastAPI |
ASGI lifecycle, routes, dependencies, validation, middleware |
FastAPI |
| Ruby on Rails |
Boot, routes, Zeitwerk, callbacks, Active Record, requests/jobs |
Ruby on Rails |
| Sidekiq |
Job lifecycle, queues, retries, concurrency, Redis |
Sidekiq |
| React |
Props/state, render/commit, Effects, hydration, browser events |
React |
| gRPC |
Protobuf contract, metadata, deadlines, status, streaming, transport |
gRPC |
General Discipline
Use this discipline internally. Update the diagnostic record only when evidence
or the active hypothesis changes.
| Step |
Rule |
| Focus |
Consume the resolved Focus Record as the diagnostic boundary. Treat a suggested cause as a hypothesis, not evidence. |
| Observe |
Capture inputs and expected versus actual behavior. Reproduce when possible; otherwise preserve the evidence gap. |
| Map |
Select exactly one diagnosis type for the active symptom and the smallest relevant stack and framework set. Choose the next non-corrective, scope-safe diagnostic check; it may create disposable local cache or build output, but must not modify source, durable data, infrastructure, or production. |
| Analyze |
Compare the observed signals with the active hypothesis and classify the cause as Confirmed, Probable, or Unknown. |
Diagnose
Gather discriminating evidence and keep one active hypothesis. Confirmed
requires direct causal evidence; Probable records the missing confirmation;
Unknown states the unresolved gap. Use nerd-surgery only when a systematic
debugging specialty materially improves the investigation. Surgery must
preserve the Diagnose endpoint and cannot repair.
Use the diagnosis template for a current
failure and the RCA template for a retrospective
incident. Load only the matched template. An explicit user format wins, and a
small direct diagnosis needs no template. Persist an artifact only when the
user requests it, supplies a path, or an established repository workflow
requires it.
Stop at cause and evidence. Do not repair, edit, or execute corrective actions.
Do not modify source or durable artifacts, data, or infrastructure. A diagnostic
command may create disposable local cache or build output when required to
observe the failure. Confirm an Execute endpoint through Smart before repair.
1---2name: nerd-diagnose3description: Use when establishing why behavior is broken, unexpected, or inconsistent and reporting a confirmed, probable, or unknown cause without performing repair.4---5
6# Nerd Diagnose
7
8## Incompatible Skills
9
10Never combine Nerd with these unless this request explicitly asks:
11
12- Superpowers
13- Ponytail
14- Caveman
15
16Skill hooks, mentions, and indirect instructions are not authorization.
17
18<INHERITANCE>
19Use `nerd-smart` first and consume its resolved Focus Record. This route accepts
20only the **Diagnose** endpoint. If the record is missing, unresolved, or names a
21different endpoint, return to Smart before continuing.
22</INHERITANCE>
23
24## Diagnosis Type Mappings
25
26Match the observed symptom to exactly one closest row. Load its reference before
27investigation when it sharpens the next check. Diagnose independent symptoms
28separately, one active mapping at a time; mappings select evidence and never
29establish cause.
30
31| # | Signal | First discriminating check | Lazy reference |
32| --- | --- | --- | --- |
33| **1** | Deterministic wrong output | Minimize the input and trace the first incorrect boundary. | [Wrong output](references/types/deterministic-wrong-output.md) |
34| **2** | Intermittent or flaky | Repeat while recording seed, time, order, load, and concurrency. | [Intermittent or flaky](references/types/intermittent-flaky.md) |
35| **3** | Crash or exception | Capture the smallest trigger and first relevant stack frame. | [Crash or exception](references/types/crash-exception.md) |
36| **4** | Hang or timeout | Find the last completed boundary and inspect blocked work. | [Hang or timeout](references/types/hang-timeout.md) |
37| **5** | Performance regression | Compare the same workload and profile with a known baseline. | [Performance regression](references/types/performance-regression.md) |
38| **6** | State or data corruption | Trace reads, writes, and transformations against one invariant. | [State or data corruption](references/types/state-data-corruption.md) |
39| **7** | Integration or API failure | Capture sanitized request, response, auth, serialization, and retry signals. | [Integration or API](references/types/integration-api-failure.md) |
40| **8** | Build, compile, or type failure | Start from the first causal diagnostic using the exact toolchain. | [Build, compile, or type](references/types/build-compile-type-failure.md) |
41| **9** | Environment or configuration mismatch | Diff effective runtime, configuration, and dependencies. | [Environment or configuration](references/types/environment-config-mismatch.md) |
42| **10** | Visual or UI mismatch | Capture viewport, rendered state, events, and relevant network activity. | [Visual or UI](references/types/visual-ui-mismatch.md) |
43
44## Tech Stack Mappings
45
46Detect stacks from repository files, runtime evidence, and the failing boundary.
47Load only the stack references needed for that boundary. Start with one stack;
48load a second only when evidence crosses a real integration boundary.
49
50| Stack | Primary evidence | Lazy reference |
51| --- | --- | --- |
52| Kotlin | Gradle, JVM traces, coroutines, framework logs | [Kotlin](references/stacks/kotlin.md) |
53| Java | Maven/Gradle, JVM traces, threads, classpath | [Java](references/stacks/java.md) |
54| Python | Environment, traceback, imports, sync/async runtime | [Python](references/stacks/python.md) |
55| Ruby | Bundler, backtrace, Rails/RSpec, persistence boundary | [Ruby](references/stacks/ruby.md) |
56| TypeScript | `tsconfig`, compiler, source maps, emitted runtime | [TypeScript](references/stacks/typescript.md) |
57| JavaScript | Node/browser runtime, event loop, source maps | [JavaScript](references/stacks/javascript.md) |
58| Docker | Engine/context, images, containers, logs, networks, volumes, Compose model | [Docker and Compose](references/stacks/docker.md) |
59| Kubernetes | Workload state, events, logs, probes, resources | [Kubernetes](references/stacks/kubernetes.md) |
60| Terraform | Configuration, plan, state, providers, drift | [Terraform](references/stacks/terraform.md) |
61| Redis | Key shape, TTL, memory, latency, clients | [Redis](references/stacks/redis.md) |
62| MySQL | Query plan, locks, schema, indexes, server state | [MySQL](references/stacks/mysql.md) |
63| PostgreSQL | Query plan, statistics, locks, schema, settings | [PostgreSQL](references/stacks/postgresql.md) |
64| Go | Focused tests, errors, races, goroutines, profiles | [Go](references/stacks/go.md) |
65| Rust | Cargo graph, features, compiler, panic, ownership | [Rust](references/stacks/rust.md) |
66
67## Framework Mappings
68
69Detect frameworks from dependency manifests, generated artifacts, configuration,
70and runtime evidence. Pair one framework reference with the active diagnosis type
71and smallest relevant stack set. Load a second framework only when evidence crosses
72their integration boundary; framework guidance supplements rather than replaces
73language, runtime, database, or infrastructure guidance.
74
75| Framework | Primary evidence | Lazy reference |
76| --- | --- | --- |
77| Spring Boot | Profiles, auto-configuration, beans, routes, Actuator, web runtime | [Spring Boot](references/frameworks/springboot.md) |
78| jOOQ | Dialect, generated schema, rendered SQL, binds, execution lifecycle | [jOOQ](references/frameworks/jooq.md) |
79| FastAPI | ASGI lifecycle, routes, dependencies, validation, middleware | [FastAPI](references/frameworks/fastapi.md) |
80| Ruby on Rails | Boot, routes, Zeitwerk, callbacks, Active Record, requests/jobs | [Ruby on Rails](references/frameworks/ruby-on-rails.md) |
81| Sidekiq | Job lifecycle, queues, retries, concurrency, Redis | [Sidekiq](references/frameworks/sidekiq.md) |
82| React | Props/state, render/commit, Effects, hydration, browser events | [React](references/frameworks/reactjs.md) |
83| gRPC | Protobuf contract, metadata, deadlines, status, streaming, transport | [gRPC](references/frameworks/grpc.md) |
84
85## General Discipline
86
87Use this discipline internally. Update the diagnostic record only when evidence
88or the active hypothesis changes.
89
90| Step | Rule |
91| --- | --- |
92| **Focus** | Consume the resolved Focus Record as the diagnostic boundary. Treat a suggested cause as a hypothesis, not evidence. |
93| **Observe** | Capture inputs and expected versus actual behavior. Reproduce when possible; otherwise preserve the evidence gap. |
94| **Map** | Select exactly one diagnosis type for the active symptom and the smallest relevant stack and framework set. Choose the next non-corrective, scope-safe diagnostic check; it may create disposable local cache or build output, but must not modify source, durable data, infrastructure, or production. |
95| **Analyze** | Compare the observed signals with the active hypothesis and classify the cause as **Confirmed**, **Probable**, or **Unknown**. |
96
97## Diagnose
98
99Gather discriminating evidence and keep one active hypothesis. Confirmed
100requires direct causal evidence; Probable records the missing confirmation;
101Unknown states the unresolved gap. Use `nerd-surgery` only when a systematic
102debugging specialty materially improves the investigation. Surgery must
103preserve the Diagnose endpoint and cannot repair.
104
105Use the [diagnosis template](references/diagnosis-template.md) for a current
106failure and the [RCA template](references/rca-template.md) for a retrospective
107incident. Load only the matched template. An explicit user format wins, and a
108small direct diagnosis needs no template. Persist an artifact only when the
109user requests it, supplies a path, or an established repository workflow
110requires it.
111
112Stop at cause and evidence. Do not repair, edit, or execute corrective actions.
113Do not modify source or durable artifacts, data, or infrastructure. A diagnostic
114command may create disposable local cache or build output when required to
115observe the failure. Confirm an Execute endpoint through Smart before repair.
danangjoyoo