qa-review-templates

name	QA Review Templates
description	Sidecar data for /qa workflow — Red Team personas, dimension checklists, and QA report templates loaded just-in-time.
source	catalog

QA Review Skills

Architecture: Sidecar Skill Parent Workflow: /qa

This skill provides the data structures, templates, and complex persona definitions required by the /qa workflow. By keeping this out of the main workflow file, we maintain a lean execution loop while ensuring high-quality, standardized Q&A outputs.

When to Load

File	When	Purpose
This file (§1)	Step 0.5 — Pre-QA Strategy	QA Report template structure (created at kickoff)
This file (§2)	Step 2 — Generate Questions	Persona question banks (inspiration)
This file (§3)	Step 2 — Generate Questions	Dimension seed patterns (per tag)
This file (§5)	Step 0.5 — Process Selection	Process selection logic & comparison matrix
stacks/[name].md	Step 0 — Pre-flight	Stack-specific QA gotchas & Skill Router
domains/csa.md	Step 0 — Pre-flight	CSA-specific QA checks & persona definition
references/process-full-plan.md	Step 0.5 — Process = Full-Plan	Waterfall Gate process template
references/process-phase-loop.md	Step 0.5 — Process = Phase-Loop	Iterative Gate process template
references/process-risk-driven.md	Step 0.5 — Process = Risk-Driven	Pareto Gate process template
references/process-adversarial.md	Step 0.5 — Process = Adversarial	Devil's Advocate process template

1. QA Report Template

When creating the QA Report at Step 0.5 (Pre-QA Strategy), the Agent MUST format the file according to this structure and save it to Projects/[project]/artifacts/qa/qa-[date]-[mode]-[target]-[seq].md.

Language Guard: The Agent MUST translate all headers, table columns, and labels in this template (e.g., "Executive Summary", "Verdict", "Action Items") into the user's preferred language defined in .para-workspace.yml (e.g., Vietnamese), while keeping the markdown structure and logic tags ([LOGIC], [SEC]) intact.

# 🛡️ QA Review Report: [Target Artifact Name]

> **Target:** `[Path to artifact]`
> **Target Version:** `[Last Modified Timestamp or Git Hash]`
> **Workflow Mode:** `/qa [plan/spec/artifact/audit]`
> **Process:** `[full-plan / phase-loop (specify N phases) / risk-driven (specify N risks) / adversarial]` (MUST specify the exact count of phases/risks in parentheses to prevent context decay)
> **Dimensions:** `[LOGIC, SEC, FEAS, COMP, CONS, DEP, GOV, OSS]`
> **Verdict:** `[✅ Ready | ⚠️ Action Required | 🔴 Blocked]`

## 0. QA Strategy (Pre-QA)

### Focus Areas — Coverage Tracker

| # | Focus Area | Round 1 | Round 2 | Status |
|---|---|---|---|---|
| 1 | **[Area Name]** — [Brief scope description] | — | — | ⏳ Pending |
| ... | | | | |

### Red Team Roster
- 🏗️ **[Persona]:** [Justification for selection]
- ...

### Process Log

| Round | Trigger | Scope | Questions | Critical | Fixed |
|---|---|---|---|---|---|
| *(empty — rows appended after each round)* |

### 🚀 Next Steps

*(Generated by Agent after each round — see Step 7. Mode-dependent selection)*

**For Plan Mode:**

| Action | Command | Description |
|---|---|---|
| **Start Development** | `/plan [project-name] dev` | Activate plan and start execution via Plan Dev Gate (Mandatory per Rule 3d) |
| **Deep review** | `deep [aspect]` | Add another review round if needed. |
| **Full audit** | `/qa audit` | Run Compliance Audit on the fixed Plan. |
| **Close QA** | `done` | Close the QA report, no further review. |

**For Spec Mode:**

| Action | Command | Description |
|---|---|---|
| **Create Plan** | `/plan create [version]` | Create a new implementation plan based on the approved spec (Recommended next step) |
| **Sync Backlog** | `/backlog sync` | Synchronize spec acceptance criteria into project backlog |
| **Deep review** | `deep [aspect]` | Add another review round on the specification if needed |
| **Close QA** | `done` | Close the QA report, no further review |


