Root Cause Diagnosis

Turns exception evidence into an English root-cause report. Structured understanding of the business codebase comes from the CodexQA CLI; this skill diagnoses on top of that analysis.

CLI: node {baseDir}/scripts/diagnose.ts ($SKILL_SCRIPT). Task data: {baseDir}/data/{taskId}/.

README.md / README.zh-CN.md / HOW_IT_WORKS.md / KNOWN_LIMITATIONS.md (and their .zh-CN twins) are human-facing. Do not load them at runtime.

Boundaries

Need	Skill
Symbol-graph change impact, callers, test gaps, entry risk	codexqa-code-analyzer
Exception RCA from stacks/logs on top of CLI analysis	this skill
SAST + Agent LLM Detection → report_scan.*	codexqa-defect-analyzer
CodexQA evidence-pack + Agent LLM judgment → bilingual REVIEW-REPORT.html	codexqa-code-reviewer

Split of work

Layer	Owns
TypeScript (draft-report)	First-level English headings, extracted facts (facts.json), mechanical storyGaps
Model	Report narrative inside those headings, using only cited facts
TypeScript (write-report)	Reject missing headings and story gaps. Do not reject on section length

Do not put exception-class fix wording in scripts/draft_report.ts. Mechanical defects stay in TypeScript; causal truth in this business domain stays with the model.

Happy path

