Skip to content

USAGE.md

Latest commit

 

History

History
56 lines (48 loc) · 3.04 KB

USAGE.md

File metadata and controls

56 lines (48 loc) · 3.04 KB
Raw

USAGE — how teams actually run comprehension-debt

Install: pip install . (from this folder) → the cdebt command. No network, no API key required; everything runs locally and deterministically. Optional: export ANTHROPIC_API_KEY=... unlocks the --llm lanes (Claude drafts the WHY for you to verify; answers graded against the code). export CDEBT_LLM_MODEL=... overrides the model.

60-second tour (any git repo)

cdebt scan .                  # 0-100 risk per file + the evidence WHY
cdebt explain . <file>        # who understood it, and their captured WHY
cdebt gate . --base main      # CI guard: blocks risky un-understood changes
cdebt audit . --md audit.md   # governance evidence pack for the risk owner

Workflow 1 — developer, daily (mostly invisible)

The gate runs in CI on every PR (see action.yml). Clean PRs pass silently. When it blocks, repay in ~3 minutes: cdebt repay . # drafts ADR + 3 file-specific questions cdebt confirm . -i # answer in your own words (graded, grounded) Honest "I don't know" scores 0 — the file simply stays unrepaid until someone understands it. Using an AI tutor to learn first, then confirming what you verified, is the intended path.

Workflow 2 — tech lead, weekly

cdebt scan . --save-baseline  # record the index
cdebt trend                   # is dark debt growing?
cdebt repay . --path <file>   # schedule backlog repayments into the sprint
cdebt reverify .              # re-grade the whole corpus with today's grader

Declare AI-heavy history without trailers: echo '{"assume_ai": true}' > cdebt.json && cdebt scan . --config cdebt.json (Verified files are exempt; only unverified self-documentation is discounted.)

Workflow 3 — incident day

cdebt serve --port 8088       # Sentry/PagerDuty webhooks, or:
cdebt ingest . --payload incident.json     # source auto-detected

At ingest, the terminal surfaces understood by: NAME for the blamed files. Then close the loop: cdebt calibrate . # AUC / precision / lift on YOUR incidents # + the Miss Ledger: every incident the score # under-rated, with its likely blind spot cdebt recalibrate . # fold incidents into learned weights

Config (cdebt.json, passed via --config)

assume_ai          bool   declare AI-authored code without git trailers
assumed_ai_share   float  prior share (default 0.41)

Testing this product

python tests/test_suite.py    # 53 checks: every command + edge cases,
                              # no network, no API key, ~1 minute

See VALIDITY.md for what the score does and does not claim.

Benchmarking (reproducible predictive evidence)

git clone --depth 1 https://github.com/soarsmu/BugsInPy /tmp/BugsInPy
python benchmarks/bugsinpy_bench.py --bugsinpy /tmp/BugsInPy --project tqdm

For each REAL historical bug it checks out the buggy commit (no lookahead), scans, and reports the percentile rank of the bug file. 17 projects available.