## 1. Executive Summary

| Category | Count |
| :--- | :--- |
| **Total Questions Raised** | 0 |
| **✅ Resolved/OK** | 0 |
| **⚠️ Minor Issues** | 0 |
| **🔴 Critical Blockers** | 0 |

## 2. Red Team Findings

*(Group findings by Phase or Section. Use the Personas to label the questions).*

### 📌 [Phase/Section Name]

#### 🏗️ Principal Architect
**Q [LOGIC]:** [Question]
**A:** [Answer/Resolution]
**Verdict:** [✅/⚠️/🔴]

#### 🤖 AI Security Expert
**Q [SEC]:** [Question]
**A:** [Answer/Resolution]
**Verdict:** [✅/⚠️/🔴]

#### 💼 Project Tech Lead
**Q [GOV]:** [Question]
**A:** [Answer/Resolution]
**Verdict:** [✅/⚠️/🔴]

## 3. Action Items & Fixes Applied

- [ ] (Fixed) Changed API payload to include proper validation in Phase 2.
- [ ] (Pending) Update timeline for Phase 3 integration testing.

2. Persona Question Banks

CRITICAL RULE FOR AGENTS: DO NOT copy these reference questions verbatim. They serve strictly as a guide to illustrate the style and angle of questioning for each Persona. The Agent MUST dynamically generate the actual probing questions based on the target Spec's technical details, the active system design (sysdesign-*.md), and the physical entities (APIs, DB tables, files) of the codebase.

🏗️ Principal Architect ([LOGIC], [DEP])

• Does this architecture introduce a single point of failure?
• Is there a circular dependency between these modules?
• What happens if the upstream service is offline?
• Does this scale to 10x the current data load?
• "Phase N task X.Y requires [output], but which prior task produces it?"
• "If task X.Y fails, does the plan have a fallback or does it block everything?"
• "The dependency flow shows A → B → C, but task C.1 references A directly — is B actually needed?"
• [Spec] Does this spec clearly define the database schema (DDL) and are there any conflicts in constraints (e.g., NOT NULL vs ON DELETE SET NULL)?
• [Spec] Does the proposed schema migration path preserve existing data and prevent corruption?
• [Spec] Are all API payloads, HTTP status codes, and response structures explicitly typed and validated?
• Rule: If a 🔴 Critical architectural or logic flaw is found, proactively suggest @[/brainstorm] to explore multiple solution options before proposing a quick patch.

🛡️ Security Auditor ([SEC])

• Are credentials or tokens being logged or stored in plaintext?
• Is this bash command vulnerable to injection?
• Do we have proper validation for user-supplied input here?
• Are we bypassing standard CORS/CSRF protections?
• "Task X.Y runs git push — is there a HARNESS GUARD on the line above?"
• "This step auto-runs a command — could it have destructive side-effects?"
• "Are any secrets, API keys, or credentials referenced in this artifact?"
• [Spec] Is authorization/access control (roles, permissions) strictly defined for every proposed API route?
• [Spec] How are sensitive parameters (passwords, tokens) handled in transit, storage, and in logging?
• [Spec] Does the spec address protection against common vulnerabilities (e.g., CSRF, IDOR, path traversal, injection)?

🤖 AI Security & Boundary Expert ([SEC], [LOGIC])

• Can a malicious file (e.g., Markdown) trigger prompt injection?
• Are we granting the LLM too much autonomy (e.g., auto-commit without review)?
• Could the graph extraction leak sensitive environment variables to the LLM context?

🌍 Open Source Maintainer ([OSS], [CONS])

• Are there hardcoded absolute paths (e.g., /Users/name/...)?
• Does this implementation violate our 'Clean Room Design' policy?
• Is this documentation compliant with our English-First global standard?
• Is the license header required for this new file?

⏱️ Delivery Manager ([FEAS], [COMP])

