---
name: code-quality-scoring
description: "Vendor-neutral framework for scoring software health, estimating technical debt, assessing cloud readiness and open-source safety, and communicating quality to business stakeholders. Use when you need to quantify code health at the application or portfolio level rather than fix individual findings."
user-invocable: false
disable-model-invocation: true
version: 1.0.0
updated: "2026-06-15"
category: universal
author: bobmatnyc
license: Apache-2.0
progressive_disclosure:
entry_point:
summary: "Score software health (Resiliency + Agility + Elegance), estimate technical debt, assess cloud readiness and open-source safety, and frame all of it for business stakeholders"
when_to_use: "When assessing a whole codebase for health/debt/cloud-readiness, prioritizing remediation across a portfolio, or translating quality metrics into business language — not when fixing a single lint finding"
quick_start: "1. Compute Software Health as the average of Resiliency, Agility, Elegance sub-scores 2. Apply the red/orange/green bands 3. Convert violation density into an effort-to-fix estimate 4. Weight by business impact to prioritize 5. Present using the stakeholder framing in quality-communication-guide.md"
references:
- software-health-framework.md
- technical-debt-estimation.md
- cloud-maturity.md
- open-source-safety.md
- quality-communication-guide.md
context_limit: 800
tags:
- code-quality
- software-health
- technical-debt
- cloud-readiness
- open-source-safety
- metrics
- portfolio
requires_tools: []
---
# Code Quality Scoring
A vendor-neutral framework for **quantifying and communicating** software quality at the
application and portfolio level. Most quality skills tell you how to fix one finding;
this skill tells you how to *score* an entire codebase, *estimate* the cost of its debt,
and *explain* both to people who do not read code.
> **Source note:** The scoring frameworks below are derived from CAST Highlight's code
> quality indicators and methodology (https://doc.casthighlight.com/). They are
> paraphrased and re-expressed as a vendor-neutral model. Threshold bands and
> debt-density figures are CAST's proprietary calibration from their AppMarq benchmark
> dataset; they are presented here as **attributed reference ranges**, not as universal
> standards. Where CAST defers to open standards (COCOMO II for effort, SPDX/choosealicense
> for licenses, CWE/CVE for security), cite those primary sources.
## When to Use This Skill
Use it when the question is **"how healthy is this codebase, and what should we do
first?"** — for example:
- Onboarding to an unfamiliar codebase and needing a health baseline.
- Deciding whether to refactor, rewrite, or retire an application.
- Prioritizing remediation across many applications (a portfolio).
- Estimating the effort/cost a backlog of quality defects represents.
- Presenting a quality/debt position to a manager, product owner, or executive.
Do **not** reach for it to fix a single defect — for that, use the language-specific
quality skills (Python/Java/PHP/TS quality anti-patterns) and `code-review-standards`.
## Core Concept 1 — Software Health is a composite
Treat overall code health as the straight average of three independent dimensions, each
scored 0–100. This decomposition (derived from CAST Highlight) is useful because each
dimension maps to a *different* class of fix and a *different* stakeholder concern:
| Dimension | A.k.a. | Measures | Maps to checklist family |
|-----------|--------|----------|--------------------------|
| **Resiliency / Robustness** | Software Resiliency | Will it break in production? Error handling, defensive coding, reliability | Robustness, Security |
| **Agility / Changeability** | Software Agility | Can a team understand and change it quickly? Documentation, readability, naming | Changeability, Transferability |
| **Elegance / Efficiency** | Software Elegance | Is it lean? Complexity, dead code, algorithmic/data-access efficiency | Efficiency |
```
Software Health = avg(Resiliency, Agility, Elegance)
```
**Threshold bands** (attributed to CAST's calibration — use as guidance, not gospel):
| Band | Health | Agility (note the different cutoffs per dimension) |
|------|--------|-----------------------------------------------------|
| 🔴 Low / Red | below ~53 | below ~54 |
| 🟠 Medium / Orange | ~53–75 | ~54–69 |
| 🟢 High / Green | above ~75 | above ~69 |
The key insight is *not* the exact numbers — it is that each dimension has its own
distribution and its own remediation strategy, so a single blended grade hides the story.
A codebase can be green on Resiliency (rarely crashes) yet red on Agility (nobody can
change it safely). See **[software-health-framework.md](references/software-health-framework.md)**.
## Core Concept 2 — Technical debt is an effort-to-fix estimate
Express debt as **estimated remediation effort**, derived from violation density scaled
by a per-line-of-code debt factor that varies by language. Higher-level / verbose
languages (Java, JavaScript, PHP) tend to carry more debt per LOC than concise scripting
languages (Python, shell). Always present these as **attributed ranges** ("Java's median
debt density is roughly 3–4× Python's per industry benchmarks") rather than copied exact
figures, and convert to money/time only with explicit assumptions stated. CAST's
maintenance-effort model itself builds on **COCOMO II**. See
**[technical-debt-estimation.md](references/technical-debt-estimation.md)**.
## Core Concept 3 — Cloud readiness is scan + survey
Cloud maturity is the average of a **code-scan** score (blockers and boosters detected in
source — e.g. hard-coded file paths and host names are blockers; statelessness and
externalized config are boosters) and a **survey** score (team/operational factors the
code cannot reveal). See **[cloud-maturity.md](references/cloud-maturity.md)**.
## Core Concept 4 — Open-source safety is a three-part index
Third-party risk is the average of **Security** (CVE count weighted by criticality),
**License Compliance** (share of low- vs medium- vs high-risk licenses), and
**Obsolescence** (version gap to latest). This cross-references the Phase 1 OSS Safety
work — do not duplicate it. See **[open-source-safety.md](references/open-source-safety.md)**,
and for remediation mechanics use `universal/security/security-scanning` and
`toolchains/universal/dependency/dependency-audit`, which already carry the license-risk tiers and
CVE-weighting framing.
## Core Concept 5 — Prioritize by business impact
A defect-dense application nobody depends on is lower priority than a moderately-flawed
revenue-critical one. Blend a technical risk score with a **business impact** score
(failure consequences, audience size, release/maintenance effort) so remediation is
ranked by *risk to the business*, not by raw defect count. CAST formalizes this as a
ROAR-style index (risk weighted by business impact). See
**[quality-communication-guide.md](references/quality-communication-guide.md)**.
## How to Apply (quick workflow)
1. **Score the three health dimensions** from your existing linters/scanners — map each
tool's findings into Resiliency / Agility / Elegance, average to a Health score, place
on the red/orange/green band.
2. **Estimate debt** — multiply violation density by the language's debt factor (as an
attributed range), express as effort (hours/FTE) with assumptions stated.
3. **Score OSS safety and cloud readiness** if relevant to the decision.
4. **Weight by business impact** to rank applications/modules.
5. **Communicate** using the stakeholder framing — lead with risk and money, not rule
names.
## Anti-Patterns
- **Reporting a single blended grade** and hiding the dimension that is actually red.
- **Quoting debt in exact dollars** without stating the LOC, hourly rate, and density
assumptions — present ranges and assumptions.
- **Treating CAST's threshold numbers as universal law** — they are one vendor's
calibration; cite them as reference context.
- **Ranking remediation by defect count** instead of by business-weighted risk.
- **Duplicating the OSS license tiers here** — cross-reference the Phase 1 references.
## Navigation
- **[Software Health Framework](references/software-health-framework.md)** — the
Resiliency/Agility/Elegance decomposition, bands, and how to map linter output onto it.
- **[Technical Debt Estimation](references/technical-debt-estimation.md)** — effort-to-fix
model, per-language debt-density ranges (attributed), COCOMO II linkage, worked example.
- **[Cloud Maturity](references/cloud-maturity.md)** — scan vs survey, code blockers and
boosters, how to read a cloud-readiness score.
- **[Open Source Safety](references/open-source-safety.md)** — the Security/License/
Obsolescence index; cross-references to the dependency-audit and security-scanning skills.
- **[Quality Communication Guide](references/quality-communication-guide.md)** — business-
impact framing, ROAR-style prioritization, presenting scores to non-technical stakeholders.
## Related Skills
- **code-review-standards** — per-finding checklist with Efficiency + Transferability
dimensions (Phase 1); this skill aggregates those families into scores.
- **security-scanning** / **dependency-audit** — OSS safety remediation mechanics.
- **software-patterns** — architectural signals that low Elegance/Agility scores point to.