run is seconds. Wall-clock is LLM round-trips. Do not load references/, other skills, --help, or scripts/*.ts before run. Do not invent Class#search:1 for → Class tails. Do not count 字 or trim to a hint.

1. Collect exception evidence and the code location. Write an exception file if needed.
2. One process: run (or submit --with-analyze) with --exception/--exception-file plus --git/--branch, --file, or --dir. Bare flags without run still run. Uploaded files and non-git folders are copied into data/<taskId>/repo and git-inited there only. Do not invent a git remote. Do not git init in the user's original path.
3. run writes brief.json, facts.json, and a heading-only report.draft.md. It does not author or persist report.md. parse-exception is already done; skip unless parsed.json is missing.
4. If stdout has facts / factsPath, fill report.draft.md from facts.json in one pass (Report rules below). If codexqa.ready=true and brief exists but facts are missing, draft-report --task-id then fill. Do not read analysis.json when brief/facts exist. Do not open ~/.codexqa/.
5. write-report --from-draft. If stdout has storyGaps, edit the draft once from that output and retry. Do not retry to shrink length.
6. Show one English paragraph from stdout chat.en (the first line of Executive summary) plus paths to report.md / report.en.md / report.html. If chat.en is empty, use that summary line. Do not paste the full document.
7. Observe stdout/meta timings after every CLI step. If a step is abnormally slow, diagnose that delay and fix it before continuing RCA.
8. Skill defects (mandatory): if a step is wrong, truncates, skips a rule, or is flaky, first encode the rule in TypeScript (scripts/*.ts + tests/*.test.ts) so later runs cannot regress. Keep an Agent-only note in this file only when the check cannot be decided without an LLM (for example: whether a causal sentence is true in this business domain). After the TS fix, re-run or draft-report before filling the report.

Abbreviated class-only → Foo frames expand to hinted types ending with Foo before staying weak.

Report rules (mandatory)

English Markdown only. Same eight ## headings as references/report-template.md. No extra top-level headings. Do not write a Chinese report.

The Target column is a prompt hint for the model, not a write-report reject. Keep the report complete even if a section exceeds the hint.

Section	Target (hint)	Must contain
Executive summary	100	what failed, in-repo root, literal Confidence: high|medium|low
Symptom and exception facts	100	type, message gist, primary Class#method:line
Mapped call path	300	entry → each hop → extracted branch then-call → throw; mark weak frames
Root cause	300	earliest wrong contract in this repo, why that path ran; cite Class#method. Include race/contend only when facts.raceEvidence is true
Trigger	100	throw site; not the root cause
Contributing factors	100	factors grounded in facts (swallowKey, evidenceGaps); do not invent swallow / race / weak-frame claims
Suggested fix and verification	100	one fix + one verify; do not apply code
Confidence and gaps	100	use facts.confidence (high/medium); never write Confidence: high when facts say medium; one gap

Mapped call path and Root cause must tell the story: entry, hops, branch, and throw. Mention race/contend only when facts.raceEvidence is true. Cite catch-all swallow only when facts.swallowKey is set. Mark hypothesis when facts.lineDrift is non-empty; do not invent line-drift or weak-frame claims without facts. A slogan or a bare A→B→C is invalid. Do not paste facts.json as the report.

When facts.lineDrift is non-empty, Root cause must mark hypothesis. Trigger must cite the throw class and say it is not the root. Root must cite the throw class and (if extracted) the branch else-call.

write-report storyGaps (edit the draft once if rejected):

Gap	Section	Required text
missing-confidence	Executive summary	Confidence:
confidence-overstated	Executive summary	do not write Confidence: high when facts.confidence is medium
mapped-missing-branch-then	Mapped call path	facts.branch.thenCall
mapped-missing-throw	Mapped call path	throw class from facts.throwKey
mapped-invented-weak	Mapped call path	drop "weak frame" wording when facts.weakCount is 0
root-missing-branch-else	Root cause	facts.branch.elseCall
root-missing-throw	Root cause	throw class
root-missing-race	Root cause	raced/race/contend — only when facts.raceEvidence=true
root-invented-race	Root cause	remove race/contend when facts.raceEvidence is false
root-missing-hypothesis-on-drift	Root cause	hypothesis when facts.lineDrift is non-empty
root-invented-line-drift	Root cause	drop line-drift claims when facts.lineDrift is empty
contributing-missing-swallow	Contributing / Root	cite facts.swallowKey (or swallow wording) when set
contributing-invented-swallow	Contributing / Root	drop swallow/catch-all claims when facts.swallowKey is null
trigger-missing-throw	Trigger	throw class
trigger-missing-not-root	Trigger	not the root (or not root)

Citations: one Class#method (or file:line) per causal claim. No SQL dumps, no numbered evidence lists, no whole-class pastes.

Chat: one English paragraph + paths to report.md / report.en.md. Do not paste the full document.

Entry

node "$SKILL_SCRIPT" run --exception-file "$PATH" --dir "$LOCAL_DIR"
# uploaded business file (non-git OK; stack sibling sources in the same folder are bundled):
#   node "$SKILL_SCRIPT" run --exception-file "$PATH" --file /abs/path/OrderService.java
# remote:
#   node "$SKILL_SCRIPT" run --exception "$TEXT" --git "$GIT_URL" --branch "$BRANCH"
# already-open IDE / cwd:
#   node "$SKILL_SCRIPT" run --exception "$TEXT"
# stepwise (debug only):
node "$SKILL_SCRIPT" submit --exception-file "$PATH" --dir "$LOCAL_DIR"
node "$SKILL_SCRIPT" ensure-codexqa --task-id $TASK_ID --with-analyze
# fill data/<id>/report.draft.md from facts.json, then:
node "$SKILL_SCRIPT" write-report --task-id $TASK_ID --from-draft

Load order

Load each reference at most once, and never before run. Links from this file are one level deep.

File	When to load
references/workflow.md	Stepwise debug, or facts missing after run
references/codexqa.md	Before ensure-codexqa / analyze-frames when run did not index
references/exception-parse.md	Before interpreting parsed.json when facts/brief are missing
references/report-template.md	Before filling report.draft.md, only if Report rules above are not already in context

RCA rules

• Distinguish trigger (the throw), root cause (earliest incorrect state/contract in this repo), and contributors.
• Do not treat the last stack frame as the root cause.
• Every causal claim cites Class#method or file:line. Do not add extra evidence lists.
• Missing graph → hypothesis + how to verify. Never invent call edges.
• After a real ensure-codexqa attempt with ready=false, grep is allowed and evidence is weak.

CodexQA (CLI only)

Install if missing: npm install -g @openqa-cn/codexqa --registry https://registry.npmjs.org/. Talk to the codexqa binary only (index / query / stats / repos). Do not copy engine or skill source into this skill. Details: references/codexqa.md.