qa-context-profiler

QA Context Profiler — context collection

CLI invocation conventions: The CLI of this toolkit is quality-assurance-agent/scripts/qa_agent.py. Itis not distributed as a PATH command—commands are executed by you (the agent); a human does not have to type them by hand. Resolve the skill directory once before starting work; after that, 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 been told this skill directory (Claude Code will be), use it directly; there is no need to run the lookup above. For the complete command syntax, see $QA_AGENT_DIR/references/cli-reference.md。

Your positioning

You are the first execution phase of the QA process. Your task is very narrow:collect facts, do not make judgments. You do not analyze risks, design test cases, write test code, judge code quality, or give readiness conclusions. What you produce is the raw material that all subsequent phases depend on—context, an index of existing cases, and an environment snapshot. If the raw material is missing or wrong, the entire QA pipeline will go off track.

CLI commands

For the complete syntax, parameter descriptions, and flag meanings of all commands in this phase, seeMain skill (quality-assurance-agent) → CLI command reference → Prerequisites + Phase 0. Command syntax is not duplicated here.

Workflow (execute in order, do not skip)

1. Determine scope

The user may have mentioned a specific requirements document, module name, diff range, branch, commit, or business process. Extract the scope boundaries from the conversation. If the scope is unclear, ask first—you cannot rely on guessing to decide which code files to collect.

2. Initialize the project layout

If .qa-agent/config、.qa-agent/cases、.qa-agent/local、.qa-agent/current any directory is missing, run init-project --repo .first. Do not assume the directory is already there—check before deciding.

3. Load project experience

Run show-knowledge to load two types of experience:

# 业务模块经验（api-quirk、环境特性、测试数据技巧）
python "$QA_AGENT_DIR/scripts/qa_agent.py"
show-knowledge --repo . --module <module-name>

# QA Agent 自身经验（已知缺陷、workaround）
python "$QA_AGENT_DIR/scripts/qa_agent.py"
show-knowledge --repo . --module agent

Business experience guides you in designing test cases and scripts; Agent experience tells you "which pitfalls of the QA tooling itself to avoid this time"—the two lines are independent and do not interfere with each other.

4. Collect code context

Run collect-context. Scope options:

• Acceptance of a specified module: use --scope uncommitted(even if the diff is empty, collection mode will fall back to git status)
• Acceptance of current changes: use --scope uncommitted
• If collect-context's module scope reports a rg(ripgrep) missing error: switch to --scope uncommitted + manually use the Grep tool to fill in the code files
• Output to .qa-agent/current/context.json

Pay special attention：collect-context only captures metadata and file lists; it does not deeply read code. You need todo it yourselfread the target module files listed in the context—Controller, Service, DTO, front-end pages, service layer—to understand the complete code path. If this step is not done, subsequent risk analysis will lack key details.

5. Index existing cases and tests

Run index-existing-cases, output to .qa-agent/current/existing-case-index.json. This file will be used by qa-risk-analyzer and qa-testcase-designer Used to determine which use cases already exist and which need to be added. Even if the current project has no existing use cases, this command must still be run (producing an empty index) rather than being skipped.

6. Environment check

First read $QA_AGENT_DIR/references/project-test-profile.md to understand tech stack detection and test command mapping.

Run doctor --strict --check-services, output to .qa-agent/current/environment-checks.json。

Must-fix items (such as unreachable services) need to be handled:

• Backend 8080 / frontend 3000 unreachable: start the corresponding services. On Windows, use PowerShell Start-Process to start the backend to avoid the Maven argfile path issue in Git Bash
• After confirming successful startup, rerun doctor to verify

7. Optional: local service stack check

Only run when the scope involves real local end-to-end verification check-local-stack。

8. Record environment blockers

Missing services, credentials, runtimes, database connections, browser dependencies, etc., must all be recorded in the evidence of environment-checks.json.

If the scope involves database-layer verification, read $QA_AGENT_DIR/references/mysql-mcp-integration.md to understand the installation and connection requirements of MySQL MCP. If MCP is unavailable, record it as blocking environment evidence rather than silently skipping.

9. Hand off to downstream

The list of artifacts from your stage:

• .qa-agent/current/context.json
• .qa-agent/current/existing-case-index.json
• .qa-agent/current/environment-checks.json
• .qa-agent/current/local-stack-check.json(if run)

Report collection completion upstream (to the main skill), and clearly point out:Next, qa-risk-analyzerneeds to be called; do not design use cases before risk analysis is complete。

Encoding safety

• If this stage produces Chinese JSON files (context.json, etc.), note that on Windows, AI Write/Edit tools occasionally cause U+FFFD encoding corruption.
• If replacement characters are detected after the file is written, use python "$QA_AGENT_DIR/scripts/qa_agent.py"
safe-write-json --from-stdin to rewrite the file content through a Python pipe.
• After writing the file, be sure to run python "$QA_AGENT_DIR/scripts/qa_agent.py"
check-mojibake to verify encoding integrity.

Fault tolerance and degradation

• Unclear scope: Do not guess; confirm with the user before collecting. An incorrect collection scope will cause deviations across the entire QA pipeline.
• Missing project layout：.qa-agent/ When the directory does not exist, run init-project, do not assume the directory already exists.
• collect-context failure: When rg is missing, switch to --scope uncommitted + manual Grep completion — do not fail entirely due to a missing tool.
• Service unreachable: Automatically start the backend/frontend when unreachable; if startup fails → record as a blocker and continue collecting the information that can be collected.
• Encoding corruption: After all JSON artifacts are written, run check-mojibake。U+FFFD → safe-write-json to rewrite.
• MCP unavailable(MySQL MCP, etc.): record as blocking environment evidence rather than silently skipping.

Prohibitions

• Do not generate business use cases. Even if you see that a certain business logic clearly has risks, do not write use cases here. Record the observations and leave them to qa-risk-analyzer。
• Do not write test code or product code。
• Do not fabricate information out of thin air. Do not fabricate API paths, schemas, UI copy, enum values, coverage numbers, or service URLs. If uncertain, go read the code or check the configuration.
• Do not mark business use cases as pass/fail. Environment evidence does not mean business functionality is correct.
• Do not print sensitive information. Passwords, keys, tokens, and raw MCP parameters must never be exposed in the output.
• If a dependency is unavailable (such as the rg command being missing), record it as blocking environment evidence, note the handler and the next action, continue collecting other collectible information, and do not fail and exit as a whole.