qa-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QA Plan

QA计划

This skill generates a structured QA plan for a sprint, feature, or individual story. It reads all in-scope story files and their referenced GDDs, classifies each story by test type, and produces a plan that tells developers exactly what to automate, what to verify manually, what the smoke test scope is, and when to bring in a playtester.

Run this before a sprint begins so the team knows upfront what testing work is required. A test plan written after implementation is a post-mortem, not a plan.

Output:

production/qa/qa-plan-[sprint-slug]-[date].md

该Skill可为sprint、功能或单个故事生成结构化QA计划。它会读取所有范围内的故事文件及其引用的GDDs，按测试类型对每个故事进行分类，并生成一份计划，明确告知开发人员哪些内容需要自动化、哪些需要手动验证、冒烟测试的范围是什么，以及何时引入Playtest人员。

请在sprint开始前运行该Skill，以便团队提前了解所需的测试工作。在实现后编写的测试计划属于事后总结，而非真正的计划。

Output:

production/qa/qa-plan-[sprint-slug]-[date].md

Phase 1: Parse Scope

阶段1：解析范围

Argument:

$ARGUMENTS

(blank = ask user via AskUserQuestion)

Determine scope from the argument:

sprint
— read the most recent file in
```
production/sprints/
```
, extract every story file path referenced. If
```
production/sprint-status.yaml
```
exists, use it as the primary story list and fall back to the sprint plan for story metadata.
feature: [system-name]
— glob
```
production/epics/*/story-*.md
```
, filter to stories whose file path or title contains the system name. Also check the epic index file (
```
EPIC.md
```
) in that system's directory.
story: [path]
— validate that the path exists and load that single file.
No argument — use
```
AskUserQuestion
```
:
- "What is the scope for this QA plan?"
- Options: "Current sprint", "Specific feature (enter system name)", "Specific story (enter path)", "Full epic"

After resolving scope, report: "Building QA plan for [N] stories in [scope]."

If a story file path is referenced but the file does not exist, note it as MISSING and continue with the remaining stories. Do not fail the entire plan for one missing file.

Argument:

$ARGUMENTS

(blank = ask user via AskUserQuestion)

从参数中确定范围：

sprint
— 读取
```
production/sprints/
```
中最新的文件，提取所有引用的故事文件路径。如果
```
production/sprint-status.yaml
```
存在，则将其作为主要故事列表，并在需要故事元数据时回退到sprint计划。
feature: [system-name]
— 匹配
```
production/epics/*/story-*.md
```
路径，筛选出文件路径或标题包含系统名称的故事。同时检查该系统目录下的史诗索引文件（
```
EPIC.md
```
）。
story: [path]
— 验证路径是否存在并加载该单个文件。
无参数 — 使用
```
AskUserQuestion
```
：
- "本次QA计划的范围是什么？"
- 选项："当前sprint"、"特定功能（输入系统名称）"、"特定故事（输入路径）"、"完整史诗"

解析范围后，告知用户："正在为[范围]中的[N]个故事构建QA计划。"

如果某个故事文件路径被引用但文件不存在，标记为MISSING并继续处理剩余故事。不会因单个缺失文件导致整个计划失败。

Phase 2: Load Inputs

阶段2：加载输入

For each in-scope story file, read the full file and extract:

Story title and story ID (from filename or header)
Story Type field (if present in the file header — e.g.,
```
Type: Logic
```
)
Acceptance criteria — the complete numbered/bulleted list
Implementation files — listed under "Files to Create / Modify" or similar
Engine notes — any engine API warnings or version-specific notes
GDD reference — the GDD path(s) cited
ADR reference — the ADR(s) cited
Estimate — hours or story points if present
Dependencies — other stories this one depends on

After reading stories, load supporting context once (not per story):

```
design/gdd/systems-index.md
```
— to understand system priorities and which GDDs are approved
For each unique GDD referenced across all stories: read only the Acceptance Criteria and Formulas sections. Do not load full GDD text — these two sections contain the testable requirements and the math to verify.
```
docs/architecture/control-manifest.md
```
— scan for forbidden patterns that automated tests should guard against (if the file exists)

If no GDD is referenced in a story, note it as a gap but do not block the plan. The story will be classified using acceptance criteria alone.

对于每个范围内的故事文件，读取完整文件并提取以下信息：