• Is this time estimate realistic given the team's capacity?
• Are we missing prerequisite setup steps before execution?
• Is this feature strictly necessary, or is it scope creep?
• "Task X.Y assumes [tool] is installed — has this been verified?"
• "This step uses npx [package] — but the code hasn't been published yet. Should it use local build?"

🔍 QA/Test Lead ([CONS])

• How exactly do we verify this step is successful?
• What is the expected behavior if the input is null or undefined?
• Phase X says one thing, but Phase Y contradicts it — which is correct?
• "Phase heading says 'Commit #2/2' but Git Operation Summary shows 3 commits — which is correct?"
• "Version is '0.9.0' in Goal but '0.8.6' in the code snippet — mismatch?"
• "Task numbering jumps from 3.4 to 3.6 — is 3.5 missing or was it renumbered?"
• [Spec] Are the acceptance criteria (UC/Acceptance Criteria) clear, testable, and free of vague language?
• [Spec] Are edge cases (null inputs, database offline, API timeout) covered in the spec?
• [Spec] Does the spec define clear measurable targets (e.g., latency threshold, error rate limit)?

💼 Project Tech Lead ([GOV], [COMP])

Context requirement: This persona's questions are only meaningful AFTER loading the project's full governance context (rules, skills, release process) in Pre-flight Step 5.

• Check for project-level QA checklists in .agents/rules/qa.md. If it exists, read it and integrate its questions directly into the Tech Lead's checklist.
• "The project has maintenance rule M[N] requiring version sync across N files — does the plan list ALL locations?"
• "Project type is OSS with tarball release — does the plan include a Release phase per M6?"
• "Maintenance rule M1 restricts git add to repo/ only — are all git commands scoped correctly?"
• "The project Governance Checklist has N items — does it cover ALL triggered rules from .agents/rules.md?"
• "This project uses Template-First editing (M5) — does the plan edit repo/templates/ before workspace copies?"
• "Walkthrough is missing the project's release verification (gh release view) — should it be added?"
• "The plan bumps version but has no tarball/release step — is this a version bump orphan?"
• "The project has a build+test rule (M4) — does every Phase include build verification before commit?"
• "Project distributes AI Intelligence via tool.manifest.yml — are shipped_in and template versions updated?"
• "The install-hooks.sh pre/post lifecycle hooks — are they affected by this plan's changes?"
• "Does the plan update corresponding knowledge templates, schema definitions, or documentation references to prevent knowledge drift when modifying API structures, configurations, or core features?"
• "Does the plan evaluate if a formal release packaging and deployment step is required to distribute compiled binaries/assets to end-users instead of only pushing source code?"
• Rule: If a 🔴 Critical governance or compliance violation is found, proactively suggest @[/brainstorm] to explore multiple solution options before proposing a quick patch.

📐 CSA Expert ([CSA])

• Does the plan allocate and map every HTML spec anchor from the baseline specification file into the plan's CSA mapping table?
• Are there any new features in the plan that lack spec anchors?
• Do the proposed anchor locations in the plan comply with micro-anchoring principles? (e.g., avoid clustering @para-doc comments; anchor comments must sit directly above the corresponding public entity declaration).
• Do all suggested or existing spec anchor IDs follow the standard kebab-case naming convention with a csa- prefix (e.g., csa-{module}-{name-slug})?
• Does the plan include steps to verify the Post-Draft Audit and the Plan Dev Gate?
• Rule: If a 🔴 Critical CSA traceability gap is detected (e.g., missing mappings or incorrect anchoring), suggest resolving them before finalizing the review.

3. Dimension Seed Patterns

Quick-reference seed patterns per dimension tag. Agent uses these alongside the Persona Question Banks (§2) when generating questions at Step 2.

[LOGIC] Logic & Sequencing

• "Phase N task X.Y requires [output], but which prior task produces it?"
• "If task X.Y fails, does the plan have a fallback or does it block everything?"

[SEC] Security & Safety

• "Task X.Y runs git push — is there a HARNESS GUARD on the line above?"
• "This step auto-runs a command — could it have destructive side-effects?"

