Skip to main content

/qa-doc-review

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

name: qa-doc-review version: "2.0" level: 3 trigger: "QA Documentationreview, doc review, documentation review, qa-doc, review documentation, check docs" author: john updated: 2026-03-16

QA-Doc Review Squad— Level 3 Supervised Skill

SpawnSistematski 5pregled expertdokumentacije agentsi inQA parallelartefakata. toProvjerava reviewcompleteness, systemaccuracy, documentationi for a project. Each agent reviews their domain and returns findings with severity ratings.linkove.

WhenWHEN toTO UseUSE

  • BeforeIF development"doc startsreview", on"review docs", "check documentation", "QA doc" → activate
  • IF completing a new projecttask with existingdocs documentation
    • deliverable
  • After→ majorrun documentationas revision
    • post-step
  • When validating architecture decisions before buildvalidation

ArgumentsWORKFLOW

    Step
  • 1: Classify Document Type

    • <project-path>IF —task Pathdocumentation → validate against GOTCHA acceptance criteria
IF API documentation → check endpoint coverage, examples, error codes
IF runbook/ops doc → check command accuracy (run commands to projectverify)
rootIF architecture doc → check against actual system (mustquery haveHiveMind)
docs/IF directory)changelog
→

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: Frameworkcheck version issues,format, 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" | sortcompleteness

    Step
  1. 2:

    MapAccuracy Check

    2. # For runbooks: verify commands actually work
# Run key commands and compare output to what doc claims
IF command in doc:
  run command → compare output → flag discrepancies

    Step 3: Quality Checklist

    [ ] Title and metadata present (date, author, version)
[ ] All claimed commands/URLs are verified working
[ ] No localhost:XXXX references in production docs
to[ experts] basedNo on"TODO" directoryor names"FIXME" placeholders left
[ ] Links resolve (architecture/,internal database/, api/, security/, integration/, devops/, frontend/, mobile/)
    


  2. 

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

      

    • CORE PROTOCOLwiki + external)
[ ] Screenshots/diagrams are current (not stale)
[ ] GOTCHA BOOTacceptance headers
      • criteria 
    • Expertmet role(if andtask specialty
      • 

    • Assigned document paths
      • 

    • Specific checklist from expert section above
      • 

    • Output format: ###doc)
[SEVERITY] —] TitleHiveMind withpost Document, Issue, Impact, Fix
      • 

    

    3. 

  3. 

    Wait for all 5 to complete
    

    4. 

  4. 

    Compile consolidated report:
    

      

    • Summary tableconfirmed (Expertif xknowledge Severity)
      • doc)

    • Top
    5. 5

    Step cross-cutting4: issuesBookStack (foundSync by 2+ experts independently)
  5. Full findings per expert
  6. Prioritized fix recommendations

Output Format per Finding

Check 
#### IF doc should be in BookStack:
cat ~/system/config/bookstack-sync-map.json | grep "[CRITICAL|HIGH|MEDIUM|LOW]filename]"
—# ShortVerify Titlesync **Document:** filename.md, section
**Issue:** What's wrong
**Impact:** Real-world consequence
**Fix:** How to fix itstatus

PromptOUTPUT TemplateFORMAT for(report Eachto AgentJohn, not user)

##QA-DOC COREREVIEW PROTOCOLREPORT

NIKADStatus: NEAPPROVED PITAJ| korisnikaNEEDS_WORK tehnicka| pitanja.BLOCKED
TiDocument: si[title/path]
ekspert,Type: ne[task-doc on.| runbook | api-doc | architecture | changelog]

❌ BLOCKERS:
  - Ako[issue]

zapneš⚠️  → istraži sam (čitaj fajlove, dokumentaciju)WARNINGS:
  - Ako[issue]

ne✅ možešCONFIRMED riješiti → vrati parcijalni rezultat sa objašnjenjemWORKING:
  - NIKAD[verified neitems]

pitajBookStack: "kakoSYNCED da| implementiramNOT_SYNCED X"| ##N/A
GOTCHAHiveMind: BOOTPOSTED PRVI| KORAKNOT_POSTED —| prijeN/A

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:**Verdict: [Expertone 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.sentence]

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