cs-feat-qa

cs-feat-qa

Required Reading Before Starting

Before making any judgment or taking any action, first run the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not substitute by reading external AI entry points (see .codestable/reference/execution-conventions.md）。

This stage is the QA gate after review passes and before acceptance. It only reads code and artifacts, runs verification commands / browser / API / manual checks, and writes {slug}-qa.md. By default it does not modify code, does not modify the checklist, and does not modify the design; after discovering a failure, return to cs-feat-impl qa-fix.

The goal of QA is not to do code review again, nor is it the final archival acceptance report. It answers one question: in the current workspace, is there sufficient runtime evidence for the key behaviors promised by the design, and are the test focus areas and residual risks pointed out by review actually covered.

For shared paths and naming conventions see .codestable/reference/shared-conventions.md Section 0.

Independent QA Task agent (optional)

QA may follow .codestable/reference/execution-conventions.md 's Task agent selection rules and enable an independent runner to execute browser, API, CLI, integration tests, or environment re-checks, especially for high-risk features, external integrations, real browser paths, and core acceptance paths in goal mode. But it is an auxiliary executor, not the QA owner:

The main agent is responsible for building the Verification Matrix, deciding which evidence blocks, verifying runner output, and writing {slug}-qa.md 's final verdict.
By default the runner only reads code and artifacts and only runs verification; if tests or configuration need to be changed, it must return to cs-feat-impl qa-fix。
Runner output must be written into the QA report's evidence sources; conclusions not locally verified by the main agent can only serve as residual-risk or items pending re-check.
Ordinary low-risk non-functional features do not require an independent runner, to avoid fixing and amplifying QA cost.

Inputs

Before entering QA, you must read:

.codestable/attention.md
{slug}-design.md
{slug}-checklist.yaml
{slug}-review.md
In goal / gate mode, {slug}-evidence-pack.md、{slug}-gate-results.json、{slug}-dod-results.json
implementation completion report / review-fix report (if any)
git status --short
git diff(when there is a staged diff, also read git diff --cached）
required validation commands / baseline risks / acceptance scenarios / evidence types / cleanliness rules in the design
Section 4 Test And QA Focus and Section 5 Residual Risk of the review report
Project test entry points: README, package scripts, Makefile, CI configuration, commands related to this feature in historical acceptance / qa reports
Feature nature determination: functional / non-functional, and which scenarios are core acceptance paths

If the workspace has pre-existing dirty files outside the feature, record the baseline/unrelated changes; QA conclusions only cover changes attributable to this feature. When attribution cannot be distinguished, write blocked or residual-risk, do not pretend it passed.

Feature Nature and Evidence Hard Gate

QA first determines the feature nature, then decides what evidence must be obtained. This determination is written into the QA report and acceptance will re-check it.

Functional feature

If any condition is met, treat it as functional:

Changes user-visible behavior, UI, API, CLI, background tasks, permissions, persistence, integrations, runtime routing, or error semantics.
The success criteria of the roadmap / design contain runtime behaviors such as "users can...", "the system will...", "real request / turn / smoke / e2e / browser / API".
Review marks some verification as must-cover, and it corresponds to an actual runtime path.

The core paths of a functional feature must not be downgraded to residual-risk:

The key scenarios in design Section 3, checklist checks, roadmap success criteria, and items in review Test And QA Focus that belong to core functional paths must have actual runtime evidence: choose an appropriate combination of unit / integration / e2e / browser / API / CLI / manual smoke, but the evidence must allow the behavior to be observed.
Running only typecheck / lint / diff review cannot prove that core functional paths pass.
When external credentials, services, devices, network, or cost prevent the core paths from running, the conclusion is blocked; if the implementation clearly lacks tests or the behavior fails, the conclusion is failed。
Only if design explicitly defined a path as "conditionally non-blocking" before implementation (for example, when CI has no auth, only the unavailable path is verified), and QA has verified the alternative path and the skip reason, may this be written as residual-risk. QA cannot change an originally core acceptance path into non-blocking on the spot.

Non-functional feature

The following types are treated as non-functional by default, unless they also change runtime behavior:

Documentation, architecture / roadmap / requirement / learning write-back.
Pure refactoring, naming cleanup, directory migration, dead code cleanup, with a declaration of unchanged behavior.
Test reinforcement, type reinforcement, lint/build configuration, script cleanup, generated artifact sync.
Internal design documents, protocol descriptions, agent skill copy updates.

Non-functional features are not required to use e2e / browser / API / manual real-path verification; they may pass via static checks, diff review, documentation consistency, type checking, build, targeted tests, snapshots, or schema validation. The QA report must state the reason why "end-to-end runtime verification is not needed" and the alternative evidence actually used by this feature.

If a non-functional feature touches production routes, user-visible copy, permissions, security boundaries, data migration, or external integrations, then even if the goal is "refactoring/cleanup", the relevant touch points are still verified as functional core paths.

Startup Check

{slug}-design.md exists and status=approved。
{slug}-checklist.yaml exists,steps all done，checks is still not fully passed by acceptance.
{slug}-review.md exists, frontmatter doc_type=feature-review、status=passed, no unresolved blocking findings。
In goal / gate mode, the evidence pack, gate results, and DoD results must exist; gate warnings and Residual Risks are included in the QA matrix.
If the review report is not based on the current diff: first return to cs-code-review for re-review. qa-fix or other code changes will make the old review stale.
If there is already {slug}-qa.md：
- status=passed and the diff has not changed: prompt that it may proceed to cs-feat-accept。
- status=failed / blocked: read the old failure items and confirm whether this is a retest after qa-fix.
- diff has changed: re-run QA and record the round in the report.

QA Process

1. Build the verification matrix

Summarize the QA matrix from the key scenarios in design Section 3, design must-run commands, review Test And QA Focus, review residual risk, and the evidence pack's Validation Commands / DoD Results / Residual Risks:

Feature type：functional / non-functional / mixed。
Criticality: core-functional / supporting / non-functional.
Scenario: input / trigger → expected observable result.
Evidence type: unit / function / integration / e2e / browser / API / manual / typecheck / diff.
Command or action: specific command, page path, API request, manual step.
Failure criterion: what result counts as fail; do not write "looks normal".
Attribution: this feature / existing baseline / environment unavailable / cannot determine.

Prefer the project's existing test entry points and existing tools; do not introduce a new test framework just for QA. When new test code is needed, QA does not write it directly; record it as a failed item and return to cs-feat-impl qa-fix。

2. Run verification

Run in order from cheap to expensive, from automated to manual:

Baseline-related commands: typecheck / lint / build / targeted unit or the project's equivalent commands.
unit / function / integration / e2e tests directly related to the feature.
Key verification points, gate warnings, and residual risks identified by review and the evidence pack.
Functional frontend / user-visible changes: browser verification, screenshots, or explicit manual paths; running only typecheck does not count as QA passing.
Functional API / backend / runtime capabilities: real requests, integration tests, or reproducible command-line calls.
Non-functional changes: static checks, diff re-review, documentation consistency, schema/snapshot/type/build/targeted tests, and record why end-to-end runs are unnecessary.
Cleanliness re-review: debug output, temporary TODO/FIXME, commented-out code, unused imports, out-of-plan files.

Each piece of evidence must record the command, exit code, or observation result. When a command cannot be run, write the specific reason: missing dependency, service cannot start, missing external credentials, environment limitation, too costly. Not runnable is not an automatic pass.

3. Verdict

passed: all blocking QA items pass; all functional core paths have run evidence; non-functional features have sufficient alternative evidence and reasons for "no end-to-end run needed"; non-runnable items leave only non-core residual risk.
failed: key scenarios fail, required commands fail and are attributed to this feature, review focus points are not covered, test gaps affect acceptance credibility, functional frontend has no browser verification, functional API / runtime paths have no actual call evidence.
blocked: input missing, review not passed, environment unavailable to the point where core behavior cannot be determined, dirty diff attribution unclear.

When QA failed, do not fix code directly. After outputting the report, enter cs-feat-impl qa-fix; after qa-fix finishes fixing, you must first rerun cs-code-review, then rerun cs-feat-qa。

residual-risk can only carry non-core risks, explicitly deferred items, or boundaries of non-functional aspects that cannot be fully re-reviewed. It cannot carry acceptance gaps such as "core functional paths were not run", "real user paths were not verified", or "required commands were not executed".

Report template

Report path:.codestable/features/{feature}/{slug}-qa.md。

---
doc_type: feature-qa
feature: YYYY-MM-DD-slug
status: passed|failed|blocked
tested: YYYY-MM-DD
round: 1
---

# {slug} QA 报告

## 1. Scope And Inputs

- Design: {path}
- Checklist: {path}
- Review: {path}
- Evidence pack: {path / none}
- Gate results: {path / none}
- DoD results: {path / none}
- Diff basis: {git status / git diff 摘要}
- Baseline dirty files: {none / 列表 + 归因}
- Feature type: functional|non-functional|mixed
- Core evidence gate: {功能性核心路径列表；非功能性写不需要端到端运行的理由}

## 2. Verification Matrix

| ID | 来源 | 核心性 | 场景 / 风险 | 证据类型 | 命令或动作 | 期望 | 结果 |
|---|---|---|---|---|---|---|---|
| QA-001 | design S1 | core-functional/supporting/non-functional | {描述} | unit/integration/e2e/browser/API/manual/typecheck/diff | `{命令}` | {期望} | pass/fail/blocked |

## 3. Command Results

- `{命令}` → exit {code}：{摘要}
- 未运行：{命令} → {具体原因 + 是否阻塞}

## 4. Scenario Results

- [ ] QA-001 {场景}：pass/fail/blocked
  - Evidence: {输出 / 截图 / 请求响应 / 手工路径}
  - Notes: {归因 / 风险}

## 5. Findings

### failed

- [ ] QA-001 {失败项}
  - Evidence: {证据}
  - Impact: {为什么影响验收}
  - Expected fix scope: {只描述失败边界，不替实现写方案}

### blocked

- [ ] QA-00N {阻塞项}

### residual-risk

- {无法完全验证但不阻塞的风险；没有写 none}
- 不允许出现：功能性核心路径未运行、真实用户/API/运行时路径未验证、必跑命令未执行。

## 6. Cleanliness

- Debug output: pass/fail
- Temporary TODO/FIXME/XXX: pass/fail
- Commented-out code: pass/fail
- Unused imports / dead code from this feature: pass/fail
- Out-of-scope files: pass/fail

## 7. Verdict

- Status: passed|failed|blocked
- Next: `cs-feat-accept` | `cs-feat-impl` qa-fix -> `cs-code-review` -> `cs-feat-qa` | 补齐环境后重跑 `cs-feat-qa`

When there is no finding of a certain type, write none, do not delete sections; re-testing must allow comparison.

qa-fix handoff

If QA failed：

report status: failed。
tell the user the next step is to trigger cs-feat-impl 's qa-fix mode.
qa-fix only fixes QA failed / blocked items; it does not handle incidental findings and does not expand feature scope.
After qa-fix finishes fixing, the diff will change, so you must rerun cs-code-review; after review passed, rerun cs-feat-qa。
Only after QA passed can you enter cs-feat-accept。

If QA blocked：

first supplement environment / input / review status; do not write blocked as passed.

If QA passed：

tell the user the next step is cs-feat-accept。

Exit conditions

Read attention, design, checklist, review, implementation evidence, git status, git diff.
Confirmed review passed and based on the current diff.
Determined the feature type, and clearly stated the functional core paths or the reason for non-functional substitute evidence.
Established a verification matrix covering key design scenarios, required commands, review Test And QA Focus, review residual risk, evidence pack commands / residual risks, and marked the criticality of each item.
Ran the runnable verification commands / browser / API / manual checks, and recorded the results.
All functional core paths have actual run evidence; if missing, QA is failed / blocked and cannot be written as passed.
For non-functional features, if no e2e / browser / API was done, clearly stated why it is not needed and what substitute evidence was used.
All items not run have specific reasons and a blocking judgment.
Completed the cleanliness recheck.
Wrote .codestable/features/{feature}/{slug}-qa.md。
When failed / blocked, did not proceed to acceptance, but instead pointed to qa-fix or environment remediation.
When passed, clearly told the user the next step cs-feat-accept。

Common pitfalls

Writing QA as a second code review, without running any evidence.
Running only typecheck and then claiming the frontend user paths pass.
Writing functional core paths that were not run as residual-risk, and still marking passed.
Mechanically requiring e2e for non-functional features such as documentation / architecture / test reinforcement, instead of using more appropriate static / consistency / targeted test evidence.
Writing passed when commands failed but the attribution is unclear.
Fixing code directly during the QA phase, bypassing qa-fix / review re-review.
After qa-fix, skipping review and directly rerunning QA or proceeding to acceptance.
Not recording the reasons for items not run, causing acceptance to be unable to judge the remaining risk.