[FEAS] Feasibility

• "Task X.Y assumes [tool] is installed — has this been verified?"
• "The time estimate is [N days] for [scope] — is this realistic given [complexity]?"

[COMP] Completeness

• "The Walkthrough has N items but Phase 3 added [feature] — is it covered?"
• "Risk table lists N risks but Phase N has no HARNESS GUARD — should one be added?"
• "git add lists files A, B but task also modifies file C — is C missing?"

[CONS] Consistency

• "Version is '0.9.0' in Goal but '0.8.6' in the code snippet — mismatch?"
• "Task numbering jumps from 3.4 to 3.6 — is 3.5 missing or was it renumbered?"

[DEP] Dependencies

• "Phase N uses graphology npm package — is it listed in package.json?"
• "This function calls detectGodNodes() which is defined in Phase 3 — but we're in Phase 2?"

[GOV] Project Governance

• "The project has maintenance rule M3 requiring version sync across N files — does the plan list ALL locations?"
• "Project type is OSS with tarball release — does the plan include a Release phase per M6?"
• "Maintenance rule M1 restricts git add to repo/ only — are all git commands scoped correctly?"
• "The plan bumps version but has no tarball/release step — is this a version bump orphan?"
• "The project Governance Checklist has N items — does it cover ALL triggered rules?"
• "Are corresponding knowledge templates or schemas synchronized in the release phase to prevent knowledge drift after API or tool logic changes?"
• "Has the plan evaluated the necessity of a formal release packaging step to distribute binary assets or archives to users?"

4. Deep Review Aspects (Dual-Pass)

When the user triggers a deep review in Step 3, the Agent shifts focus from surface architecture to raw source code analysis.

• [DEEP-LOGIC] Line-by-line Execution: Analyze algorithm details, off-by-one errors, infinite loops, and unhandled null/undefined edge cases.
• [DEEP-SEC] Source Vulnerability: Hunt for SQL/NoSQL injections, XSS, hardcoded secrets, and missing input validation.
• [DEEP-PERF] Performance & Leaks: Identify O(N^2) bottlenecks, memory leaks, uncleaned event listeners, and hanging async/await promises.
• [DEEP-INT] Cross-file Integration: Match Data Types, JSON Payloads, and API Contracts between completely separate files (e.g., Frontend Component vs Backend Interface).
• [DEEP-CLEAN] Refactoring: Evaluate Code Smells, DRY violations, SOLID principles, and propose project-appropriate Design Patterns.

5. Process Selection Router

When: Loaded at Step 0.5 (Pre-QA Strategy) BEFORE generating questions. Agent MUST present the process selection menu and wait for user choice. This is the QA equivalent of Plan Template Selection.

5.1 Available Processes

#	Process	Slug	Philosophy	Template
1	📋 Full-Plan Review	full-plan	Waterfall Gate	references/process-full-plan.md
2	🔄 Phase-by-Phase Loop	phase-loop	Iterative Gate	references/process-phase-loop.md
3	🎯 Risk-Driven Review	risk-driven	Pareto Gate	references/process-risk-driven.md
4	⚔️ Adversarial Red Team	adversarial	Devil's Advocate	references/process-adversarial.md

5.2 Comparison Matrix

Dimension	Full-Plan	Phase-Loop	Risk-Driven	Adversarial
Token cost	🟡 Medium	🟢 Low/round	🟢 Low	🔴 High
Depth	🟡 Medium	🔴 High	🔴 Critical-only	🔴 Very High
Rounds	1-2	N (per Phase)	3 (by risk tier)	3 (attack→debate→ruling)
Best for	Small plans, specs	Large/TDD plans	Security/production	Architecture, OSS release
Output	Q&A Report	Phase Verdicts + Report	Risk Matrix + Report	Debate Log + Certification

5.3 Auto-Suggest Heuristics

Agent MUST auto-suggest a process based on artifact analysis. User may override the suggestion.

IF mode = spec OR mode = artifact
  → suggest: full-plan (no Phase structure to iterate)
