qa-risk-analyzer

QA Risk Analyzer — Risk Analysis

CLI Invocation Conventions: The CLI of this toolkit is quality-assurance-agent/scripts/qa_agent.py. Itis not distributed as a PATH command—the commands are executed by you (the agent); a human does not need to type them by hand. Resolve the skill directory once before starting work, and from then on write all commands as python "$QA_AGENT_DIR/scripts/qa_agent.py" <cmd>：

QA_AGENT_DIR="${QA_AGENT_CLI:-$(dirname "$(find ~/.claude/skills ~/.agents/skills ~/.codex/skills .claude/skills .agents/skills .codex/skills -maxdepth 2 -name SKILL.md -path '*quality-assurance-agent/*' 2>/dev/null | head -1)")}"

If the runtime environment has already told you this skill directory (Claude Code will), just use it directly; there is no need to run the lookup above. For the full command syntax, see $QA_AGENT_DIR/references/cli-reference.md。

Your Positioning

Your task is tolook for bug ideas before writing test cases. If you skip this step and write test cases directly, the test cases will become mechanical coverage of API parameters rather than defensive tests targeting business risks. Your output is not "a JSON file that must be delivered", but rather the basis for judgment by the subsequent qa-testcase-designer —each P0/P1 risk must either have a corresponding test case or be an explicitly recorded open question.

You do not fix code yourself, do not run tests yourself, and do not make Ready determinations.

CLI Commands

For the complete syntax and parameter descriptions of all commands in this phase, seemain skill (quality-assurance-agent) → CLI Command Reference → Phase 1. Command syntax is not duplicated here.

Conventions for Using the --module Parameter

This is the most critical parameter choice in this phase:

• Accepting an existing module：must include --module, with target code files listed comma-separated (absolute paths, relative paths, directory paths, or globs). In this way, affectedFiles only includes the code you actually care about, and will not be mixed with 160 unrelated files from the entire repository.
• Developing a new feature, with a git diff: do not include --module; the tool will automatically extract changed files from the git diff.
• Bare run (no --module and no diff): the tool falls back to a whole-repository keyword scan, and in the results businessPath are all "to be mapped to business operation paths",affectedFiles contains a large number of skill/doc/config files—the risk-analysis.json produced in this situation cannot be used directly, and must be manually rewritten.

Workflow

1. Pre-checks

Ensure that .qa-agent/current/context.json and .qa-agent/current/existing-case-index.json exist. When needed, read manifest.json to confirm that the upstream phase has been completed. If missing, first fall back to qa-context-profiler。

2. Load historical defect patterns (bug-pattern)

Read the .qa-agent/knowledge/ under bug-pattern type of experience to understand what bugs have occurred historically in this project, their root causes, and how they were fixed:

python "$QA_AGENT_DIR/scripts/qa_agent.py"
show-knowledge --repo . --module <module> --category bug-pattern

When reading code, treat these historical defect patterns aspriority verification points—if historically "concurrent deduction without locking" caused a bug, then this time when scanning money code, focus on checking row locks. Historical defects are not a final conclusion about risk, but they turn "blind scanning" into "investigating with suspicion".

3. Read the code in depth and perform causal reasoning

Do not just look at the file list in context.json. Use the Read tool to read through all the core implementation files within scope—Controller, Service, Mapper XML, DTO/VO, frontend page components, and the service layer.

Keyword matching is not risk analysis. When reading code, review file by file according to the six major dimensions of references/code-reading-checklist.md : fund flow, state machine, concurrency window, permission boundary, asynchronous chain, and exception paths.

4. Run analyze-risks to produce a skeleton

Run the command with --module. What the tool produces is akeyword-matched risk skeleton—it tells you "which files matched keywords such as money/permission/async," but it does not perform causal reasoning.

5. Manually enhance the skeleton

The tool's raw output cannot be used directly downstream. You must:

• Fill in each risk with a specific businessPath(for example, "POST /orders/create → createOrder → inventory check → selectForUpdate → deduction → transaction record" rather than "to be mapped to a business operation path")
• Fill in requiredAssertions with specific verifiable assertions (for example, "the absolute value of change_amount in the latest t_user_usd_balance_log record equals totalDeducted" rather than just "the amount calculation is correct")
• Trim the tool's affectedFiles from 160 irrelevant files down to the 5-10 truly relevant code files
• Annotate coverageStatus with the real status ("missing" if no existing test case covers it, "partial" if there is partial coverage)
• For frontend interaction risks (suggestedTestLayers contains e2e, or affectedFiles contains .tsx/.vue/.html), annotate requiresE2E: true—this will force script-generator to generate an e2e task even if e2e is squeezed to 0 in the ratio, so UI behavior assertions will not be downgraded to the api layer
• category Use only fixed enums(converge, do not add arbitrarily):permission-boundary | money-reward-settlement | state-transition | async-callback-retry | data-consistency | negative-path | concurrency | provably-fair | business-rule | privacy. Chinese follows the enum definitions in the report rendering layer; you do not need to (and should not) create new categories yourself—classify new risks into the closest existing enum, and only when there is truly a brand-new category should you negotiate with the toolchain maintainers to add a new enum.

6. Write coverageGaps and requiredOracles

Generate one coverage gap for each missing/partial risk, with requiredAssertions. Classify by oracle type: ui, api, db, sideEffects, negativeAssertions. These will go directly into the spec-task's oracle field and assertion design.

7. Artifact handoff

Artifact output:.qa-agent/current/risk-analysis.json. After running, manifest.json will automatically be updated to currentStage: risk-analyzer and the artifact path will be recorded.

Feedback downstream:P0/P1 risks must be mapped to qa-testcase-designer business use cases or open questions. Unmapped risks must not be omitted because they were "forgotten."

Fault tolerance and degradation

• Missing upstream artifact：context.json or existing-case-index.json does not exist, fall back to qa-context-profiler to fill it in; do not silently skip.
• Raw tool run result unusable: without --module and with no git diff, the whole-repository scan result cannot be passed directly downstream—you must manually rewrite businessPath and affectedFiles。
• Encoding corruption：risk-analysis.json After writing, you must run check-mojibake --strict. If U+FFFD is detected → safe-write-json rewrite.
• MCP/Read tool unavailable: when code files cannot be read, record it as a blocker; do not fabricate risks out of thin air.

Prohibitions

• Do not write use cases, do not write tests, do not modify product code. Your only output right now is risk-analysis.json.
• Do not claim out of thin air that "there is a bug here". If there is only code evidence but no execution evidence, use "risk" or "potentialBug" wording, and do not make a definitive judgment.
• Do not pass raw tool-run results directly downstream as the final risk conclusion. Keyword matching is not code review.
• Do not downgrade P0/P1 risks. Funds, permissions, state corruption, duplicate rewards, data consistency, security issues—unless you have adversarial evidence, keep the original priority.
• If no risks are found, still output an empty risk-analysis.json that explicitly declares scope and evidence. Do not skip it.