# Quality Audit

> 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).

- **Type:** Skill
- **Install:** `agentstack add skill-victoraurelius-claude-starter-kit-quality-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [VictorAurelius](https://agentstack.voostack.com/s/victoraurelius)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [VictorAurelius](https://github.com/VictorAurelius)
- **Source:** https://github.com/VictorAurelius/claude-starter-kit/tree/main/skills/quality-audit

## Install

```sh
agentstack add skill-victoraurelius-claude-starter-kit-quality-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

**Usage:** `/quality-audit [|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:

```bash
# 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  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)

| 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,  **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 /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

```json
{
  "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:

| 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [VictorAurelius](https://github.com/VictorAurelius)
- **Source:** [VictorAurelius/claude-starter-kit](https://github.com/VictorAurelius/claude-starter-kit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-victoraurelius-claude-starter-kit-quality-audit
- Seller: https://agentstack.voostack.com/s/victoraurelius
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.