Story title和故事ID（从文件名或标题栏提取）
Story Type字段（如果文件标题栏中存在，例如
```
Type: Logic
```
）
Acceptance criteria — 完整的编号/项目符号列表
实现文件 — 列在"Files to Create / Modify"或类似标题下的文件
引擎说明 — 任何引擎API警告或特定版本相关说明
GDD引用 — 引用的GDD路径
ADR引用 — 引用的ADR
估算 — 若存在则提取工时或故事点数
依赖项 — 本故事依赖的其他故事

读取完所有故事后，一次性加载支持上下文（而非逐个故事加载）：

```
design/gdd/systems-index.md
```
— 用于了解系统优先级以及哪些GDD已获批
对于所有故事中引用的每个唯一GDD：仅读取Acceptance Criteria和Formulas部分。无需加载完整GDD文本——这两个部分包含可测试的需求和用于验证的计算公式。
```
docs/architecture/control-manifest.md
```
— 扫描自动化测试应防范的禁用模式（如果文件存在）

如果某个故事未引用任何GDD，标记为缺口但不阻止计划执行。该故事将仅通过Acceptance criteria进行分类。

Phase 3: Classify Each Story

阶段3：分类每个故事

For each story, assign a Story Type. If the story already has a

Type:

field in its header, use that value and validate it against the criteria below. If the field is missing or ambiguous, infer the type from the acceptance criteria.

Story Type	Classification Indicators
Logic	Acceptance criteria reference calculations, formulas, numerical thresholds, state transitions, AI decisions, data validation, buff/debuff stacking, economy transactions, or any testable computation
Integration	Criteria involve two or more systems interacting, signals or events propagating across system boundaries, save/load round-trips, network sync, or persistence
Visual/Feel	Criteria reference animation behaviour, VFX, shader output, "feels responsive", perceived timing, screen shake, particle effects, audio sync, or visual feedback quality
UI	Criteria reference menus, HUD elements, buttons, screens, dialogue boxes, inventory panels, tooltips, or any player-facing interface element
Config/Data	Changes are limited to balance tuning values, data files, or configuration — no new code logic is involved

Mixed stories (e.g., a story that adds both a formula and a UI display): assign the primary type based on which acceptance criteria carry the highest implementation risk, and note the secondary type. Mixed Logic+Integration or Visual+UI combinations are the most common.

After classifying all stories, produce a classification summary table in conversation before proceeding to Phase 4. This gives the user visibility into how tests will be allocated.

为每个故事分配Story Type。如果故事标题栏中已存在

Type:

字段，则使用该值并根据以下标准进行验证。如果字段缺失或含义模糊，则从Acceptance criteria推断类型。

故事类型（Story Type）	分类指标
Logic	Acceptance criteria涉及计算、公式、数值阈值、状态转换、AI决策、数据验证、增益/减益叠加、经济交易或任何可测试的计算内容
Integration	验收标准涉及两个或多个系统交互、跨系统边界传播的信号或事件、保存/加载往返、网络同步或持久化
Visual/Feel	验收标准涉及动画行为、VFX、着色器输出、"响应流畅"、感知时序、屏幕震动、粒子效果、音频同步或视觉反馈质量
UI	验收标准涉及菜单、HUD元素、按钮、屏幕、对话框、inventory面板、工具提示或任何面向玩家的界面元素
Config/Data	变更仅局限于平衡调优值、数据文件或配置——不涉及新的代码逻辑

混合类型故事（例如同时添加公式和UI显示的故事）：根据哪部分Acceptance criteria具有最高实现风险分配主要类型，并注明次要类型。Logic+Integration或Visual+UI组合是最常见的混合类型。

完成所有故事分类后，在对话中生成分类汇总表，然后再进入阶段4。这使用户能够了解测试将如何分配。

Phase 4: Generate Test Plan

阶段4：生成测试计划

Assemble the full QA plan document. Use this structure:

markdown

undefined

组装完整的QA计划文档，采用以下结构：

markdown

undefined

QA Plan: [Sprint/Feature Name]

Date: [date] Generated by: /qa-plan Scope: [N stories across [N systems]] Engine: [engine name from .claude/docs/technical-preferences.md, or "Not configured"] Sprint File: [path to sprint plan if applicable]

Test Summary

