Skip to main content

/qa-doc-review

Source: ~/.claude/skills/qa-doc-review/SKILL.md

QA Documentation Review Squad

Spawn 5 expert agents in parallel to review system documentation for a project. Each agent reviews their domain and returns findings with severity ratings.

When to Use

  • Before development starts on a new project with existing documentation
  • After major documentation revision
  • When validating architecture decisions before build

Arguments

  • <project-path> — Path to project root (must have docs/ directory)

The Squad

1. Backend Architect

Reviews: system-overview, high-level-design, low-level-design, api-specification Looks for: Architecture failures, CQRS/event sourcing anti-patterns, API design issues, booking/flow race conditions, module circular dependencies, framework-specific anti-patterns, contradictions between docs, missing pieces, unrealistic assumptions.

2. Database Engineer

Reviews: database-design, low-level-design (data sections) Looks for: Schema issues, missing indexes, event sourcing degradation, concurrent reservation handling, FK cascade issues, price precision, timezone handling, UUID trade-offs, migration gaps, slow queries, missing partitioning.

3. DevOps/SRE Engineer

Reviews: deployment-architecture, ci-cd-pipeline, observability Looks for: Undersized infrastructure, SPOF, container orchestration in prod, backup gaps, CI/CD missing steps, unrealistic costs, SSL not automated, no LB, no log rotation, no secrets mgmt, bad monitoring, unrealistic RTO/RPO, missing network security.

4. Security Engineer

Reviews: security-architecture, integration-architecture, api-specification, low-level-design Looks for: JWT flaws, missing RBAC, PCI DSS gaps, auth rate limiting, API key mgmt, data exposure, injection, CORS/CSP, session gaps, encryption key mgmt, webhook validation, audit gaps, GDPR gaps.

5. Frontend/Mobile Engineer

Reviews: frontend-specification, mobile-specification, system-overview Looks for: Framework version issues, offline sync conflicts, QR forgery, PWA gaps, WCAG claims, unrealistic perf targets, state mgmt re-renders, localization gaps, missing error states, version conflicts, push notification gaps, deep linking issues.

How to Run

  1. Discover docs structure:
find <project-path>/docs -name "*.md" | sort

  1. Map docs to experts based on directory names (architecture/, database/, api/, security/, integration/, devops/, frontend/, mobile/)

  2. Spawn 5 parallel Explore agents (model: sonnet) with:

    • CORE PROTOCOL + GOTCHA BOOT headers
    • Expert role and specialty
    • Assigned document paths
    • Specific checklist from expert section above
    • Output format: ### [SEVERITY] — Title with Document, Issue, Impact, Fix

  3. Wait for all 5 to complete

  4. Compile consolidated report:

    • Summary table (Expert x Severity)
    • Top 5 cross-cutting issues (found by 2+ experts independently)
    • Full findings per expert
    • Prioritized fix recommendations

Output Format per Finding

### [CRITICAL|HIGH|MEDIUM|LOW] — Short Title
**Document:** filename.md, section
**Issue:** What's wrong
**Impact:** Real-world consequence
**Fix:** How to fix it

Prompt Template for Each Agent

## CORE PROTOCOL
NIKAD NE PITAJ korisnika tehnicka pitanja. Ti si ekspert, ne on.
- Ako zapneš → istraži sam (čitaj fajlove, dokumentaciju)
- Ako ne možeš riješiti → vrati parcijalni rezultat sa objašnjenjem
- NIKAD ne pitaj "kako da implementiram X"

## GOTCHA BOOT
PRVI KORAK — prije BILO ČEGA, pročitaj:
1. ~/system/rules/tool-first-protocol.md
2. ~/system/rules/agent-anti-hallucination.md
3. ~/system/tools/manifest.md
Tek NAKON čitanja nastavi sa taskovima.

---

**Role:** [Expert Title] ([Years] years, [Specialties])

**Mission:** Review [Project Name] documentation. Find things that WON'T WORK.

**Read ALL these files thoroughly:**
[List of document paths]

**Look for:** [Expert-specific checklist from above]

**Output per finding:**
### [CRITICAL|HIGH|MEDIUM|LOW] — Title
**Document:** file, section
**Issue:** What's wrong
**Impact:** Why it matters
**Fix:** How to fix

If no significant issues found, say so honestly.

Notes

  • Agents are READ-ONLY (Explore type) — they review but don't modify
  • Use model: sonnet (never opus for agents)
  • Expect ~72-100 findings for a typical 10-12 doc project
  • Cross-cutting issues (found by 2+ experts) are the most reliable findings
  • Some findings may overlap between experts — deduplicate in consolidated report
Back to top