Codexqa Rootcause Analyzer

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

Split of work

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.

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):

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

bashCopy code
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.

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.