---
paths: "devforgeai/qa/**, **/gaps.json, **/qa-report.md"
---

# QA Output Fidelity Rules

**Purpose:** Ensure QA output files (gaps.json, qa-report.md) contain full-fidelity, zero-ambiguity data that enables automated remediation without human interpretation.

**Reference:** CLAUDE.md Critical Rule 16

---

## Principle

QA output files are the **contract between QA and Dev workflows**. When `/dev STORY-NNN --fix` reads gaps.json, it must find:
- Exactly WHAT is wrong (file, line, description)
- Exactly HOW to fix it (remediation with code-level guidance)
- Exactly WHY it matters (severity, provenance, blocking status)

A summary-only gaps file forces the dev workflow to re-investigate issues that QA already diagnosed. This wastes cycles and risks the dev workflow misinterpreting the problem.

---

## gaps.json Minimum Field Contract

Every entry in `coverage_gaps`, `anti_pattern_violations`, `deferral_issues`, and `regression_findings` arrays MUST contain these fields:

### Coverage Gap Entry (Required Fields)

```json
{
  "file": "src/module/handler.py",
  "layer": "business|application|infrastructure",
  "coverage_pct": 72,
  "threshold_pct": 95,
  "uncovered_lines": [45, 46, 47, 89, 90, 91, 92],
  "uncovered_functions": [
    {"name": "validate_input", "lines": "45-47"},
    {"name": "handle_error", "lines": "89-92"}
  ],
  "severity": "CRITICAL",
  "remediation": "Add unit tests for validate_input (null input, empty string, overlength) and handle_error (timeout, connection refused, malformed response)"
}
```

### Anti-Pattern Violation Entry (Required Fields)

```json
{
  "file": "src/module/service.py",
  "line": 142,
  "category": "God Object|SQL Concatenation|Hardcoded Secret|Tool Usage|Direct Instantiation|Missing Validation",
  "severity": "CRITICAL|HIGH|MEDIUM|LOW",
  "provenance": "GROUNDED",
  "description": "ServiceManager class has 23 methods across 3 unrelated domains (order processing, payment, notification)",
  "evidence": "Source: anti-patterns.md, lines 15-20 (God Object: >500 lines or >10 methods across domains)",
  "remediation": "Split into OrderService, PaymentService, NotificationService. Extract shared state to OrderContext DTO.",
  "classification": "REGRESSION|PRE_EXISTING"
}
```

### Remediation Sequence Entry (Required Fields)

```json
{
  "step": 1,
  "action": "Add missing test for validate_input null case",
  "file": "tests/test_handler.py",
  "lines": "new function after line 67",
  "severity": "CRITICAL",
  "estimated_time": "5 minutes",
  "blocks": ["step 2 depends on this test existing"]
}
```

---

## qa-report.md Mandatory Population Rules

When populating the qa-report-template.md, the following fields are **REQUIRED** (not optional, not "N/A") for each severity level:

### CRITICAL Violations (ALL fields required)

- `{{FILE}}:{{LINE}}` — exact file path and line number
- `{{CODE_SNIPPET}}` — the actual violating code (not a description of it)
- `{{FIX_CODE}}` — the corrected code
- `{{SECURITY_IMPACT}}` — specific impact statement
- `{{REFERENCE}}` — context file citation (anti-patterns.md, coding-standards.md)

### HIGH Violations (ALL fields required)

- `{{FILE}}:{{LINE}}` — exact file path and line number
- `{{ISSUE}}` — specific description (not "code quality issue")
- `{{EXPECTED}}` vs `{{ACTUAL}}` — concrete comparison
- `{{FIX_DESCRIPTION}}` — actionable fix instruction

### MEDIUM/LOW Violations (file + description required)

- `{{FILE}}` — file path required
- `{{ISSUE}}` — specific description required

### Coverage Gaps (ALL fields required)

- `{{FILE}}` — exact file path
- `{{COVERAGE_PCT}}` — actual percentage (not "below threshold")
- `{{UNCOVERED_LINES}}` — specific line numbers or ranges
- `{{UNCOVERED_METHODS}}` — method names with line ranges
- `{{SUGGESTED_TESTS}}` — at least 1 concrete test suggestion per gap

---

## Enforcement

The `pre-qa-output-fidelity.sh` PreToolUse[Write] hook runs `validate-qa-output`
against every gaps.json written to `devforgeai/qa/reports/` and blocks the Write
(`exit 2`) when an entry fails the field contract above. A sparse file cannot be
written — partial data is worse than no data.

When validation fails because Phases 02-04 did not collect the data, route the
fix: re-run coverage analysis with `--verbose` for coverage-gap fields, or
re-invoke the anti-pattern-scanner subagent for anti-pattern fields — then
rebuild gaps.json.

---

## Prohibited Patterns

These output patterns are **FORBIDDEN** in gaps.json and qa-report.md:

| Forbidden Pattern | Required Instead |
|-------------------|-----------------|
| `"file": "various files"` | Specific file path per entry |
| `"line": null` | Specific line number (or line range) |
| `"remediation": "Fix the issue"` | Specific fix instruction with code guidance |
| `"severity": "issue"` | CRITICAL, HIGH, MEDIUM, or LOW |
| `"description": "Coverage below threshold"` | Exact percentage, threshold, and uncovered lines |
| `"uncovered_lines": []` (empty when coverage < threshold) | At least the top uncovered lines |
| Entire sections omitted | All template sections populated (empty sections get "None found") |

---

## Provenance Requirement

Every violation entry in gaps.json MUST include provenance:

- **GROUNDED**: Violation backed by specific file content, test output, or context file quote
- **DERIVED**: Violation inferred from heuristics (must include 1-sentence justification)
- **INCONCLUSIVE**: Evidence insufficient — flag rather than fabricate

This aligns with the Epistemic Integrity Protocol (`.claude/rules/core/epistemic-integrity.md`).

---

## References

- **Template**: `src/claude/skills/spec-driven-qa/assets/templates/qa-report-template.md`
- **Phase 05**: `src/claude/skills/spec-driven-qa/phases/phase-05-reporting.md`
- **ADR-010**: Coverage thresholds are CRITICAL blockers
- **RCA-002**: gaps.json generation is mandatory for FAILED QA
- **Epistemic Integrity**: `.claude/rules/core/epistemic-integrity.md`
