diagnose

Diagnose

Use this skill when the user faces a build / sim / test / difftest failure and wants an external investigation. The skill packages the failure context and routes to Codex through codex-plugin-cc's rescue command.

This skill does not solve the failure itself. It assembles context and hands off. Codex investigates and proposes a root cause and a fix plan.

Do not autoload — only respond when the user invokes /chipdev-method:diagnose or matches the trigger phrases in the description.

---

Prerequisites

Same as audit:

1. codex CLI on PATH.
2. codex-plugin-cc installed.
3. Current working directory is a git repository.

Surface remediation steps if any are missing.

---

How to use this skill in a response

When triggered, perform the following steps:

Step 1. Classify the failure

Pick one (ask the user if not obvious):

• Build failure — compile / link / codegen error.
• Simulation crash — segfault, assertion, exception in the sim.
• Simulation hang — sim runs but never terminates.
• Test mismatch — output differs from golden.
• Difftest mismatch — behavior model and RTL disagree at a sampling point.
• Performance regression — sim got slower or runs out of memory.
• Numerical degradation — NaN / Inf / accuracy below threshold.
• Other / unknown.

The classification drives what context to collect.

Step 2. Verify prerequisites

command -v codex >/dev/null || echo "MISSING: codex CLI"
git rev-parse --is-inside-work-tree >/dev/null 2>&1 || echo "MISSING: not a git repo"

If anything is missing, instruct the user to install codex-plugin-cc or re-invoke from a git repo. Stop.

Step 3. Collect failure context

Always collect:

1. The error message / log excerpt the user provided.
2. The most recent commit message and one-line diff summary (git log -1 --stat).
3. The list of files modified in the most recent commit.

By failure class, additionally:

Class	Extra context
Build failure	Full compiler / linker / codegen output, last 200 lines.
Sim crash	Stack trace if available, last 200 lines of sim log, the test command.
Sim hang	The last 100 lines before hang; the test command; estimated where it hung (cycle / module).
Test mismatch	The diff / mismatch report (e.g., CompTool output); the test name and inputs.
Difftest mismatch	The exact instruction / transaction at mismatch; ref state vs DUT state at the boundary; mask configuration in use.
Performance regression	Before / after timing; profiling output if available; commit ranges that bracket the regression.
Numerical degradation	The threshold violated; the data type; the workload / test name.

Cap log excerpts at ~500 lines. If the log is longer, take the first 100 and last 200, plus any line containing error, fail, assert, nan, or the test name.

Read the user's argument:

• A path → read the file (subject to the cap).
• A free-text description → use as the user's narrative.

Step 4. Build the diagnosis prompt

Use references/diagnose-prompt-template.md as the template. Fill in:

1. Failure classification.
2. Failure context (logs, commit info, file list).
3. The "common cause patterns" relevant to the classification — drawn from references/failure-taxonomy.md.
4. Hypotheses the user has already ruled out, if any.
5. Expected output: ranked candidate root causes with evidence, plus a minimal repro plan.

Step 5. Invoke Codex

Prefer the codex-plugin-cc slash command (/codex:rescue or whichever that plugin exposes). Direct fallback:

codex exec -m gpt-5.4 \
  -c model_reasoning_effort=high \
  --full-auto \
  -C "$(git rev-parse --show-toplevel)" \
  - < "$DIAGNOSE_PROMPT_FILE"

Step 6. Format the result

When Codex returns:

1. Lead with the most-likely root cause in one sentence.
2. List ranked candidates with evidence, capped at 5.
3. Show the minimal reproduction — the smallest test / command that triggers the failure.
4. Show the proposed fix if Codex provided one. Be explicit that the user should validate it before merging.
5. Note open questions Codex flagged.

Do not echo Codex's full output verbatim — compress.

---

Failure-class playbooks [abstract]

Quick patterns to surface to the user before invoking Codex, when classification is clear.

Build failure

• Code generated from the DSL is out of date — try a clean rebuild and see if the error persists.
• Header dependency: a generated header changed schema; downstream module needs adjustment. Audit proc_* callback signatures.
• New compiler version: tightened warnings have promoted to errors.
• Static / shared mode mismatch: a module changed library-kind without the build-system update.

Sim crash

• Null pointer in a generated Conn — module was renamed but the factory was not regenerated.
• Memory pool double-free — transaction is freed by both producer and consumer.
• Out-of-bounds queue access — idle() returned false but queue had already been drained.

Sim hang

• A module's idle() returns false while no input remains — stale flag.
• A valid+ready deadlock: both sides waiting on each other.
• Idle threshold not reached — set a hard simulation-time cap.

Difftest mismatch

• See align-and-difftest triage flow before invoking diagnose. Often the right initial step is align-and-difftest's "Debugging a mismatch" section, not diagnose directly.

Numerical degradation

• Subnormal handling differs between ref and DUT.
• Rounding mode bug — accumulator is not in the agreed rounding mode.
• Threshold misconfigured — relative-error threshold too tight after a recent ref change.

---

Common failure modes when running diagnose [abstract]

• Log dump is too large. Codex generic-reviews. Always cap and highlight the relevant section.
• No reproduction command. Codex can't propose a minimal repro. Always include it.
• User has not stated what they already tried. Codex re-suggests the same thing. Always pass "what's been ruled out".
• Diagnose run on a non-deterministic failure. Codex hypothesizes; user can't confirm. State the determinism status up front.

---

See also

• audit — the sister skill, for methodology compliance review.
• align-and-difftest — the difftest-specific triage flow that may resolve the issue without invoking Codex.
• references/failure-taxonomy.md — common failure causes by class.
• references/diagnose-prompt-template.md — the Codex prompt template.