Quality Grades
Grade each product domain and architectural layer. Track gaps over time.
Triggers
grade qualityaudit domain qualityshow quality gapsrun quality gradesdomain quality report
Process
- Detect domains:
grade_domains.py auto-detects product domains from the repo layout (or use --domains to scope).
- Grade layers: each domain is scored A-F across six architectural layers (agents, skills, scripts, tests, docs, workflows), with gaps tagged critical, significant, or minor.
- Report: emit markdown or JSON; with
--output, the script loads prior JSON to compute per-domain trends (improving, stable, degrading, new).
- Act: address critical gaps first; rerun to track movement.
Quick Start
# Grade all auto-detected domains
python3 .claude/skills/quality-grades/scripts/grade_domains.py
# Grade specific domains as JSON
python3 .claude/skills/quality-grades/scripts/grade_domains.py --domains security memory --format json
# Write report to file (enables trend tracking)
python3 .claude/skills/quality-grades/scripts/grade_domains.py --output quality-grades.md
# Show top 10 domains by gap count
python3 .claude/skills/quality-grades/scripts/grade_domains.py --top-n 10
Grading Criteria
| Grade |
Score |
Meaning |
| A |
90-100 |
Full coverage, no known gaps |
| B |
75-89 |
Minor gaps, non-blocking |
| C |
60-74 |
Gaps present, should address |
| D |
40-59 |
Significant gaps, blocking quality |
| F |
0-39 |
Broken or missing |
Architectural Layers
Each domain is graded across six layers:
| Layer |
What it checks |
| agents |
Agent definition file completeness |
| skills |
SKILL.md presence and structure |
| scripts |
Automation scripts with docstrings |
| tests |
Test file coverage for the domain |
| docs |
Documentation in docs/ and .agents/ |
| workflows |
GitHub Actions workflow coverage |
Gap Severity
| Severity |
Meaning |
| critical |
Missing required artifact (blocks quality) |
| significant |
Important gap (should address soon) |
| minor |
Nice-to-have improvement |
Trend Tracking
When --output is used, the script loads previous JSON results to compute trends:
| Trend |
Meaning |
| improving |
Score increased by 5+ points |
| stable |
Score changed less than 5 points |
| degrading |
Score decreased by 5+ points |
| new |
No previous data |
When to Use
Use this skill when:
- Starting a quality improvement initiative across multiple domains
- Reporting on repo health to stakeholders
- Identifying which domains need the most attention
- Tracking quality trends over time via repeated runs
Use code-qualities-assessment instead when:
- Assessing code-level qualities (cohesion, coupling) for specific files
- Reviewing a single PR or module
Anti-Patterns
| Avoid |
Why |
Instead |
| Grading without context |
Scores depend on repo structure |
Run from repo root |
| Ignoring trends |
Single snapshots miss trajectory |
Use --output for persistence |
| Treating all F grades equally |
Some domains are optional |
Focus on domains with critical gaps |
Verification
After execution, run the bundled validator and require exit 0:
python3 .claude/skills/quality-grades/scripts/grade_domains.py --output quality-grades.md
echo "exit=$?" # must be 0; exit 2 means no domains detected (report is empty)
Scripts
| Script |
Purpose |
Exit codes |
scripts/grade_domains.py |
Grade detected domains across six layers; supports --domains, --format, --output, --top-n. |
0 success; 2 no domains detected (report is empty). |
scripts/check_grade_changes.py |
Compare current grades against a degradation threshold and open a GitHub issue when domains degrade or hit critical. |
0 no degradation; 1 script error or degradation detected. |
References
| File |
Content |
references/code-qualities.md |
Five foundational qualities (cohesion, coupling, DRY, encapsulation, testability) with diagnostics |
references/solid-principles.md |
SOLID overview, violation signs, mapping to code qualities, grading application |
references/kiss-principle.md |
Simplicity principles, KISS vs YAGNI, complexity justification criteria |
1---2name: quality-grades3description: Grade each product domain and architectural layer with A-F scoring and gap tracking. Produces markdown or JSON reports showing grades, file counts, gaps, and trends. Use when you ask "grade quality", "audit domain quality", "show quality gaps", "domain quality report", or "run quality grades" across a repo. Use for repo-wide A-F domain grading and trend tracking. Do NOT use for single-file maintainability scoring (use code-qualities-assessment) or a pre-merge review (use review).4license: MIT5---67# Quality Grades89Grade each product domain and architectural layer. Track gaps over time.1011<!-- vendor-portability: declared. The docs layer of the grader scans the consumer's docs/ and .agents/ for documentation coverage, and the skills layer reads .claude/skills/*/SKILL.md. These are scan targets, not preconditions: a vendored install without .agents/ grades the docs layer on whatever documentation the consumer repo has rather than failing. Issue #2050. -->1213## Triggers1415- `grade quality`16- `audit domain quality`17- `show quality gaps`18- `run quality grades`19- `domain quality report`2021---2223## Process24251. **Detect domains**: `grade_domains.py` auto-detects product domains from the repo layout (or use `--domains` to scope).262. **Grade layers**: each domain is scored A-F across six architectural layers (agents, skills, scripts, tests, docs, workflows), with gaps tagged critical, significant, or minor.273. **Report**: emit markdown or JSON; with `--output`, the script loads prior JSON to compute per-domain trends (improving, stable, degrading, new).284. **Act**: address critical gaps first; rerun to track movement.2930## Quick Start3132```python33# Grade all auto-detected domains34python3 .claude/skills/quality-grades/scripts/grade_domains.py3536# Grade specific domains as JSON37python3 .claude/skills/quality-grades/scripts/grade_domains.py --domains security memory --format json3839# Write report to file (enables trend tracking)40python3 .claude/skills/quality-grades/scripts/grade_domains.py --output quality-grades.md4142# Show top 10 domains by gap count43python3 .claude/skills/quality-grades/scripts/grade_domains.py --top-n 1044```4546---4748## Grading Criteria4950| Grade | Score | Meaning |51|-------|-------|---------|52| A | 90-100 | Full coverage, no known gaps |53| B | 75-89 | Minor gaps, non-blocking |54| C | 60-74 | Gaps present, should address |55| D | 40-59 | Significant gaps, blocking quality |56| F | 0-39 | Broken or missing |5758## Architectural Layers5960Each domain is graded across six layers:6162| Layer | What it checks |63|-------|---------------|64| agents | Agent definition file completeness |65| skills | SKILL.md presence and structure |66| scripts | Automation scripts with docstrings |67| tests | Test file coverage for the domain |68| docs | Documentation in docs/ and .agents/ |69| workflows | GitHub Actions workflow coverage |7071## Gap Severity7273| Severity | Meaning |74|----------|---------|75| critical | Missing required artifact (blocks quality) |76| significant | Important gap (should address soon) |77| minor | Nice-to-have improvement |7879## Trend Tracking8081When `--output` is used, the script loads previous JSON results to compute trends:8283| Trend | Meaning |84|-------|---------|85| improving | Score increased by 5+ points |86| stable | Score changed less than 5 points |87| degrading | Score decreased by 5+ points |88| new | No previous data |8990---9192## When to Use9394Use this skill when:9596- Starting a quality improvement initiative across multiple domains97- Reporting on repo health to stakeholders98- Identifying which domains need the most attention99- Tracking quality trends over time via repeated runs100101Use `code-qualities-assessment` instead when:102103- Assessing code-level qualities (cohesion, coupling) for specific files104- Reviewing a single PR or module105106---107108## Anti-Patterns109110| Avoid | Why | Instead |111|-------|-----|---------|112| Grading without context | Scores depend on repo structure | Run from repo root |113| Ignoring trends | Single snapshots miss trajectory | Use --output for persistence |114| Treating all F grades equally | Some domains are optional | Focus on domains with critical gaps |115116---117118## Verification119120After execution, run the bundled validator and require exit 0:121122```bash123python3 .claude/skills/quality-grades/scripts/grade_domains.py --output quality-grades.md124echo "exit=$?" # must be 0; exit 2 means no domains detected (report is empty)125```126127- [ ] `grade_domains.py` exited 0 (non-zero = no domains; the report is not valid)128- [ ] Each domain has grades for all six layers129- [ ] Gaps include actionable descriptions130131## Scripts132133| Script | Purpose | Exit codes |134|---|---|---|135| `scripts/grade_domains.py` | Grade detected domains across six layers; supports `--domains`, `--format`, `--output`, `--top-n`. | `0` success; `2` no domains detected (report is empty). |136| `scripts/check_grade_changes.py` | Compare current grades against a degradation threshold and open a GitHub issue when domains degrade or hit critical. | `0` no degradation; `1` script error or degradation detected. |137138## References139140| File | Content |141|------|---------|142| `references/code-qualities.md` | Five foundational qualities (cohesion, coupling, DRY, encapsulation, testability) with diagnostics |143| `references/solid-principles.md` | SOLID overview, violation signs, mapping to code qualities, grading application |144| `references/kiss-principle.md` | Simplicity principles, KISS vs YAGNI, complexity justification criteria |
rjmurillo