ELIF artifact has ≥ 5 phases AND mode = plan
  → suggest: phase-loop
ELIF artifact has Risks table with ≥ 3 entries
  → suggest: risk-driven
ELIF user requests "stress test" OR "thorough review" OR "red team"
  → suggest: adversarial
ELIF artifact has ≤ 4 phases
  → suggest: full-plan
ELSE
  → suggest: full-plan (default)

5.4 Selection Prompt Template

Agent MUST present this prompt at Step 0.5 and STOP for user selection:

🛡️ QA PROCESS SELECTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: [artifact name]
Mode: [plan/spec/artifact/audit]
Phases: [N] | Risks: [N] | Lines: [N]

  1. 📋 Full-Plan Review     — Scan everything at once (🟡 Medium cost)
  2. 🔄 Phase-by-Phase Loop  — Review each phase independently (🟢 Low/round)
  3. 🎯 Risk-Driven Review   — Focus on highest risks first (🟢 Low cost)
  4. ⚔️ Adversarial Red Team — Multi-persona debate (🔴 High cost)

💡 Suggested: [N]. [Name] — [reason]

❓ Select a process (1-4) or press Enter for suggested:

⛔ CHECKPOINT: Agent MUST STOP the workflow here and wait for the user's explicit process selection. Do NOT proceed to generate questions until the user selects a process.

5.5 Post-Selection

After user selects a process:

1. Load the corresponding references/process-*.md template.
2. Extract the process flow and adapt the QA Strategy section accordingly.
3. Add > **Process:** [slug] to the QA Report header.
4. Proceed to the rest of Step 0.5 (Focus Areas, Red Team Roster, Process Log).

6. Spec Audit Process & Templates

The specification audit and review process (Action: spec) is designed to automate the discovery of architectural drift and ensure that safety and technical standards are established before code execution.

6.1 Spec Audit Report Template

When saving the Spec Audit report, the Agent MUST use the following structure:

# 🛡️ Spec Audit Report: [Spec Name]

> **Target:** `[Path to spec file]`
> **Sysdesign Reference:** `[Path to sysdesign file]` (if `--sys` is enabled)
> **Verdict:** `[Pass ✅ | ⚠️ Warning | 🔴 Blocked]`

## 1. Spec Quality Checklist Results (spec-quality-checklist.md)
*   **Score:** [passed]/[total] Pass
*   **Issues/Recommendations:**
    - [List failed or warning checklist items, e.g., "C4: Missing code style sample"]

## 2. Sysdesign Alignment & Spec Overlap Report
*   **API Interface Drift:** [None / Detected payload or endpoint mismatch]
*   **Database Schema Drift:** [None / Detected data type drift or foreign key conflict]
*   **Structure Drift:** [None / Incorrect proposed file location]
*   **Spec Overlap Check:** [None / Detected overlap with other specs without clear boundaries]

## 3. CSA Anchors Audit
*   **Total Anchors:** [N] anchors
*   **CSA G1 (One-to-One):** [Pass ✅ / Fail]
*   **CSA G2 (Reverse Validation):** [Pass ✅ / Fail]
*   **CSA G3 (No Blanket):** [Pass ✅ / Fail]

6.2 Agent Execution Steps

1. Ingest Spec & Sysdesign: Read the entire target specification and the corresponding system design file (if available).
2. Evaluate 30 Checklist Items: Run the 30 checks from spec-quality-checklist.md.
3. Cross-Check Database, APIs, and Spec Overlap:
   • Extract the SQL DDL and API endpoints from the Spec.
   • Compare each table, foreign key, and endpoint schema directly against the Sysdesign.
   • Detect issues such as: Foreign key conflicts, camelCase vs snake_case naming drift, wrong API routing, or missing columns.
   • Scan existing specs in artifacts/specs/ to verify boundaries between the target Spec and other specs are clear and non-conflicting.
4. Validate CSA Anchors: Scan the anchors and ensure no blanket anchors are used at the H1/H2 levels.
5. Output Report: Create the QA report and propose spec fixes directly to the user.