Skip to main content

Technical Debt

Overview​

skylos debt <path> ranks structural technical debt hotspots using Skylos's static findings.

It deliberately separates two ideas:

  • Structural debt score: how much debt exists in the codebase or file hotspot
  • Priority score: what should be fixed first right now

Changed files and baseline drift raise priority, but they do not inflate the underlying structural debt score.

Basic Usage​

# Full project debt scan
skylos debt .

# Machine-readable output
skylos debt . --json

# Show only the top 10 hotspots in table output
skylos debt . --top 10

How Scoring Works​

Structural Score​

The structural score answers:

How much technical debt exists here?

This is what powers the repo-level debt percentage and each hotspot's score field.

Priority Score​

The priority score answers:

Which hotspot should I look at first?

Priority is higher when a hotspot is:

  • in a changed file
  • new versus the saved debt baseline
  • worsened versus the saved debt baseline
  • backed by stronger underlying severity signals

This is exposed as priority_score in JSON output and used to order hotspots in reports and agent workflows.

Changed-Only Reviews​

skylos debt . --changed
skylos debt . --changed --json

--changed is a view/filter mode, not a different scoring model.

When you use it:

  • the visible hotspot list is limited to git-changed files
  • the repo debt score stays project-scoped
  • changed files in .js and .jsx are included in changed-file discovery

This lets you review active work without pretending the whole repo suddenly has less debt.

Baselines​

# Save the current project debt baseline
skylos debt . --save-baseline

# Compare the current project to the saved baseline
skylos debt . --baseline

# Append the current project summary to debt history
skylos debt . --history

# Show saved debt history without running a new scan
skylos debt . --show-history

# Show only the latest saved history entries
skylos debt . --show-history --history-limit 5

Baseline status is reported per hotspot as one of:

  • new
  • worsened
  • improved
  • unchanged

Debt History Reports​

--history appends the current project score, risk rating, hotspot count, signal count, and latest top hotspot files to .skylos/debt_history.jsonl.

--show-history reads that saved history without running a new scan.

Example:

skylos debt . --show-history

Output includes the saved score trend and the latest recorded hotspot files:

Skylos Debt History
Entries: 2 shown (2 total)

Timestamp                         Score  Delta Risk       Hotspots  Signals
2026-05-01T00:00:00+00:00           72%      - HIGH             41      180
2026-05-02T00:00:00+00:00           76%     +4 MODERATE         38      160

Latest Top Hotspots:
  1. skylos/cli.py | score=36.50 | signals=6 | maintainability
  2. skylos/analyzer.py | score=35.00 | signals=5 | complexity

Machine-readable history is available with:

skylos debt . --show-history --json

Older history entries saved before hotspot details were recorded still load, but the latest-hotspot section will say the details were not recorded.

Important Scope Rule​

Debt baselines and debt history are project-level artifacts.

Because of that:

  • --save-baseline only works for project-root scans
  • --history only works for project-root scans
  • subdirectory scans can still use --changed and --baseline, but they cannot persist repo-wide baseline/history files

Policy Files​

Skylos can read a repo-local skylos-debt.yaml.

Example:

report:
  top: 10

gate:
  min_score: 70
  fail_on_status: new_or_worsened

Policy discovery starts from the scan target and walks upward toward the project root.

Explicit CLI flags still win. For example:

skylos debt . --top 20

will override report.top from the policy file.

JSON Output​

Example fields to expect in JSON output:

{
  "score": {
    "score_pct": 68,
    "scope": "project"
  },
  "summary": {
    "scope": {
      "score": "project",
      "hotspots": "changed"
    }
  },
  "hotspots": [
    {
      "file": "app/services.py",
      "score": 27.87,
      "priority_score": 38.87,
      "baseline_status": "worsened"
    }
  ]
}
# 1. Get a full project debt picture
skylos debt .

# 2. Save a baseline once the repo is in an acceptable state
skylos debt . --save-baseline

# 3. Review active work without distorting repo score
skylos debt . --changed

# 4. Check whether hotspots are getting worse over time
skylos debt . --baseline

# 5. Review saved debt score history and latest hotspot locations
skylos debt . --show-history