Grade

🎯 GOAL

Produce a Software Quality Report with:

• Overall score (0–100) with letter grade and confidence level
• Mode: full or diff (with base ref)
• Hard-fail blockers (citing specific signals)
• Per-domain scores (7 domains, ISO 25010-aligned)
• Evidence table (mechanical measurements + tool provenance)
• Judged findings (each citing ISO sub-characteristic + inspection target + justification)
• Trend vs previous run
• Top risks
• Fastest improvements

🧩 ARGUMENTS

Default base ref resolution for --diff with no ref:

1. Try git rev-parse --verify main → use if it exists
2. Else git rev-parse --verify master → use
3. Else abort: "Could not resolve a default base ref. Pass one explicitly."

Record the resolved base ref in base_ref and mention it in the report header.

🧱 DOMAINS — ISO 25010 aligned

Total = 100.

🚨 HARD-FAIL GATES

Cap the overall grade at D (≤69) and list blockers FIRST when any of these concrete signals fire. Every blocker in the output must cite the exact signal value that triggered it.

Explicitly NOT hard-fails (track as risks, not blockers):

• tests=timeout / typecheck=timeout — inconclusive; note in Evidence and Top Risks
• tests=missing / typecheck=missing — scored 0 but not a gate; the stack may genuinely lack one
• Aspirational concerns ("no prod tests", "unsafe admin access") — note in Top Risks with concrete evidence or not at all

📊 SCORING RULES

Each row below is either [M] Mechanical (tool-backed threshold → score) or [J] Judged (LLM decides based on ISO sub-characteristic + evidence + inspection).

For [M] rows: apply the threshold mechanically. Same inputs = same score. If a signal is unknown (tool not installed, no data), award the "Unknown" column and flag the absence in Missing.

For [J] rows: pick one of three bands — Low / Medium / High — each mapping to a fixed point value. The LLM must:

1. Cite the ISO 25010 sub-characteristic being evaluated
2. Read the numeric evidence signal(s) listed
3. Use the Explore subagent to inspect the specific sites (file paths) the evidence points to — always required for judged criteria worth ≥4 points
4. Pick Low/Medium/High and write a one-sentence justification citing specific file paths
5. Anchor to previous entry: if the evidence signals are within ±10% of the prior run's and no material code change is detected, inherit the prior judged score unless there's a specific reason to deviate

1. Correctness (20) — ISO 25010: Functional Suitability

2. Reliability (15) — ISO 25010: Reliability

All rows are [J] — there is no static tool that measures runtime reliability. The LLM inspects code for resilience patterns anchored to the ISO sub-characteristic definitions.

3. Maintainability (15) — ISO 25010: Maintainability

4. Security (15) — ISO 25010: Security

5. Performance (10) — ISO 25010: Performance Efficiency

All rows are [J] — runtime performance can't be measured statically. The LLM spot-checks hot paths guided by evidence counts.

6. Test Quality (15) — ISO 25010: Functional Suitability + Testability

7. Operational Readiness (10) — DORA-readiness (static enablers)

Note: real DORA metrics need production data. This domain scores enablers — static artifacts that make DORA possible.

Scoring sum: add per-criterion points within each domain, cap at the domain max, sum domains for overall (0-100). Letter grade: A ≥90, B ≥80, C ≥70, D ≥60, F <60 — capped at D (69) if any hard-fail gate trips.

🔍 EVIDENCE COLLECTION

Tool priority (highest to lowest confidence)

1. Native tool output — tests, lint, typecheck, coverage, security_high from stack-specific runners
2. Multi-language analysis tools — lizard (complexity), jscpd (duplication), gitleaks (secrets)
3. Filesystem / presence checks — Dockerfile, CI config, health endpoint strings
4. LLM inspection via Explore — for judged criteria, always constrained to specific file paths from evidence signals
5. Heuristic evidence counts — from heuristics.sh; used as hints for judged criteria, never as direct score inputs

Missing data

If a signal is unknown:

• For [M] rows: use the "Unknown" column of the scoring table; add to Missing section
• For [J] rows: if the evidence signal is missing, rely on Explore inspection alone and note lowered confidence

Never regex-substitute for a missing real measurement.

📈 CONFIDENCE

Set based on how much of the scoring was tool-backed:

• High — Native tools (tests/lint/typecheck/audit) ran, AND at least 2 of {lizard, jscpd, gitleaks} ran, AND coverage is known
• Medium — Most native tools ran, but some of {lizard, jscpd, gitleaks} missing
• Low — Multiple native tools missing OR all three universal tools missing

State the confidence level in the report header and name the specific missing tools.

📄 OUTPUT FORMAT (STRICT)

# Software Quality Report

**Overall Score**: <0-100>/100
**Grade**: <A|B|C|D|F>
**Confidence**: <High|Medium|Low>
**Mode**: <full | diff vs <base_ref> (<N> files)>
**Commit**: <short-sha>

---

## 🚨 Hard-Fail Blockers
<List each blocker with the exact signal value that fired it, or "None">

---

## 📊 Domain Scores

| Domain                  | Score     | Notes (brief) |
|-------------------------|-----------|---------------|
| Correctness             | X/20      | ...           |
| Reliability             | X/15      | ...           |
| Maintainability         | X/15      | ...           |
| Security                | X/15      | ...           |
| Performance             | X/10      | ...           |
| Test Quality            | X/15      | ...           |
| Operational Readiness   | X/10      | ...           |
| **TOTAL**               | **X/100** |               |

---

## 📈 Trend
<One of:>
- `No prior runs — baseline established.`
- `vs <prev date> (<prev commit>): overall <+N|-N|±0>, grade <prev>→<new>, confidence <prev>→<new>`
  + domain deltas (only those ≥ ±1)
  + signal deltas (only those that materially moved)

---

## 🔍 Evidence

### Mechanical (tool-backed)
| Signal | Value | Tool | Scoring criterion |
|---|---|---|---|
| tests | <pass/fail/...> | <jest/pytest/...> | 1.1 |
| typecheck | ... | ... | 1.2 |
| ... | | | |

### Judged findings (ISO 25010-anchored)
- **[Domain.N] Criterion — <Low/Med/High → +N>**: one sentence justification citing `path/to/file.py:42` and the ISO sub-characteristic.
- ...

### Missing
- `<signal>` — `<tool>` not installed / not applicable. Install: `<install command>`.
- ...

---

## ⚠️ Top Risks
1. <risk> — <impact> — <specific path>
2. ...

---

## 🛠️ Fastest Improvements
1. <action> — <expected point gain> — <effort estimate>
2. ...

---

## Summary
<2-4 sentences: overall state, biggest lever, recommended next step>

EXECUTION RULES

Follow this flow in order. Steps marked [full only] or [diff only] are mode-specific.

1. Read standards.md once per session if you haven't yet — it contains the philosophy and threshold citations.
2. Parse arguments per the ARGUMENTS section. Resolve mode and, for diff mode, the base ref.
3. Capture provenance: git rev-parse --short HEAD and ${CLAUDE_SKILL_DIR}/trend.sh slug.
4. [full only] Commit cache check (see COMMIT CACHING). Cache hit → print cached report, stop.
5. Read the previous entry for this mode: ${CLAUDE_SKILL_DIR}/trend.sh prev <slug> <mode>. Empty result = first run → baseline.
6. Run signal collectors:
   • Always: ${CLAUDE_SKILL_DIR}/grade.sh from the repo root → project-wide signals.
   • [diff only] Also: git diff --name-only <base_ref>...HEAD > /tmp/grade-diff-files.<pid>.txt && ${CLAUDE_SKILL_DIR}/diff_scan.sh /tmp/grade-diff-files.<pid>.txt → diff-scoped signals. Clean up the tmp file after.
7. Parse SIGNAL: lines from both scripts into a signals dict. In diff mode, *_scope=diff signals override the matching *_scope=project signals for diff-scoped criteria (lint, secrets, complexity, duplication, largest_file_lines, heuristic evidence). Tests/typecheck/coverage/security_high/deploy_artifact_count stay project-wide regardless.
8. Apply [M] scoring mechanically from the tables. These scores must be reproducible — the same signals must always produce the same numbers.
9. Apply [J] scoring per the pattern:
   • For each [J] criterion, read the listed evidence signal(s)
   • For criteria worth ≥4 points, use the Explore subagent with a specific inspection target ("look at these 5 files for X pattern"); for <4 point criteria, a quick Read is sufficient
   • Pick Low/Medium/High and write a one-sentence justification citing specific paths + the ISO sub-characteristic
   • Anchor to previous entry: if evidence signals are within ±10% of the prior run's and the mechanical signals haven't materially changed (no new fail/pass transitions, complexity/duplication within 1% band), inherit the prior judged scores unless you have specific new evidence. State "inherited from prev" in the justification.
