skills.rest
paulingham
paulinghamCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

debt-ledger

Scan repositories for DEBT: markers and produce a per-file ledger.

1|Updated Mar 15, 2026
Search Tags:#scanning#markers#ledger#debt#code-debt#deliberate-simplification
One-click install
npx skills add https://github.com/paulingham/.claude --skill debt-ledger
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debt-ledger
Source: https://github.com/paulingham/.claude/tree/main/skills/debt-ledger
Command: npx skills add https://github.com/paulingham/.claude --skill debt-ledger

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Advisory and automated tool to identify and surface deliberate-simplification debt markers (DEBT:) across a codebase, render a per-file ledger, and flag entries with no upgrade trigger (silent rot). It remains advisory, never gating progress.

Core Features & Use Cases

  • Gathers all DEBT: markers across the repository and collects them into a grouped ledger.
  • Renders a per-file ledger, highlighting whether each marker has an upgrade trigger or is no-trigger.
  • Excludes noise like vendor and build directories to keep focus on actionable debt.
  • Use Case: During Reflect to track debt trends and surface silent rot, or in periodic sweeps to keep the codebase debt visible.

Quick Start

Scan the repository for DEBT markers and render a per-file ledger for review.

Frequently Asked Questions about debt-ledger

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I scan my codebase for deliberate technical debt markers?▼

To scan for codebase debt markers, the tool identifies DEBT: comments across the repository and groups them into a per-file ledger. It classifies entries as having an upgrade trigger or no-trigger while excluding build and vendor directories to reduce noise.

What is a no-trigger debt marker and why does it cause silent rot?▼

A no-trigger debt marker is a DEBT: comment lacking a defined upgrade condition. These markers cause silent rot because they lack an automated trigger for resolution, allowing the deliberate simplification to persist unnoticed during periodic codebase sweeps.

How do I track code debt trends without blocking development progress?▼

Tracking code debt without blocking progress requires an advisory ledger that surfaces DEBT: markers in a non-blocking format. This approach produces a clear verdict of DEBT_LEDGER_WRITTEN or DEBT_LEDGER_CLEAN to support debt governance without gating pipelines.

Does the debt marker scanner exclude vendor and build directories?▼

Yes, the debt marker scanner excludes vendor and build directories by default. This noise exclusion keeps the generated ledger focused on actionable code debt markers within the actual source files of the repository.

What is the best way to identify deliberate simplification debt in a repository?▼

The best way to identify deliberate simplification debt is using an advisory scanner to collect DEBT: markers into a grouped ledger. This method highlights whether each marker has an upgrade trigger, producing a final DEBT_LEDGER_WRITTEN or DEBT_LEDGER_CLEAN verdict for governance.

Related Skills

Explore More Software Engineering Skills→
marmelabmarmelab

ponytail-debt

Scan repository files for ponytail: comment markers and generate a structured debt ledger.

Official
Intermediate
All-The-VibesAll-The-Vibes
50

unslop

Detect and report AI-generated slop in code, comments, and UI artifacts.

Official
Intermediate
richardnguyen0715richardnguyen0715

code-review-and-quality

Automate code review against correctness, readability, architecture, security, and performance criteria.

Community
Advanced
travisjneumantravisjneuman
88

tech-debt-analyzer

Analyze codebases for technical debt using Python static analysis scripts.

Community
Intermediate