Story	Type	Automated Test Required	Manual Verification Required
[story title]	Logic	Unit test — `tests/unit/[system]/`	None
[story title]	Integration	Integration test — `tests/integration/[system]/`	Smoke check
[story title]	Visual/Feel	None (not automatable)	Screenshot + lead sign-off
[story title]	UI	Interaction walkthrough	Manual step-through
[story title]	Config/Data	Data validation test	Spot-check in-game values

Story	Type	Automated Test Required	Manual Verification Required
[story title]	Logic	Unit test — `tests/unit/[system]/`	None
[story title]	Integration	Integration test — `tests/integration/[system]/`	Smoke check
[story title]	Visual/Feel	None (not automatable)	Screenshot + lead sign-off
[story title]	UI	Interaction walkthrough	Manual step-through
[story title]	Config/Data	Data validation test	Spot-check in-game values

Automated Tests Required

[Story Title] — [Type]

Test file path:

tests/[unit|integration]/[system]/[story-slug]_test.[ext]

What to test:

[Specific formula or rule from the GDD Formulas section]
[Each named state transition or decision branch]
[Each side effect that should or should not occur]

Edge cases to cover:

Zero/minimum input values (e.g., 0 damage, empty inventory)
Maximum/boundary input values (e.g., max level, stat cap)
Invalid or null input (e.g., missing target, dead entity)
[Any edge case explicitly called out in the GDD Edge Cases section]

Estimated test count: ~[N] unit tests

[If no GDD formula reference was found for this story, note:] No formula found in referenced GDD — test cases must be derived from acceptance criteria directly. Review the GDD Formulas section before writing tests.

Test file path:

tests/[unit|integration]/[system]/[story-slug]_test.[ext]

What to test:

[Specific formula or rule from the GDD Formulas section]
[Each named state transition or decision branch]
[Each side effect that should or should not occur]

Edge cases to cover:

Zero/minimum input values (e.g., 0 damage, empty inventory)
Maximum/boundary input values (e.g., max level, stat cap)
Invalid or null input (e.g., missing target, dead entity)
[Any edge case explicitly called out in the GDD Edge Cases section]

Estimated test count: ~[N] unit tests

Manual QA Checklist

[Story Title] — [Type]

Verification method: [Screenshot + designer sign-off | Playtest session | Manual step-through | Comparison against reference footage] Who must sign off: [designer / lead-programmer / qa-lead / art-lead] Evidence to capture: [screenshot of X | video clip of Y | written playtest notes | side-by-side comparison]

Checklist:

[Specific observable condition — concrete and falsifiable]
[Another condition]
[Every acceptance criterion translated into a manual check item]

If any criterion uses subjective language ("feels", "looks", "seems"), it must be supplemented with a specific benchmark or a playtest protocol note.

Checklist:

[Specific observable condition — concrete and falsifiable]
[Another condition]
[Every acceptance criterion translated into a manual check item]

If any criterion uses subjective language ("feels", "looks", "seems"), it must be supplemented with a specific benchmark or a playtest protocol note.

Smoke Test Scope

Critical paths to verify before any QA hand-off for this sprint:

