quality-assurance git:20260811.1169f49A

Immutable. This exact content never changes and is served at /api/v1/blob/0335ea2532069cae.

---
name: quality-assurance
description: "Reference material with consistency-analysis heuristics and checklist-management rules. Loaded on demand by `analyze-compliance` and `quality-control`; not directly invokable."
---

# Quality Assurance Guide

## Analysis Heuristics (`/sddp-analyze`)

When performing consistency analysis, verify the following relationships:

### 1. Spec vs. Plan Alignment
- **Requirement Coverage**: Does every P1/P2/P3 user story or objective in `spec.md` have a corresponding section in `plan.md`?
- **Entity Matching**: Do entities defined in `spec.md` (Data Requirements) match the `data-model.md`?
- **Complexity Check**: If the spec marked a feature as "high complexity", does the plan include specific architectural mitigations?

### 2. Plan vs. Tasks Alignment
- **Task Completeness**: Does every section of the implementation plan have at least one corresponding task in `tasks.md`?
- **Phase Ordering**: Do tasks respect the allowed phase order (optional Setup → optional Foundational → Story Phases → optional Polish)?
- **Missing Chunks**: Are there major components in the architecture diagram that are absent from the task list?

### 3. Instructions Compliance
- **Critical Violation**: Any plan decision that contradicts `project-instructions.md` is a CRITICAL error.
- **Reporting**: Flag these immediately with high severity.

## Checklist Management (`/sddp-checklist`)

Checklists are the primary gate for the implementation phase.

### Checklist Queue (`.checklists`)

The `/sddp-plan` agent generates a `.checklists` queue file in `FEATURE_DIR/checklists/` that recommends checklist domains based on risk signals detected in the technical plan. This enables automated or sequential checklist generation without manual domain input.

- **File**: `FEATURE_DIR/checklists/.checklists`
- **Format**: `- [ ] CHL### Domain Name` (e.g., `- [ ] CHL001 Security`)
- **Generation**: `/sddp-plan` creates the file after the Post-Design Gate, capped by the `MaxChecklistCount` setting in `.github/sddp-config.md` (default: 1). The plan agent may generate fewer entries if only fewer domains are relevant.
- **Consumption**: `/sddp-checklist` picks the first unchecked entry when no explicit domain is provided, and marks it `- [X]` after completion.
- **Advisory, not blocking**: The queue itself does not block implementation. Only the generated checklist *files* (`.md`) in `checklists/` are gating artifacts.
- **Override**: An explicit domain argument to `/sddp-checklist` always takes priority over the queue.

### Standard Categories
Every generated checklist should consider these categories if relevant:
1.  **Security**: Authz rules, input validation, secret handling.
2.  **Performance**: Indexing strategy, N+1 query checks, caching.
3.  **Observability**: Logging points, metric emission, error context.
4.  **Testing**: Unit test coverage, edge case handling.

### Template
Use the template at [assets/checklist-template.md](assets/checklist-template.md).

### Evaluation (`TestEvaluator`)

After a checklist is generated, the `TestEvaluator` sub-agent automatically evaluates every unchecked item against the feature artifacts. Each item receives one of three outcomes:

1. **PASS** — The question is clearly answered by existing artifacts. Item is marked `[X]` with an inline annotation citing the evidence source.
2. **RESOLVE** — The question reveals a genuine gap. The evaluator amends the relevant artifact(s) (e.g., adds missing `FR-###`, `TR-###`, `OR-###`, or `RR-###` to `spec.md`, adds task to `tasks.md`) then marks the item `[X]`.
3. **ASK** — The question is ambiguous or has multiple valid resolutions. The evaluator batches these, asks the user, then applies the chosen resolution.

Automated agents may change checkbox state from `- [ ]` to `- [X]` when supported by verified evidence or an explicit applied resolution.

It is invoked in two places:
- **`/sddp-checklist`**: Automatically after checklist generation (Step 5).
- **`/sddp-implement`**: As a third gate option ("Auto-evaluate checklists now") when checklists fail the gate.

## Definition of Done

### Implementation Ready
A feature is "Implementation Ready" only when:
1.  Scale/Complexity risks are mitigated in `plan.md`.
2.  All P1 user stories or objectives have tasks.
3.  No "NEEDS CLARIFICATION" markers remain in Spec or Plan.
4.  If checklists exist in `specs/<feature-folder>/checklists/`, all must pass (or be explicitly overridden).

### Release Ready
A feature is "Release Ready" (eligible for `.qc-passed`) only when ALL of the following are true:

> **QC strictness**: reads `## QC Strictness` from `.github/sddp-config.md`. Falls back to keyword scanning of `project-instructions.md`.

1.  **All tests pass** — unit and integration test suites report 0 failures.
2.  **Coverage meets threshold** — if `project-instructions.md` defines a coverage mandate, the measured coverage percentage meets or exceeds it. If no threshold is defined, coverage is reported but not enforced.
3.  **No CRITICAL or ERROR static analysis findings** — linting and compilation issues at error severity are resolved.
4.  **No CRITICAL security vulnerabilities** — security scan findings classified as CRITICAL are resolved.
5.  **All P1 work items PASSED** — every P1 story or objective has its acceptance, validation, or verification criteria verified in the implementation.
6.  **All Success Criteria (SC-###) PASSED** — every success criterion is achievable by the current implementation.
7.  **PI compliance: no violations** — no `project-instructions.md` principles are violated.
8.  **No unresolved CRITICAL/ERROR `[BUG]` tasks** — CRITICAL/ERROR bugs may never be excluded with `[DEFERRED]`; only deferred WARNING bugs may remain unchecked.
9.  **No unacknowledged SKIPPED checks for PI-mandated categories** — if `project-instructions.md` mandates any QC category (linting, security, coverage, accessibility, performance), that check must either pass, be explicitly acknowledged by the user as a risk-accepted waiver (WARNING), or generate FAIL with BUG tasks. Silent skips for PI-mandated categories do not satisfy Release Ready.
10. **Manual verification attested** — every required manual scenario records PASS with human identity, UTC timestamp, and evidence; pending or malformed attestation is BLOCKED.
11. **Current QC evidence** — `.qc-passed` report and evidence SHA-256 digests match the current `qc-report.md` and every manifest file.

> **Note on criteria 2–4**: These criteria apply when the respective tool ran. If a tool was SKIPPED and the category is PI-mandated, criterion 9 governs the outcome. If the category is not PI-mandated, a SKIPPED check does not block Release Ready but is reported as a WARNING recommendation.

This definition is enforced by `/sddp-qc` (Step 7) when determining the Overall Verdict.