- Home
- Skills
- Code Quality & Review
- Technical Debt Triage — Prioritized, Evidence-Based Backlog
Technical Debt Triage — Prioritized, Evidence-Based Backlog
Turn codebase signals into a focused backlog: verified root causes, separate investigation leads, transparent priorities and actionable acceptance criteria.
$20
Works with the AI Agents you already use
Technical Debt Triage — Prioritized, Evidence-Based Backlog
Example session with this skill installed
Synthetic evaluation with a fictional 10-file Python/TypeScript/Rust order-service repository supplied as context.
Use $technical-debt-triage to triage this small repository for technical debt worth fixing. Inspect all relevant languages, keep it read-only and offline, do not execute project code, and return at most five confirmed root-cause groups plus three investigation leads with a useful backlog.
Context includes documented inventory reservation and retry-delay contracts, both public reservation entrypoints, a shared reservation function, a retry helper, a cache with an unavailable external caller, CLI JSON output, a Rust constant/test, a negative TypeScript type test, a placeholder environment template and Python tests. This is a controlled synthetic example, not a customer audit.
- Read your context and instructions
- Compiled the technical debt triage
Synthetic evaluation: actual complete agent report. Only local absolute paths are redacted below; this is not a customer benchmark.
Technical-debt triage — mixed fixture
Target: fictional mixed fixture (local absolute path redacted).
All evidence paths below are relative to this target.
Recommended backlog
| Order | Group | Action | Impact | Confidence | Effort |
|---|---|---|---|---|---|
| 1 | G1: Shared reservation boundary accepts nonpositive quantities | Act next | High for documented inventory behavior | High, static | S: about half a day–one day |
| 2 | G2: Retry default overwrites explicit zero | Plan | Medium, bounded timing-contract violation | High, static | S: about half a day–one day |
Fix G1 first because a directly callable reservation can increase inventory. G2 is independent and smaller in behavioral scope. Estimates include implementation, focused regression checks and review, assuming the supplied interfaces are complete and no external compatibility migration is needed. Deployment and release effort are unknown. No project code or tests were executed.
G1 — Missing positive-quantity validation in the shared reservation function
Status: confirmed by static inspection; not reproduced.
Evidence and contract: CONTRACTS.md:5 requires both public entrypoints to reject zero and negative quantities with ValueError, and explicitly rules out middleware validation. api.py:4–5 (reserve_http) and api.py:8–9 (reserve_job) pass quantity directly to inventory.reserve. inventory.py:1–5 checks only whether stock is less than quantity before subtracting it.
Trigger and consequence: With stock of 5, a quantity of -2 passes the insufficient-stock check and the subtraction changes stock to 7. Quantity 0 succeeds and returns 5 instead of raising ValueError. Both entrypoints share this cause and belong in one remediation group. The contract violation is directly traceable; no production exposure or frequency is established.
Counterevidence checked: The inspected public callers contain no validation, and the contract says callers invoke them directly. test_inventory.py:6–8 checks only a valid reservation through the shared function. The integration-service skip at lines 10–12 does not guard these local input cases. The existing insufficient-stock guard is useful but does not establish quantity positivity.
Impact/confidence: High for broken documented core reservation behavior and inventory inflation; high confidence from the explicit contract and complete local call chain. Durability, monetary loss and real deployment are not established.
Bounded remedy: Validate quantity > 0 in inventory.reserve before mutation, raising ValueError otherwise. Keep both public entrypoints using this single boundary. No storage redesign, concurrency changes or broader input-type policy is needed; the contract already specifies integer quantities and string SKUs.
Acceptance criteria and proposed regression checks: Through each public entrypoint, quantities 0 and -2 raise ValueError and leave the stock dictionary unchanged. Positive requests subtract exactly the requested units; exact-stock requests succeed with a zero balance; requests above stock raise ValueError without mutation. Add focused local tests for the shared boundary and both entrypoint integrations. These checks are proposed, not executed. No remediation dependency was found inside the target.
G2 — Truthiness default discards an explicitly requested immediate retry
Status: confirmed by static inspection; not reproduced.
Evidence and contract: CONTRACTS.md:7 says omitted wait defaults to 1000 ms and zero means retry immediately. retry.ts:1–2 implements retryDelay(waitMs?: number) using waitMs || 1000, which selects 1000 for zero.
Trigger and consequence: retryDelay(0) returns 1000 rather than 0, losing the caller's requested immediate delay. Actual scheduler use, retry counts and aggregate latency are absent, so no outage or measured performance claim is made.
Counterevidence checked: The helper itself accepts the caller-selected value under the documented contract; there is no conditional guard preserving zero. types.test.ts:1–4 is a separate negative SKU type test and supplies no counterevidence for this runtime behavior. An external caller is not required to establish that the helper's specified return behavior is violated.
Impact/confidence: Medium for bounded incorrect delay selection; high confidence from the explicit zero/omission contract and direct expression semantics.
Bounded remedy: Default only when waitMs is undefined, preserving zero and supplied delays; a default parameter or explicit undefined check is sufficient. Do not introduce an unsupported policy for negative, NaN or other out-of-contract values as part of this fix.
Acceptance criteria and proposed regression checks: Omitted and explicit undefined input return 1000; zero returns 0; representative positive inputs such as 1 and 250 return unchanged. Add a focused helper test in the project's eventual test setup. These checks are proposed, not executed. No TypeScript test-runner manifest/configuration is supplied, so runner integration and external compatibility require confirmation before committing the estimate. No dependency on G1.
Separate investigation queue
L1 — Establish cache cardinality and lifecycle before adding eviction
Action: Investigate. Impact: unknown; potentially material memory growth if a long-lived process receives unbounded distinct keys or large values. Confidence: low for any defect. Effort: unknown until the external caller is available; the first step is a bounded caller/lifecycle review.
Evidence: cache.py:2 creates a module-level dictionary; remember at lines 5–6 retains entries and recall at lines 9–10 reads them. No local eviction is present. However, cache.py:1 explicitly says its separately deployed caller is not supplied. Repeated writes to a fixed finite key set could be intentional and bounded.
Missing facts: Key producer, distinct-key cardinality, value sizes, process lifetime, intended retention and invalidation semantics.
Smallest discriminating check: Obtain and statically inspect that caller and its lifecycle/retention contract in a separately authorized pass. Confirm a retention problem only if the caller demonstrably retains obsolete data or permits growth beyond its intended resource/lifetime bounds; dismiss the unbounded-growth hypothesis if the intended finite key set and suitable value/lifetime bounds are established. No caller lookup, profiling or production access was performed. Do not add an arbitrary TTL before establishing the contract.
Only one investigation lead is supported; the three-lead cap is not a quota.
Dismissed signals
- CLI print and explanatory comments: cli.py:5–8 implements the JSON-stdout contract in CONTRACTS.md:7. Printing this result is intended output, and the comments explain the protocol; neither establishes debt.
- Rust unwrap: constant.rs:5–10 confines it to a test parsing the valid literal "12" as u32. The exported label function at lines 1–3 simply formats a constant. No reachable failing production parse was found.
- TypeScript suppression: types.test.ts:2–3 deliberately checks rejection of a numeric SKU. It is a negative type test, not evidence of bypassed runtime validation. Compiler/test execution was not checked.
- Configuration template: .env.example:1–2 contains a documentation endpoint and an explicit token placeholder, consistent with CONTRACTS.md:3. No actual credential exposure is evidenced.
- Skipped integration test: test_inventory.py:10–12 gives an external-service prerequisite. That skip alone does not prove a CI or coverage defect. Missing local quantity cases inform G1's proposed checks rather than creating a separate root-cause group.
Coverage and limits
- Inspected all 10 inventoried target files: CONTRACTS.md; api.py; inventory.py; cache.py; cli.py; test_inventory.py; retry.ts; types.test.ts; constant.rs; .env.example. This covers the visible Python API, inventory, cache, CLI and unittest content; TypeScript helper and negative type test; Rust implementation and inline test; contract and safe configuration template.
- Also read the skill's SKILL.md and its prioritization, signals and examples references. Total content-read ledger: 10 target files plus 4 guidance files, within the 40-file cap even when counted together.
- Considered 8 candidate groups: reservation validation (confirmed), retry default (confirmed), cache retention (lead), CLI print/comments, Rust unwrap, negative type suppression, configuration placeholders and skipped integration test (the latter five dismissed). This is within the 12-candidate cap. Returned 2 confirmed groups and 1 lead, below the 5/3 caps; no confirmed groups were dropped or merged to meet a cap.
- Revision and tracked/dirty status are unknown. There is no .git entry in the target inventory, and ancestor Git metadata was outside the explicitly allowed read scope. No applicable instruction file or dependency/build manifest was present in the target inventory. Ancestor instructions and external callers were not read under that scope restriction.
- Available tools used: read-only directory/file listing, rg file inventory, cat and numbered source reads. No necessary read tool was unavailable. No runtime, compiler, test runner or dependency installation was attempted.
- Existing tests were statically inspected only. Proposed checks were not executed; there are no measured coverage or performance results. No network calls, vulnerability/advisory checks, remote reads, issue creation or target changes were performed. Current dependency vulnerability status was not checked and no dependency manifest was supplied.
- Stopped because all allowed target files were inspected and supported candidates were classified, not because the budget was exhausted. External cache producers, deployment/CI wiring and production behavior remain outside this report. The sole authorized write is this report (local output path redacted).
Connects securely to your tools. The creator never sees your data.
About this skill
Decide what is worth fixing before you start another implementation pipeline. Technical Debt Triage guides a coding agent through a bounded, evidence-based review of a repository or directory.
What you get
- Confirmed findings tied to inspected contracts, callers, code paths and concrete consequences.
- Separate investigation leads when reachability, context or a required source file is missing.
- Root-cause grouping so repeated symptoms do not become duplicate backlog items.
- Transparent impact, confidence and effort judgments, with uncertainty and ranking rationale.
- Focused remedies, observable acceptance criteria and proposed regression checks.
- A coverage ledger, explicit inspection budget and dismissed false positives.
Logs, TODOs, large files, type suppressions and test filenames are signals to investigate, not automatic defects. The default pass is offline and read-only, with caps of 40 inspected files, 12 candidate causes, five confirmed groups and three investigation leads. You can specify another scope or budget.
Included
A standalone SKILL.md, signal interpretation guide, prioritization and reporting guide, worked examples, usage instructions and MIT license. No executable runtime or required second model.
Requirements and limits
Use with a capable coding agent that can read files, or supply source excerpts. Git and search tools are optional. Model and host usage costs are separate. This is a Markdown skill, not a standalone scanner or enforced OS sandbox. Test execution, edits, remote audits and issue creation are opt-in actions subject to your host permissions. It does not promise exhaustive coverage, security certification, measured test coverage or guaranteed defect detection.
Validation
The package has structural and synthetic-fixture checks, plus two independent agent trials: a Python/TypeScript/Rust sample and a source-excerpt scenario without tools. These limited synthetic trials are not a customer-repository benchmark or a guarantee across models.
Source and differentiation
Created by the original author as an expanded adaptation of scan-debt from the public MIT-licensed project: https://github.com/lhermoso/claude-workflows . The added value is the evidence and prioritization method, false-positive handling, self-contained references and evaluated examples. Issue Pipeline and Drain Issues are not required.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Code Quality & Review.
Bounded static triage, not an exhaustive audit or security certification. Model judgment can miss or misclassify issues. No measured coverage or performance claims. Current vulnerability databases are not checked in the default offline pass. Two synthetic agent trials do not establish accuracy on customer repositories or compatibility with every host/model. Read-only behavior depends on the agent and host permissions; tests, writes, fixes and remote actions are opt-in.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 26 days ago
- Software
Python
Permissions
Read only the user-selected project or supplied excerpts. Native file/search tools suffice; optional Git/shell equivalents are read-only. Default: no network, code execution, writes or issue creation. Those additional actions require opt-in scope and host permissions. Read-only is an instruction, not an OS sandbox. Avoid secrets and generated/vendor content; never report credential values.