afc-qa

name	afc:qa
description	Project quality audit — test confidence, error handling gaps, code health
argument-hint	[scope: all, tests, errors, coverage, or specific concern]
user-invocable	true
context	fork
allowed-tools	["Read","Grep","Glob","Bash"]
model	sonnet

/afc:qa — Project Quality Audit

Detects quality gaps between structural correctness and actual runtime behavior. Read-only — does not modify any files. Reports findings to console only.

Arguments

• $ARGUMENTS — (optional) scope of audit. Defaults to all.
  • all — run all 5 categories
  • tests — category A only (Test Confidence)
  • errors — category B only (Error Resilience)
  • coverage — categories A + D (Test Confidence + API & Contract Safety)
  • Or a free-form concern (e.g., "are error messages user-friendly", "check for dead exports")

Project Config (auto-loaded)

!cat .claude/afc.config.md 2>/dev/null || echo "[CONFIG NOT FOUND] Proceeding without config — read CLAUDE.md for project info."

Audit Categories

A. Test Confidence

Evaluate whether the test suite actually catches regressions.

Checks:

• Assertion density: ratio of assertions to test functions (low ratio = weak tests)
• Test-to-code ratio: test LOC vs source LOC per layer (guided by {config.architecture})
• Mock overuse: tests that mock so much they only test the mock setup
• Runtime verification: execute {config.test} and analyze output (pass/fail counts, skipped tests, timing)
• Missing coverage: source files/modules with zero test coverage

B. Error Resilience

Evaluate whether errors are handled consistently and helpfully.

Checks:

• Catch consistency: unhandled promise rejections, empty catch blocks, swallowed errors
• Error propagation: errors that lose context through the call chain
• User-facing messages: cryptic error strings, raw stack traces exposed to users
• Boundary validation: missing input validation at API/CLI/form boundaries
• Apply {config.code_style} error handling rules if available

C. Build & CI Integrity

Evaluate whether CI pipeline is healthy and reproducible.

Checks:

• CI execution: run {config.ci} and {config.gate} commands, verify they pass
• Lock file integrity: lock file present, consistent with manifest (package.json vs lock, etc.)
• Unused dependencies: declared but never imported packages
• Build reproducibility: environment-dependent paths, hardcoded secrets, missing env vars

D. API & Contract Safety

Evaluate whether interfaces between modules are sound.

Checks:

• Type mismatches: function signatures vs actual usage at call sites
• Dead exports: exported symbols never imported elsewhere
• Deprecated usage: calls to deprecated APIs (internal or external)
• Layer boundary violations: imports that cross architecture boundaries (guided by {config.architecture})

E. Code Health Signals

Evaluate general code quality indicators.

Checks:

• Complexity hotspots: deeply nested logic, functions with high cognitive complexity (many branches, side effects, or state mutations). Line count alone is not a reliable indicator — a 30-line function with nested conditionals and side effects may be more complex than a 60-line function with simple sequential logic.
• Duplication: near-identical code blocks across files
• Magic numbers/strings: unexplained literals in logic
• TODO/FIXME accumulation: stale markers (count, age if git history available)
• Compare against {config.code_style} rules if available

Execution Steps

1. Parse Scope

Interpret $ARGUMENTS to determine which categories to run:

Argument	Categories
all or empty	A, B, C, D, E
tests	A
errors	B
coverage	A, D
free-form text	best-matching subset

3. Lightweight Runtime

Run commands that produce real output:

• {config.test} — capture pass/fail/skip counts and timing
• {config.gate} or {config.ci} — capture exit code and output

Only run commands that exist in config. Skip gracefully if not configured.

4. Codebase Scan

For each active category:

1. Use Glob to discover relevant files
2. Use Grep for pattern-based detection (empty catches, TODO markers, etc.)
3. Use Read for targeted inspection of flagged files
4. Cross-reference findings against {config.architecture} layer structure

5. Critic Loop

Always read ${CLAUDE_SKILL_DIR}/../../docs/critic-loop-rules.md first and follow it. Safety cap: 5 passes.

Focus the critic on:

• Are the findings actionable or just noise?
• Did I miss obvious quality gaps?
• Are severity ratings justified by evidence?

6. Console Report

Output the final report in this format:

## QA Audit: {project name or directory}

### Category A: Test Confidence
{findings with file:line references}
Verdict: PASS | WARN | FAIL

### Category B: Error Resilience
{findings with file:line references}
Verdict: PASS | WARN | FAIL

### Category C: Build & CI Integrity
{findings with file:line references}
Verdict: PASS | WARN | FAIL

### Category D: API & Contract Safety
{findings with file:line references}
Verdict: PASS | WARN | FAIL

### Category E: Code Health Signals
{findings with file:line references}
Verdict: PASS | WARN | FAIL

### Summary
├─ A: Test Confidence    — {PASS|WARN|FAIL} {(N issues) if any}
├─ B: Error Resilience   — {PASS|WARN|FAIL} {(N issues) if any}
├─ C: Build & CI         — {PASS|WARN|FAIL} {(N issues) if any}
├─ D: API & Contract     — {PASS|WARN|FAIL} {(N issues) if any}
└─ E: Code Health        — {PASS|WARN|FAIL} {(N issues) if any}

Total: {N} PASS, {N} WARN, {N} FAIL
Priority fixes: {top 3 most impactful issues}

Verdict Criteria

• PASS — no issues found, or only cosmetic observations
• WARN — issues found but not blocking; quality could degrade over time
• FAIL — critical gaps that likely cause bugs, outages, or security issues

Notes

• Read-only: Do not modify any files. Report only.
• Evidence-based: Every finding must include a file:line reference or command output.
• Config-aware: Adapt checks to the project's declared architecture and conventions.
• Scope discipline: Only run categories matching the requested scope.
• Not a linter: Focus on semantic quality gaps that automated tools miss.