ai-debt-detector
Skill4 starsChanged 38 days agoMITView on GitHub
Use after generating code, after accepting AI suggestions, or when reviewing AI-written modules. Also use when code works but feels brittle, when error handling seems thin, when orphaned resources or missing cleanup are suspected, or when the agent claims done but hidden debt may exist. Catches the specific failure patterns AI agents produce that humans would not.
In this repository37 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- airflow-dag-patternsSkill
- async-python-patternsSkill
- backtesting-frameworksSkill
- create-readmeSkill
- data-engineeringSkill
- data-quality-frameworksSkill
- dataset-curationSkill
- dbt-transformation-patternsSkill
- design-doc-mermaidSkill
- embedding-strategiesSkill
- eval-harness-firstSkill
- excalidraw-diagramSkill
- execution-algorithmsSkill
- external-diagram-mermaid-generateSkill
- frontend-designSkill
- hybrid-search-implementationSkill
- improve-codebase-architectureSkill
- llm-evaluationSkill
- market-regime-detectionSkill
- mcp-builderSkill
- mcp-registry-syndicationSkill
- mcprush-gateway-deploymentSkill
- mermaid-diagramsSkill
- ml-pipeline-workflowSkill
- orchestratorSkill
- postgresql-table-designSkill
- prompt-engineering-patternsSkill
- python-testing-patternsSkill
- rag-implementationSkill
- regulatory-compliance-auditSkill
- risk-metrics-calculationSkill
- security-reviewSkill
- spark-optimizationSkill
- sql-optimization-patternsSkill
- vector-index-tuningSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 9 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 4
Use after generating code, after accepting AI suggestions, or when reviewing AI-written modules.
- Distinctive: line 19
After any AI code generation session (20+ lines produced)
- Distinctive: line 20
Before merging AI-generated PRs
- Distinctive: line 21
When code works but something feels off
- Distinctive: line 22
After vibe-coding sprints where debt accumulates fastest
- Distinctive: line 23
When the agent claims done without showing verification
- Distinctive: line 27
After code generation, scan for these AI-specific debt patterns:
- Distinctive: line 43
HALLUCINATED DEPS: - Do all imports actually exist?
- Distinctive: line 58
Import from a path that doesn't exist in the project
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AI Debt Detector
Overview
AI agents generate code that passes the happy path but hides debt: missing error handling, orphaned resources, ignored failure modes, hallucinated packages, silent architectural drift. This skill forces a targeted audit for the exact patterns AI agents get wrong.
When to Use
- After any AI code generation session (20+ lines produced)
- Before merging AI-generated PRs
- When code works but something feels off
- After vibe-coding sprints where debt accumulates fastest
- When the agent claims done without showing verification
Process
After code generation, scan for these AI-specific debt patterns:
- FAILURE MODES - What happens when this fails?
- Network timeout? Disk full? Permission denied? Null input?
- Is there a try/catch? Does it catch SPECIFIC errors or swallow everything?
- Are resources cleaned up on failure? (streams closed, connections returned, temp files deleted)
- ORPHANS - What gets created but never cleaned up?
- Temp files, event listeners, intervals, subscriptions, connections
- Are there corresponding cleanup/dispose/close calls for every open/create?
- In React: does every addEventListener have a removeEventListener in cleanup?
- EDGE CASES - What inputs break this?
- Empty array/string? null/undefined? Multi-MB input? Unicode? Concurrent calls?
- Does the code assume the happy path? (AI almost always does)
- HALLUCINATED DEPS - Do all imports actually exist?
- Is every package in package.json/requirements.txt?
- Are API methods real? (AI invents plausible-sounding methods that don't exist)
- Does this library's latest version still export this function?
- ARCHITECTURAL DRIFT - Does this match the project's patterns?
- Same error handling style as existing code?
- Uses the project's established utilities (not reinventing)?
- Follows the file structure convention?
Red Flags (stop and fix immediately)
catch (e) {}orcatch (e) { console.log(e) }- swallowed error- No
finallyblock when resources were opened // TODO: handle error- AI's way of punting- Import from a path that doesn't exist in the project
- Timeout set but no abort/cleanup on timeout
- Database connection opened but never released back to pool
Common Mistakes
- Trusting that compilation means correctness (compilation checks syntax, not logic)
- Reviewing only the diff without checking what the AI did NOT generate (missing error paths)
- Assuming the AI used the right library version (it often uses deprecated APIs)
- Skipping the orphan check because garbage collection handles it (it doesn't for connections, listeners, timers)
Why This Exists
AI agents systematically optimize for "looks correct" and "passes the happy path." They miss failure modes, orphan resources, and hallucinate dependencies at rates significantly higher than manual code. This skill forces an audit for those specific blind spots.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

