| 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 wave 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 [kitehub|kiteclass|all]
Default: all (đánh giá cả KiteHub + KiteClass)
Last Updated: 2026-04-29 (v1.1 — added Cat 11 Persona Coverage; total scale 100 → 110)
Instructions
Khi user invoke /quality-audit:
Bước 1: Thu thập dữ liệu tự động
Chạy tất cả lệnh sau song song để thu thập metrics:
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 kiteclass all
kiteclass/scripts/test-api-e2e.sh
kiteclass/scripts/dev-status.sh
find kiteclass -name "*.java" -path "*/src/main/*" | wc -l
find kiteclass -name "*Test.java" | wc -l
find kiteclass/kiteclass-frontend/src -name "*.tsx" -o -name "*.ts" | wc -l
grep -r "TODO\|FIXME\|HACK\|XXX" kiteclass/*/src/main --include="*.java" | wc -l
find documents -name "*.md" | wc -l
kiteclass/scripts/monitor.sh health
CRITICAL: KHÔNG chạy lệnh ad-hoc cho:
- Tests →
scripts/test-local.sh
- CI monitoring →
scripts/check-ci.sh
- Docker →
*/scripts/dev-*.sh hoặc kitehub/scripts/*.sh
- Monitoring →
*/scripts/monitor.sh
Bước 2: Chấm điểm 11 categories (110 điểm)
Per-check scoring (Wave 72b Bucket E): Every category below uses per-check pass/fail rubric per .claude/rules/audit-skill-rubric-quality-audit.md §2 (5+ sub-checks per category, P0/P1 severity). Any P0 sub-check FAIL caps category total ≤ (max - 4) AND audit-level verdict = FAIL regardless of total score. The bug list (every FAIL) precedes the score table. See bound rule for primacy + concrete sub-check enumeration mirroring Wave 71c security-audit pattern.
Scale change 2026-04-29 (v1.1): Cat 11 (Persona Coverage) added as 11th /10 category, raising max from 100 → 110. This preserves the relative weight of the original 10 tech categories (no rebalancing) while adding business-correctness signal that tech-only audits miss. Grade scale below adjusted proportionally. When citing a "score" in shorthand, use X/110 form.
1. E2E Functionality (10 điểm)
| Tiêu chí | Điểm | Check |
|---|
| E2E API tests pass 100% | 4 | test-api-e2e.sh 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→Instance | 2 | Manual hoặc E2E |
| AI features hoạt động (không chỉ mock) | 2 | Check AI provider config |
2. Security (10 điểm)
| Tiêu chí | Điểm | Check |
|---|
| Authentication: JWT + email verify + captcha | 3 | Code review |
| Rate limiting hoạt động | 2 | Gateway config |
| Không có secrets hardcode trong code | 2 | grep -r sensitive patterns |
| CORS configured đúng | 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 | mvnw test |
| 0 skipped tests | 2 | Check skipped count |
| Test coverage >70% | 2 | Jacoco 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 |
|---|
| KiteClass FE: vitest pass, <10% skipped | 3 | vitest run results |
| KiteHub FE: build pass (all pages) | 2 | next build |
| 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 gradient headers, shadow-soft |
| Theme system hoạt động (đổi màu visual) | 2 | Test ?primary=FF0000 URL |
| 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ả Docker containers healthy | 3 | docker compose ps |
| Production deployment plan có (Terraform) | 2 | Check terraform/ folder |
| Backup strategy documented | 2 | Check docs |
| Monitoring/alerting | 2 | Check dashboard/alerts |
| Secrets management documented | 1 | SECRET-MANAGEMENT.md |
8. Documentation (10 điểm)
Business docs at documents/01-business/ are SOURCE OF TRUTH. Score 0 for this category if no business docs exist for implemented domains.
| Tiêu chí | Điểm | Check |
|---|
| Business docs exist for all implemented domains | 3 | Check documents/01-business/ has doc for each service with business logic |
| Business docs match code - config keys, rules | 2 | Cross-check config keys in code vs business doc Config section |
| Architecture + guides + README up-to-date | 3 | Check planning/ docs, vietnamese/ folder, README, CLAUDE.md |
| Plans up to date with completion tracking | 2 | Check ✅/⬜ in 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 | User reports |
| Consistent coding style (ESLint, Checkstyle) | 1 | Pre-commit hooks |
| No dead code / unused imports | 1 | Linter results |
| Spring Boot latest patch version | 1 | Check pom.xml |
| Design patterns applied correctly (no anti-patterns) | 3 | .claude/rules/design-patterns.md §3 |
| Pattern choice documented (javadoc) | 1 | Spot check key services |
| No God Services (>500 lines / >15 methods) | 1 | find -size +20k *Service.java |
Design patterns check:
- No God Service trong kitehub-branding, core services
- Status transitions via State Pattern (not switch)
- External APIs wrapped by Adapter
- Events via Outbox (check
outbox_events table + publisher)
- External calls have Circuit Breaker + fallback
- No primitive obsession (value objects for structured types)
Reference: documents/02-architecture/ai-branding-design-patterns.md + .claude/rules/design-patterns.md
Document Generation Quality check (Wave 5+ — when kiteclass-core/module/document/** changes):
- Vietnamese diacritics (Đ, ễ, ă, ô, ơ, ư) round-trip through every format — verified by
PdfGeneratorTest.vietnamese_diacritics_round_trip_through_pdf_text_layer + DocxGeneratorTest.vietnamese_diacritics_preserved_in_contract_text + sample-emitter outputs
- VND currency formatted with
vi-VN locale (. thousand separator, no decimals) — BR-DOC-PDF-003, BR-DOC-DOCX-006
- Branding-aware outputs: PDF branded header, XLSX header-row fill, DOCX title run all derive from
branding.primaryColor / branding.logoUrl / branding.displayName injected by DocumentBrandingAssembler (Sub-PR 5.5). Renderers MUST fall back gracefully when keys are absent (BR-DOC-016)
- WCAG contrast: when
branding.primaryColor paints a fill (XLSX header), foreground text switches to white. PDF + DOCX use color on text and rely on tenant choosing readable colors — flag dark backgrounds for review.
- Filename in
Content-Disposition uses RFC-5987 UTF-8 encoding so VN diacritics in filenames survive (BR-DOC-014)
- Cross-format consistency proven by
DocumentBrandingIntegrationTest — when adding a 4th format (PPT/Wave 6), extend that test before merging.
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 Superpowers methodology | 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) — added 2026-04-29 (v1.1)
Source of truth: latest reports under documents/00-brd/persona-reviews/ produced via the persona-based-business-review skill quarterly cadence. GAP-152 ships the first round of Tier 1 review reports — until those land, this category scores 5/10 (mid-baseline) marked data pending per the data-pending policy below.
Data-pending policy: if no review report exists for ≥1 Tier 1 persona, score Cat 11 = 5/10 and annotate "data pending GAP-152". Do NOT score 0 (no data ≠ no coverage); do NOT score 10 (cannot claim full coverage without evidence). This 5/10 baseline holds steady until GAP-152 ships first reports.
| Tiêu chí | Điểm | Check |
|---|
| Tier 1 personas (Solo Teacher, Tutoring Center, Medium Center, K-12 School) all have a review report ≤90 days old | 3 | ls -lt documents/00-brd/persona-reviews/*.md + match each Tier 1 persona name |
| Each Tier 1 review's Coverage Analysis table has zero 🔴 critical (blocking-launch) gaps | 3 | Read each report's verdict + critical-gap section |
Quarterly cadence respected: latest review ≤current quarter (per persona-based-business-review.md §Quarterly Review Cadence) | 2 | Compare report date vs current EOQ window |
documents/00-brd/personas-catalog.md has fresh next_review field (not overdue) | 1 | grep next_review: frontmatter; compare to today |
Audit-driven persona gaps (filed via audit-to-gap-pipeline.md) are tracked in ROADMAP, not stale | 1 | grep recent persona-* gaps in ROADMAP |
Scoring guidance:
- 9-10/10: All Tier 1 reports current, zero critical persona gaps, cadence on track
- 7-8/10: All reports exist but ≥1 has open critical gap, OR cadence slipping by ≤1 quarter
- 5/10: Data pending (GAP-152 not yet shipped) — default neutral score
- 3-4/10: Reports exist for some personas only, OR cadence overdue ≥2 quarters
- 1-2/10: Reports exist but multiple critical gaps, no remediation in flight
- 0/10: ALL personas reviewed and overall verdict shows feature completeness <30% for ≥1 Tier 1 persona (system actively unusable for that persona at scale)
Reference: documents/00-brd/personas-catalog.md (canonical Tier 1 list), .claude/skills/quality/persona-based-business-review.md (review methodology + cadence), .claude/rules/meta-gap-priority.md §3 (business-logic tier rationale).
Bước 3: Output Report
# Quality Audit Report: [KiteHub/KiteClass/All]
**Ngày:** [date]
**Người đánh giá:** Claude Code
**Version:** [latest commit hash]
---
## 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 (rebased for /110 — proportional to the prior /100 thresholds)
- 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)
**Conversion note:** the new thresholds are the prior /100 thresholds × 1.1 (rounded). E.g., A was 90/100 = 0.90; now A starts at 99/110 = 0.90. Comparing audits across the v1.0 → v1.1 boundary: convert old `X/100` to equivalent `(X × 1.1)/110` before delta — OR add a "data pending" 5 to the old score for direct comparison (assumes Cat 11 baseline neutral).
---
## Detailed Findings
### ✅ Strengths (8+/10)
[List categories scoring 8+ with evidence]
### ⚠️ Needs Improvement (5-7/10)
[List categories with specific gaps]
### ❌ Critical Issues (<5/10)
[List categories with blockers]
---
## Improvement Roadmap
### Quick Wins (1-2 hours each)
[Items that give most score per effort]
### Medium Effort (0.5-1 day)
[Important improvements]
### Major Effort (2+ days)
[Strategic improvements]
---
## Comparison with Previous Audit
| Category | Previous | Current | Change |
|----------|----------|---------|--------|
| ... | ... | ... | +X/-X |
(Nếu có audit trước, so sánh. Nếu không, ghi "First audit")
---
## Action Items
| Priority | Item | Estimated Score | Effort |
|----------|------|-----------------|--------|
| 🔴 P0 | ... | +X | ... |
| 🟠 P1 | ... | +X | ... |
| 🟡 P2 | ... | +X | ... |
---
## Next Audit Recommended
Đề xuất chạy `/quality-audit` lại sau khi hoàn thành Phase [X] của improvement plan.
Bước 4: Lưu kết quả
- Save report to
documents/04-quality/audits/quality/quality-audit-[date].md
- Update
kitehub-quality-100-plan.md 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, Docker 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) — chạy tests + scan
- Agent 2: Categories 4-6 (Frontend Tests, CI/CD, UI/UX) — build + check design
- Agent 3: Categories 7-10 (DevOps, Docs, Code Quality, PM) — config + doc review
- 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 |
|---|
mvnw test | | tail -30 (chỉ summary) |
vitest run | | tail -20 |
npm run 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 dựa trên 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 (Docker down, etc.), ghi 0 điểm cho category đó + note lý do
- So sánh với quality plan nếu có (
kitehub-quality-100-plan.md)
- 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 đang chạy (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 đến target (branch/PR):
- PHẢI dùng
scripts/check-ci.sh --status để kiểm tra — KHÔNG dùng lệnh CI trực tiếp
- Nếu có runs
in_progress → dùng scripts/check-ci.sh (wait mode) để đợi
- PHẢI báo user: "CI đang chạy, đợi kết quả trước khi chấm điểm CI/CD"
- KHÔNG ĐƯỢC giả định pass/fail
- Chỉ sau khi CI completed → mới chấm điểm categories: CI/CD, Backend Tests, E2E
- Nếu user yêu cầu audit gấp → ghi rõ "CI/CD: PENDING (chưa có kết quả)" thay vì đoán điểm
Lý do: Audit trước đã kết luận CI pass trong khi thực tế CI đang chạy. Điều này làm sai lệch kết quả đánh giá và 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 hơn từng domain, dùng:
| 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 |
| UI/UX | /ui-review | Per-screen visual /128 |
| Persona Coverage | /persona-based-business-review | Quarterly role-play per Tier 1 persona — feeds Cat 11 score |
| Document Generation | (sample inspection — no dedicated skill yet) | Open documents/04-quality/samples/* after Wave 5 Sub-PR 5.6; spot-check VN diacritics, VND format, branding application across PDF/XLSX/DOCX outputs. |
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 — per memory
feedback_audit_calibration.md, do not trust standalone score; always compute delta vs prior baseline, not absolute number
- Audit grep scope must include -core submodules — search
kiteclass-core/ + sub-modules explicitly; missing them produces false-positive issue counts (GAP-107 incident — see feedback_audit_grep_scope.md)
- Targeted re-audit only after fix — full re-audit only on release / major refactor; per
feedback_targeted_audit.md re-score only categories affected by the fix
- First-run baseline is NOT a regression — when scoring a never-audited category (e.g., ops-readiness, performance pre-2026-04-19), low score is honest baseline, not drift
- Always use
scripts/check-ci.sh --status (read mode) for audit data; gh pr checks field state returns null and breaks polling — see feedback_monitor_gh_pr_checks_no_state_field.md
- Cat 11 (Persona Coverage) defaults to 5/10 until GAP-152 ships — do NOT score 0 (no data ≠ no coverage) or 10 (cannot claim full coverage without evidence). Once GAP-152 lands first 4 Tier 1 reports, Cat 11 becomes data-driven per the rubric in §11
- Comparing v1.0 (/100) vs v1.1 (/110) audits — convert old
X/100 to (X × 1.1)/110 before delta, OR add neutral 5 to old score's category sum. Don't compare raw integers across the scale change
Log
- 2026-04-29 (v1.1): Added Cat 11 Persona Coverage /10. Total scale moved 100 → 110 (proportional rebasing — original 10 categories untouched). Grade scale rebased ×1.1. References GAP-152 as data source; defaults to 5/10 baseline ("data pending") until first reports ship. Closes GAP-050 framework AC #6 ("quality-audit /100 adds persona coverage category referencing GAP-152 output"). Reviewer: @nguyenvankiet (solo-dev — paired with
pre-flight-check.md Layer 4 + persona-based-business-review.md §Quarterly Review Cadence in same PR per rule-change-process.md §6.5 Enforcement Parity Mandate).
- 2026-03 — 2026-04 (v1.0): Skill at 10 categories /100. Various calibration entries captured in memory (see
feedback_audit_calibration.md).
