| name | quality-audit |
| description | Dùng khi user nói 'audit', 'quality check', 'kiểm tra chất lượng', 'điểm chất lượng', 'ready to merge?', 'persona coverage', hoặc trước khi merge một wave/feature lớn vào main. Chấm điểm 11 categories /110 điểm (10 tech + 1 persona coverage). |
| user-invocable | true |
/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:
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
scripts/check-ci.sh --status
scripts/test-local.sh <module> all
scripts/test-e2e.sh
scripts/status.sh
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
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.java" src 2>/dev/null | wc -l
find documents -name "*.md" | wc -l
scripts/monitor.sh health
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)
| Tiêu chí | Điểm | Check |
|---|
| E2E API tests pass 100% | 4 | E2E test results |
| E2E pass ngay lần đầu (no cold start issue) | 2 | Chạy 1 lần duy nhất |
| Critical flows hoạt động: Register→Login→Dashboard→core action | 2 | Manual hoặc E2E |
| External integrations hoạt động (không chỉ mock) | 2 | Check provider config |
2. Security (10 điểm)
| Tiêu chí | Điểm | Check |
|---|
| Authentication: token + email verify + captcha/rate-limit | 3 | Code review |
| Rate limiting hoạt động | 2 | Gateway/edge config |
| Không có secrets hardcode trong code | 2 | grep -r sensitive patterns |
| CORS configured đúng (không wildcard prod) | 1 | Gateway CORS config |
| Input validation trên tất cả endpoints | 2 | DTO annotations |
3. Backend Tests (10 điểm)
| Tiêu chí | Điểm | Check |
|---|
| Tất cả modules build + test pass (0 errors) | 4 | Test runner |
| 0 skipped tests | 2 | Check skipped count |
| Test coverage >70% | 2 | Coverage report nếu có |
| Integration tests cho critical paths | 2 | Check *IT.java files |
4. Frontend Tests (10 điểm)
| Tiêu chí | Điểm | Check |
|---|
| Unit/component tests pass, <10% skipped | 3 | Test runner results |
| Production build pass (all pages) | 2 | build command |
| Component tests cho critical pages | 3 | Count test files |
| E2E browser tests (Playwright/Cypress) | 2 | Check e2e/ folder |
5. CI/CD (10 điểm)
| Tiêu chí | Điểm | Check |
|---|
| Tất cả CI workflows green trên main | 4 | gh run list |
| 0 stale branches | 2 | git branch -r count |
| 0 open PRs không hoạt động | 2 | gh pr list --state open |
| CI history sạch (không spam failed runs) | 2 | gh run list count |
6. UI/UX (10 điểm)
| Tiêu chí | Điểm | Check |
|---|
| Tất cả pages có consistent design system | 3 | Check design tokens, shared components |
| Theme system hoạt động (đổi màu visual) | 2 | Test theme override |
| Responsive (mobile-friendly) | 2 | Check breakpoints |
| Onboarding/guidance cho new users | 2 | Wizard, checklist, tooltips |
| Accessibility (a11y basics) | 1 | aria-labels, semantic HTML |
7. DevOps/Infrastructure (10 điểm)
| Tiêu chí | Điểm | Check |
|---|
| Tất cả containers healthy | 3 | docker compose ps |
| Production deployment plan có (IaC) | 2 | Check infra/ folder |
| Backup strategy documented | 2 | Check docs |
| Monitoring/alerting | 2 | Check dashboard/alerts |
| Secrets management documented | 1 | Secrets runbook |
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.
| Tiêu chí | Điểm | Check |
|---|
| Business docs exist for all implemented domains | 3 | Mỗi service có business logic phải có rules/use-cases/api-contract doc |
| Business docs match code — config keys, rules | 2 | Cross-check config keys trong code vs business doc |
| Architecture + guides + README up-to-date | 3 | Check planning docs, README, project instructions |
| Plans up to date with completion tracking | 2 | Check ✅/⬜ trong plans |
9. Code Quality (10 điểm)
| Tiêu chí | Điểm | Check |
|---|
| 0 TODO/FIXME/HACK trong production code | 1 | grep -r |
| 0 IDE warnings (TypeScript + Java) | 1 | Compiler/linter |
| Consistent coding style (ESLint, Checkstyle) | 1 | Pre-commit hooks |
| No dead code / unused imports | 1 | Linter results |
| Framework dependencies trên latest patch | 1 | Check manifest |
| Design patterns applied correctly (no anti-patterns) | 3 | rules/design-patterns.md + quality/design-pattern-audit |
| Pattern choice documented (javadoc/comment) | 1 | Spot check key services |
| No God Services (>500 lines / >15 methods) | 1 | find -size +20k *Service.java |
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)
| Tiêu chí | Điểm | Check |
|---|
| Tất cả plans có completion status | 3 | Review plan docs |
| PRs follow team methodology (brainstorm/breakdown/TDD/review) | 3 | Check recent PR descriptions |
| Commit messages clean + meaningful | 2 | git log review |
| Issues/gaps tracked và prioritized | 2 | Check gap reports |
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.
| Tiêu chí | Điểm | Check |
|---|
| Tất cả Tier 1 personas có review report ≤90 ngày | 3 | ls -lt documents/persona-reviews/*.md + match từng persona |
| Mỗi report có zero 🔴 critical (blocking-launch) gap | 3 | Read verdict + critical-gap section |
| Quarterly cadence respected (latest review ≤ current quarter) | 2 | So sánh report date vs EOQ |
Persona catalog có next_review field không overdue | 1 | grep next_review: frontmatter |
| Audit-driven persona gaps tracked (không stale) | 1 | grep persona-* gaps trong roadmap/gap tracker |
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
| Command | Limit |
|---|
| backend test runner | | tail -30 (chỉ summary) |
| frontend test runner | | tail -20 |
| build | | tail -25 (route table only) |
gh run list | --limit 10 |
git log | --oneline -20 |
grep -r | | head -20 per pattern |
find ... | wc -l | OK (single number) |
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:
- Thu thập data → kiểm tra
gh run list status
- 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"
- Chỉ sau khi CI completed → chấm điểm: CI/CD, Backend Tests, E2E
- 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:
| Audit | Skill | Khi nào |
|---|
| Business Logic | /business-logic-audit | Code ↔ rules.md sync |
| Security | /security-audit | Deep security assessment |
| Performance | /performance-audit | Bottleneck + baseline |
| API Contract | /api-contract-audit | Endpoint ↔ docs sync |
| Ops Readiness | /ops-readiness-audit | Production deploy readiness |
| Design Patterns | /design-pattern-audit | Anti-pattern detection /100 |
| UI/UX | /ui-review | Per-screen visual /128 |
| Persona Coverage | persona review process | Quarterly role-play per Tier 1 persona — feeds Cat 11 |
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.
