Tech Debt Analyzer
Draft Architecture Decision Records that frame tech-debt tradeoffs, options, drivers, and chosen outcomes for the team and future you.
Overview
Tech Debt Analyzer is an agent skill most often used in Build (also Validate, Ship) that produces ADR-style decision write-ups to analyze and document technical debt tradeoffs.
Install
npx skills add https://github.com/ailabs-393/ai-labs-claude-skills --skill tech-debt-analyzerWhat is this skill?
- Full ADR skeleton: context, constraints, requirements, decision drivers, and considered options
- Per-option pros, cons, and effort estimates to compare refactor vs defer paths
- Decision outcome section with rationale and consequences for tech-debt visibility
- Status lifecycle fields: Proposed, Accepted, Deprecated, Superseded
- Links deciders, dates, and technical story/ticket references for audit trail
- ADR template with 3+ considered option sections and explicit decision outcome block
- Status workflow: Proposed, Accepted, Deprecated, Superseded
Adoption & trust: 795 installs on skills.sh; 399 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You feel mounting tech debt but lack a shared record of options, constraints, and why shortcuts were accepted.
Who is it for?
Indie teams documenting refactor-vs-defer choices, library migrations, or architectural compromises in a repeatable ADR format.
Skip if: Fully automated codebase debt scoring without human judgment, or greenfield spikes with no decision to record yet.
When should I use this skill?
When technical or architectural choices need documented options, constraints, and a chosen outcome—especially around tech debt and refactor timing.
What do I get? / Deliverables
You get a completed ADR draft with compared options, chosen decision, and rationale you can commit beside the codebase or ticket.
- ADR markdown document with decision drivers and chosen option rationale
- Traceable deciders, date, and technical story references
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Capturing why you accepted or deferred debt belongs with build-time product and engineering decisions before code hardens. The packaged content is an ADR template with options, drivers, and rationale—classic PM/architecture documentation work.
Where it fits
Compare building a new module vs patching legacy code before committing to the MVP scope.
Record why you chose a faster ORM shortcut with documented consequences and follow-up tasks.
Capture a pre-release ADR on debt you are knowingly shipping and when you will revisit it.
How it compares
Structured decision template—not a static analysis MCP server or a unit-test skill.
Common Questions / FAQ
Who is tech-debt-analyzer for?
Solo builders and tiny teams who want their agent to turn messy tech-debt debates into Architecture Decision Records with explicit options and outcomes.
When should I use tech-debt-analyzer?
Use it in Build (pm) when choosing stacks or deferring refactors; in Validate (scope) when deciding MVP depth vs quality bar; and in Ship (review) when recording pay-down plans before release.
Is tech-debt-analyzer safe to install?
It is a documentation template without intrinsic network or shell actions; review the Security Audits panel on this Prism page and ensure ADR content does not leak secrets into your repo.
SKILL.md
READMESKILL.md - Tech Debt Analyzer
# ADR-XXX: [Short Title of Decision] **Status:** [Proposed / Accepted / Deprecated / Superseded] **Date:** [YYYY-MM-DD] **Deciders:** [List of people involved in the decision] **Technical Story:** [Description, ticket/issue URL] --- ## Context and Problem Statement [Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.] **Key Constraints:** - [List any constraints that limit the solution space] **Key Requirements:** - [List must-have requirements] --- ## Decision Drivers [List the factors that influenced the decision, e.g.:] - [driver 1, e.g., performance requirement] - [driver 2, e.g., team expertise] - [driver 3, e.g., cost constraints] - [etc.] --- ## Considered Options ### Option 1: [Name] **Description:** [Brief description of this option] **Pros:** - [good, because...] - [good, because...] **Cons:** - [bad, because...] - [bad, because...] **Effort:** [Estimated effort] --- ### Option 2: [Name] **Description:** [Brief description of this option] **Pros:** - [good, because...] - [good, because...] **Cons:** - [bad, because...] - [bad, because...] **Effort:** [Estimated effort] --- ### Option 3: [Name] [Repeat structure for each option considered] --- ## Decision Outcome **Chosen option:** "[Option X: Name]" **Rationale:** [Explain why this option was chosen. What makes it the best choice given the context and decision drivers?] --- ## Consequences ### Positive Consequences - [e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...] - [...] ### Negative Consequences - [e.g., compromising quality attribute, follow-up decisions required, ...] - [...] ### Technical Debt [Any technical debt being incurred as a result of this decision? How will it be tracked?] --- ## Implementation **Action Items:** - [ ] [Implementation task 1] - [ ] [Implementation task 2] - [ ] [etc.] **Timeline:** [Expected implementation timeline] **Rollback Plan:** [How to revert this decision if needed] --- ## Validation **Success Metrics:** [How will we measure if this decision was correct?] **Review Date:** [When should we review this decision?] --- ## References - [Link to supporting documents] - [Link to related ADRs] - [Link to research/benchmarks] --- ## Notes [Any additional notes, context, or discussion points] # Technical Debt Register **Project:** [Project Name] **Last Updated:** [Date] **Maintained By:** [Team/Person] ## Summary - **Total Debt Items:** 0 - **Critical:** 0 - **High:** 0 - **Medium:** 0 - **Low:** 0 - **Estimated Total Effort:** 0 days --- ## Active Debt Items ### DEBT-001: [Brief Description] **Category:** [Code Quality / Architecture / Test / Documentation / Dependency / Performance / Security / Infrastructure / Design] **Severity:** [Critical / High / Medium / Low] **Created:** [YYYY-MM-DD] **Location:** - File(s): `path/to/file.ts` - Component/Module: [Name] **Description:** [Detailed description of the technical debt issue] **Impact:** - **Business Impact:** [How does this affect users, features, or business goals?] - **Technical Impact:** [How does this affect code quality, maintainability, or performance?] - **Risk:** [What could go wrong if left unaddressed?] **Root Cause:** [Why was this shortcut taken? Deadline pressure, lack of knowledge, evolving requirements, etc.] **Proposed Solution:** [How should this be addressed? What's the ideal fix?] **Effort Estimate:** [X hours/days] **Priority Justification:** [Why this severity level? Why fix this now vs later?] **Dependencies:** - Blocks: [List items this blocks] - Blocked By: [List items blocking this] - Related: [List related debt items] **Status:** [Open / In Progress / Resolved / Won't Fix] **Assignee:** [Name or Unassigned] **Target Resolution:** [YYYY-MM-DD or Sprint/Quarter] **Notes:** - [Any additional context, discussion, or updates] --- ### DEBT-002: [B