10. Check hard-fail gates. If triggered, cap at D (≤69) and list blockers first, each citing the signal value.
11. Append history entry (see TREND TRACKING).
12. Emit the report per OUTPUT FORMAT. Every score must be traceable to either a tool output (for [M]) or an inspection with file paths + ISO citation (for [J]).

💾 COMMIT CACHING

Applies to full mode only. Diff mode always re-runs (the diff set can change independently of HEAD).

Cache-hit conditions (ALL must be true):

1. git rev-parse --short HEAD matches the commit field of the latest full-mode history entry
2. git status --porcelain is empty (working tree clean)
3. Mode is full

On cache hit: print this short report and stop. Do NOT run grade.sh, diff_scan.sh, or append a new history entry.

# Software Quality Report (cached)

Current HEAD `<sha>` matches the most recent full-mode grade. No re-audit performed.

**Previous score**: <overall>/100 <grade> (Confidence: <conf>)
**Recorded**: <date>

Run `/grade-history` for the full timeline. To force a re-audit, commit or stash your changes, or use `/grade --diff` to grade uncommitted work against a base ref.

🎯 DIFF MODE

Grades only files changed between HEAD and the base ref.

Signal scoping

Heuristic constraints in diff mode

All [J] inspection via Explore must be scoped to the changed files only. Pass the file list explicitly. A reliability issue in an untouched file is not relevant to grading this diff.

Empty diff

If git diff --name-only <base>...HEAD returns no files:

No files changed between HEAD and <base_ref>. Nothing to grade in diff mode.

Stop. Do not append a history entry for an empty diff.

📈 TREND TRACKING

Every run is persisted so the next run can diff against it. Full-mode and diff-mode histories are stored in separate files so trajectories don't mix.

Flow:

1. slug=$(trend.sh slug) from repo root
2. prev=$(trend.sh prev <slug> <mode>) — third arg keeps modes separate
3. Capture commit=$(git rev-parse --short HEAD)

After scoring, build a v1 JSON entry (single-line, no pretty-printing):

{"v":1,"date":"YYYY-MM-DD","commit":"<short-sha>","mode":"<full|diff>","base_ref":"<ref or null>","overall":N,"grade":"<A-F>","confidence":"<High|Medium|Low>","domains":{"correctness":N,"reliability":N,"maintainability":N,"security":N,"performance":N,"test_quality":N,"operational_readiness":N},"signals":{"tests":"<pass|fail|timeout|missing>","lint":"<pass|fail|timeout|missing>","typecheck":"<pass|fail|timeout|missing>","coverage":"<N|unknown>","security_high":"<N|unknown>","secrets":"<N|unknown>","secrets_tool":"<gitleaks|rg-fallback|none>","largest_file_lines":"<N|unknown>","lizard_warning_count":"<N|unknown>","lizard_avg_ccn":"<N|unknown>","duplication_pct":"<N|unknown>","deploy_artifact_count":"<N|unknown>","health_endpoint_count":"<N|unknown>","observability_lib_present":"<0|1|unknown>","validation_lib_present":"<0|1|unknown>","suppression_count":"<N|unknown>","timeout_retry_count":"<N|unknown>","blocking_io_count":"<N|unknown>","logging_call_count":"<N|unknown>","test_file_count":"<N|unknown>","test_sleep_count":"<N|unknown>"}}

Field rules:

• mode: "full" or "diff" — required
• base_ref: resolved ref in diff mode (e.g. "main"), null in full mode
• signals.*: numeric values stored as strings so "unknown" can coexist with numerics
• Omit fields that are genuinely absent — older v1 entries may have fewer keys and are still valid

Append: ${CLAUDE_SKILL_DIR}/trend.sh append <slug> '<json>' <mode> — writes to <slug>.jsonl or <slug>.diff.jsonl.

Populate the Trend section by diffing the prev entry against this one. For first-mode runs: No prior runs — baseline established.

Schema compatibility:

• v0 entries have no v field → score deltas only, signals marked n/a
• v1 entries without mode → treat as mode=full

Never silently skip the append — the history file is the whole point. If append fails, surface the error in the Trend section.