Code Quality Scoring

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