Game launches to main menu without crash
New game / new session can be started
[Primary mechanic introduced or changed this sprint]
[Any system with a regression risk from this sprint's changes]
Save / load cycle completes without data loss (if save system exists)
Performance is within budget on target hardware (no new frame spikes)

Smoke tests are verified by the developer via
/smoke-check
. Reference this list when running that skill.

Critical paths to verify before any QA hand-off for this sprint:

Game launches to main menu without crash
New game / new session can be started
[Primary mechanic introduced or changed this sprint]
[Any system with a regression risk from this sprint's changes]
Save / load cycle completes without data loss (if save system exists)
Performance is within budget on target hardware (no new frame spikes)

Smoke tests are verified by the developer via
/smoke-check
. Reference this list when running that skill.

Playtest Requirements

Story	Playtest Goal	Min Sessions	Target Player Type
[story]	[What question must the session answer?]	[N]	[new player / experienced]

Sign-off requirement: Playtest notes must be written to

production/session-logs/playtest-[sprint]-[story-slug].md

and reviewed by the [designer / qa-lead] before the story can be marked COMPLETE.

If no stories require playtest validation: No playtest sessions required for this sprint.

Story	Playtest Goal	Min Sessions	Target Player Type
[story]	[What question must the session answer?]	[N]	[new player / experienced]

Sign-off requirement: Playtest notes must be written to

production/session-logs/playtest-[sprint]-[story-slug].md

and reviewed by the [designer / qa-lead] before the story can be marked COMPLETE.

If no stories require playtest validation: No playtest sessions required for this sprint.

Definition of Done — This Sprint

A story is DONE when ALL of the following are true:

All acceptance criteria verified — via automated test result OR documented manual evidence (screenshot, video, or playtest notes with sign-off)
Test file exists at the specified path for all Logic and Integration stories
Manual evidence document exists for all Visual/Feel and UI stories
Smoke check passes (run
```
/smoke-check sprint
```
before QA hand-off)
No regressions introduced
Code reviewed (via
```
/code-review
```
or documented peer review)
Story file updated to
```
Status: Complete
```
(via
```
/story-done
```
)


When generating content, use the actual story titles, GDD formula text, and
acceptance criteria extracted in Phase 2. Do not use placeholder text — every
test entry should reflect the real requirements of these specific stories.

---

A story is DONE when ALL of the following are true:

All acceptance criteria verified — via automated test result OR documented manual evidence (screenshot, video, or playtest notes with sign-off)
Test file exists at the specified path for all Logic and Integration stories
Manual evidence document exists for all Visual/Feel and UI stories
Smoke check passes (run
```
/smoke-check sprint
```
before QA hand-off)
No regressions introduced
Code reviewed (via
```
/code-review
```
or documented peer review)
Story file updated to
```
Status: Complete
```
(via
```
/story-done
```
)


生成内容时，请使用阶段2中提取的实际故事标题、GDD公式文本和Acceptance criteria。请勿使用占位符文本——每个测试条目都应反映这些特定故事的真实需求。

---

Phase 5: Write Output

阶段5：写入输出

Show the complete plan in conversation (or a summary if the plan is very long), then ask:

"May I write this QA plan to

production/qa/qa-plan-[sprint-slug]-[date].md

Write the plan exactly as generated — do not truncate.

After writing:

"QA plan written to

production/qa/qa-plan-[sprint-slug]-[date].md

Next steps:

Share this plan with the team before sprint implementation begins
Run
```
/smoke-check sprint
```
after all stories are implemented to gate QA hand-off
For Logic/Integration stories, create the test files at the listed paths before marking stories done —
```
/story-done
```
checks for them"

在对话中展示完整计划（如果计划过长则展示摘要），然后询问：

"是否可以将此QA计划写入

production/qa/qa-plan-[sprint-slug]-[date].md

？"

严格按照生成的内容写入计划——请勿截断。

写入完成后：

"QA计划已写入

production/qa/qa-plan-[sprint-slug]-[date].md

。

后续步骤：

在sprint实现开始前与团队共享此计划
所有故事实现完成后运行
```
/smoke-check sprint
```
，作为QA交接的准入条件
对于Logic/Integration类型的故事，在标记故事完成前创建指定路径下的测试文件——
```
/story-done
```
会检查这些文件"

Collaborative Protocol

协作协议

Never write the plan without asking — Phase 5 requires explicit approval.
Classify conservatively: when a story is ambiguous between Logic and Integration, classify it as Integration — it requires both unit and integration tests.
Do not invent test cases beyond what acceptance criteria and GDD formulas support. If a formula is absent from the GDD, flag it rather than guessing.
Playtest requirements are advisory: the user decides whether a playtest is warranted for borderline Visual/Feel stories. Flag the case; do not mandate.
Use
```
AskUserQuestion
```
for scope selection when no argument is provided. Keep all other phases non-interactive — present findings, then ask once to approve the write.

未获许可切勿写入计划 — 阶段5需要明确的批准。
保守分类：当故事在Logic和Integration之间存在歧义时，将其分类为Integration——它需要单元测试和集成测试。
请勿超出Acceptance criteria和GDD公式的范围编造测试用例。如果GDD中缺少公式，请标记该问题而非猜测。
Playtest要求为建议性内容：对于边界模糊的Visual/Feel类型故事，由用户决定是否需要Playtest。标记该情况，但不要强制要求。
当无参数提供时，使用
```
AskUserQuestion
```
选择范围。所有其他阶段为非交互式——展示结果，然后仅询问一次是否批准写入。