Quality Audit

/quality-audit — Đánh giá chất lượng toàn diện

Usage: /quality-audit [<module>|all]

Default: all (đánh giá toàn bộ project)

Top-of-funnel audit /110. Cho cái nhìn tổng quan; để đánh giá sâu từng domain, dùng các specialized audit ở §"Specialized Audits".

Instructions

Khi user invoke /quality-audit:

Bước 1: Thu thập dữ liệu tự động

Chạy các lệnh sau song song để thu thập metrics. Thay placeholder bằng script/đường dẫn của project:

# 1. Git & PR stats
git log --oneline --since="30 days ago" | wc -l
gh pr list --state merged --limit 200 --json number --jq 'length'
gh pr list --state open --json number --jq 'length'
git branch -r | grep -v "main\|HEAD" | wc -l

# 2. CI status — dùng project's CI helper script nếu có
#    Audit mode: đọc kết quả, KHÔNG đợi (--status / read-only)
scripts/check-ci.sh --status   # hoặc: gh run list --branch main --limit 10 --json conclusion

# 3. Backend + Frontend tests — dùng project test runner script
scripts/test-local.sh <module> all   # KHÔNG chạy mvnw/vitest/eslint ad-hoc

# 4. E2E tests — script có sẵn của project
scripts/test-e2e.sh

# 5. Docker / runtime status
scripts/status.sh   # hoặc: docker compose ps

# 6. Code stats (grep/find OK vì chỉ đếm, không execute)
find . -name "*.java" -path "*/src/main/*" | wc -l
find . -name "*Test.java" | wc -l
find . -name "*.tsx" -o -name "*.ts" | grep -v node_modules | wc -l

# 7. Security scan (grep OK — chỉ scan)
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.java" src 2>/dev/null | wc -l

# 8. Documentation
find documents -name "*.md" | wc -l

# 9. Monitoring / health
scripts/monitor.sh health   # hoặc health endpoint check

CRITICAL: KHÔNG chạy lệnh ad-hoc cho:

• Tests → project test runner script
• CI monitoring → project CI helper script
• Docker / runtime → project status script
• Monitoring → project monitor script

(Lý do: scripts encapsulate đúng flags/profiles; ad-hoc dễ sai môi trường.)

Bước 2: Chấm điểm 11 categories (110 điểm)

Per-check scoring: Mọi category dưới đây dùng per-check pass/fail rubric per rules/audit-skill-rubric-quality-audit.md §2 (5+ sub-checks per category, severity P0/P1/P2). Bất kỳ P0 sub-check FAIL → cap category total ≤ (max - 4) AND audit-level verdict = FAIL bất kể tổng điểm. Bug list (mọi FAIL) đứng TRƯỚC bảng điểm. Xem bound rule để có primacy + enumeration cụ thể.

Scale: Cat 11 (Persona Coverage) là category /10 thứ 11, nâng max từ 100 → 110. 10 tech categories giữ nguyên trọng số; Cat 11 thêm business-correctness signal mà tech-only audit bỏ sót. Shorthand điểm dùng dạng X/110.

1. E2E Functionality (10 điểm)

2. Security (10 điểm)

3. Backend Tests (10 điểm)

4. Frontend Tests (10 điểm)

5. CI/CD (10 điểm)

6. UI/UX (10 điểm)

7. DevOps/Infrastructure (10 điểm)

8. Documentation (10 điểm)

Business docs ở documents/ là SOURCE OF TRUTH. Score 0 cho category này nếu không có business docs cho các domain đã implement.

9. Code Quality (10 điểm)

Design patterns check (generic):

• No God Service trong các service chính
• Status transitions via State Pattern (not nested switch)
• External APIs wrapped by Adapter
• Events via Outbox (check outbox table + publisher)
• External calls có Circuit Breaker + fallback
• No primitive obsession (value objects cho structured types)

Document Generation Quality check (khi document-rendering code thay đổi):

• Non-ASCII / Unicode text round-trip qua MỌI export format (PDF/DOCX/XLSX) — verified bởi diacritics/Unicode round-trip tests
• Locale-specific number/currency formatting đúng locale config
• Branding-aware outputs (header/logo/displayName) derive từ branding config, fall back gracefully khi keys absent
• WCAG contrast khi branding color paints fill (foreground tự switch readable)
• Filename trong Content-Disposition dùng RFC-5987 UTF-8 encoding
• Cross-format consistency có integration test; thêm format mới → extend test trước khi merge

10. Project Management (10 điểm)

11. Persona Coverage (10 điểm)

Source of truth: latest reports dưới documents/persona-reviews/ produced via persona review process (quarterly cadence). Nếu chưa có report cho ≥1 persona Tier 1 → score 5/10 (mid-baseline) annotate "data pending".

Data-pending policy: không có report cho ≥1 Tier 1 persona → score Cat 11 = 5/10. KHÔNG score 0 (no data ≠ no coverage); KHÔNG score 10 (không claim full coverage nếu thiếu evidence). Baseline 5/10 giữ tới khi reports ship.

Scoring guidance:

• 9-10/10: Tất cả Tier 1 reports current, zero critical gap, cadence on track
• 7-8/10: Reports exist nhưng ≥1 có open critical gap, HOẶC cadence slipping ≤1 quarter
• 5/10: Data pending — default neutral score
• 3-4/10: Reports cho một số personas, HOẶC cadence overdue ≥2 quarters
• 1-2/10: Reports exist nhưng nhiều critical gaps, no remediation
• 0/10: Feature completeness <30% cho ≥1 Tier 1 persona (system unusable at scale)

Bước 3: Output Report

# Quality Audit Report: [<module>/All]

**Ngày:** [date]
**Người đánh giá:** Claude Code
**Version:** [latest commit hash]

---

## Bug List (mọi FAIL — đứng TRƯỚC bảng điểm)

| Severity | Category | Sub-check | Evidence (file:line) |
|----------|----------|-----------|----------------------|
| 🔴 P0 | ... | ... | ... |

**Audit-level verdict:** PASS / FAIL (FAIL nếu có ANY P0 sub-check FAIL)

---

## Overall Score

| # | Category | Score | Max | Grade |
|---|----------|-------|-----|-------|
| 1 | E2E Functionality | X | 10 | ✅/⚠️/❌ |
| 2 | Security | X | 10 | ✅/⚠️/❌ |
| 3 | Backend Tests | X | 10 | ✅/⚠️/❌ |
| 4 | Frontend Tests | X | 10 | ✅/⚠️/❌ |
| 5 | CI/CD | X | 10 | ✅/⚠️/❌ |
| 6 | UI/UX | X | 10 | ✅/⚠️/❌ |
| 7 | DevOps/Infra | X | 10 | ✅/⚠️/❌ |
| 8 | Documentation | X | 10 | ✅/⚠️/❌ |
| 9 | Code Quality | X | 10 | ✅/⚠️/❌ |
| 10 | Project Management | X | 10 | ✅/⚠️/❌ |
| 11 | Persona Coverage | X | 10 | ✅/⚠️/❌ |
| **Total** | | **X** | **110** | **Grade** |

### Grade Scale (/110)

- 105-110: A+ (Production Excellence)
- 99-104: A (Production Ready)
- 94-98: B+ (Near Production)
- 88-93: B (Good, needs polish)
- 77-87: C (Acceptable, significant gaps)
- <77: D (Major work needed)

(Thresholds = prior /100 thresholds × 1.1, rounded.)

---

## Detailed Findings

### ✅ Strengths (8+/10)
### ⚠️ Needs Improvement (5-7/10)
### ❌ Critical Issues (<5/10)

---

## Improvement Roadmap

### Quick Wins (1-2 hours each)
### Medium Effort (0.5-1 day)
### Major Effort (2+ days)

---

## Comparison with Previous Audit

| Category | Previous | Current | Change |
|----------|----------|---------|--------|
| ... | ... | ... | +X/-X |

(Nếu không có audit trước, ghi "First audit")

---

## Action Items

| Priority | Item | Estimated Score | Effort |
|----------|------|-----------------|--------|
| 🔴 P0 | ... | +X | ... |

Bước 4: Lưu kết quả

• Save report to documents/audits/quality/quality-audit-[date].md
• Update quality plan nếu phát hiện gaps mới
• So sánh với audit trước nếu có

Context Management (CRITICAL)

Quality-audit là skill tốn context nhất (60-100K+ tokens). Compaction giữa audit = scores sai. Tuân thủ:

Staged Execution — 3 Phases

Phase 1: Automated metrics (run in parent, ~15K tokens)

• Git stats, CI status, runtime status, code counts
• Test execution (via scripts — output có thể lớn, LUÔN | tail -30)
• KHÔNG đọc source files trong phase này

Phase 2: Parallel deep-dive (delegate to subagents, ~20K each)

• Agent 1: Categories 1-3 (E2E, Security, Backend Tests)
• Agent 2: Categories 4-6 (Frontend Tests, CI/CD, UI/UX)
• Agent 3: Categories 7-10 (DevOps, Docs, Code Quality, PM)
• Mỗi agent trả JSON summary: {category, score, evidence: [1-line each], issues: []}

Phase 3: Aggregate (parent, ~5K tokens)

• Collect subagent results → compile report → compare with previous audit

Output Limiting Rules

Subagent Return Format

{
  "categories": [
    {"id": 1, "name": "E2E Functionality", "score": 8, "max": 10, "evidence": ["E2E pass 12/12", "cold start OK"], "issues": []}
  ]
}

Parent KHÔNG cần re-verify — trust subagent evidence. Chỉ sanity-check nếu score bất thường (0 hoặc 10).

Rules

• LUÔN chạy tests thật (không đoán)
• LUÔN giao tiếp tiếng Việt
• Chấm điểm dựa trên evidence (test output, code check), không cảm tính
• Nếu E2E fail lần 1 do cold start, chạy lần 2 nhưng GHI NHẬN cold start issue (-2 điểm)
• Nếu không thể chạy test (runtime down, etc.), ghi 0 điểm cho category đó + note lý do
• KHÔNG chạy tất cả trong 1 context — PHẢI dùng staged execution + subagents

CRITICAL: CI phải hoàn thành trước khi chấm điểm

KHÔNG BAO GIỜ kết luận CI/CD score hoặc Backend Tests score khi CI còn in_progress.

Quy trình bắt buộc:

1. Thu thập data → kiểm tra gh run list status
2. Nếu có run in_progress liên quan target (branch/PR):
   • Dùng project CI helper script (read mode) để kiểm tra — KHÔNG đoán
   • Nếu còn in_progress → đợi hoặc đánh dấu PENDING
   • PHẢI báo user: "CI đang chạy, đợi kết quả trước khi chấm điểm CI/CD"
3. Chỉ sau khi CI completed → chấm điểm: CI/CD, Backend Tests, E2E
4. Nếu user yêu cầu audit gấp → ghi "CI/CD: PENDING (chưa có kết quả)" thay vì đoán

Lý do: Đoán CI pass khi thực tế đang chạy làm sai lệch kết quả + có thể dẫn đến merge PR lỗi.

Specialized Audits (for deeper analysis)

Quality-audit cho cái nhìn tổng quan /110. Để đánh giá sâu từng domain:

Thêm section "Specialized Audit Scores" vào report nếu có kết quả từ audit chuyên sâu.

Gotchas

• Self-audit overstates 15-20 pts vs specialist — không trust standalone score; luôn compute delta vs prior baseline, không phải absolute number
• Audit grep scope phải include sub-modules — multi-module projects đặt classes/config trong submodule dirs; narrow scope tạo false-positive issue counts (xem quality/business-logic-audit "Grep Scope")
• Targeted re-audit only after fix — full re-audit chỉ khi release / major refactor; re-score chỉ categories bị ảnh hưởng bởi fix
• First-run baseline is NOT a regression — scoring category chưa từng audit, low score là honest baseline, không phải drift
• Always use CI helper script (read mode) cho audit data; gh pr checks field state đôi khi null và break polling
• Cat 11 defaults to 5/10 cho tới khi persona reports ship — không score 0 hay 10
• Comparing legacy /100 vs /110 audits — convert old X/100 to (X × 1.1)/110 trước khi delta

Skill Contents

• rules/audit-skill-rubric-quality-audit.md — per-check pass/fail rubric (11 categories) bound to this skill

Log

• Ported into starter-kit from an internal project's audit-suite pack. Genericized: removed project-specific module/script names, scores, audit dates, and incident history. Methodology (11 categories /110, staged execution, per-check rubric binding, CI-completion gate) preserved intact.