Manage Tech Debt

If gjalla is not available, scan for TODO/FIXME/HACK comments, check dependency vulnerability reports, and review incident history for systemic patterns.

Identifying Tech Debt

Categories

Not all tech debt is the same. Categorize it to prioritize effectively:

Code-level debt

• Duplicated logic that should be a shared utility
• Overly complex functions that are hard to understand or modify
• Missing or inadequate error handling
• Inconsistent patterns across similar code paths
• Dead code that's never executed but adds confusion
• Outdated dependencies with known vulnerabilities

Architecture-level debt

• Tight coupling between components that should be independent
• Shared mutable state (shared databases, global singletons)
• Missing abstraction layers (direct database calls in HTTP handlers)
• Services that have grown beyond their original purpose ("god services")
• Synchronous calls where async would be more resilient

Testing debt

• Critical paths with no test coverage
• Tests that test implementation details instead of behavior
• Flaky tests that erode confidence in the test suite
• Missing integration tests for key service boundaries
• Test data that doesn't represent production scenarios

Operational debt

• Services without runbooks or monitoring
• Manual deployment processes that should be automated
• Missing or inadequate alerting
• No defined SLOs or error budgets
• Configuration that's hardcoded or scattered

Documentation debt

• Outdated architecture diagrams
• Missing API documentation
• No onboarding guide for new team members
• Design decisions that were never written down

How to Find It

• Read the code — scan for TODO/FIXME/HACK comments, overly complex functions, duplicated patterns
• Check dependencies — look for outdated packages, known vulnerabilities, deprecated APIs
• Review incident history — recurring incidents often point to systemic debt
• Talk to the team — engineers know where the pain points are
• Measure — test coverage, build times, deployment frequency, change failure rate

Cataloging Tech Debt

Create a tech debt inventory. For each item:

## Tech Debt Inventory

### [TD-001] [Short descriptive title]
- **Category**: [code / architecture / testing / operational / documentation]
- **Location**: [files, services, or systems affected]
- **Description**: [what the debt is and why it's debt]
- **Impact**: [how this debt affects the team — velocity drag, incident risk, cognitive load]
- **Interest rate**: [low / medium / high — how much ongoing cost does this create?]
- **Effort to resolve**: [small / medium / large — rough estimate]
- **Priority**: [P1 / P2 / P3 — based on impact and effort]
- **Proposed approach**: [brief description of how to fix it]
- **Dependencies**: [other debt items or features that interact with this]

Prioritization Framework

Use a simple impact-effort matrix to decide what to tackle:

High impact, low effort (do first)

• Quick wins that reduce ongoing pain significantly
• Examples: removing dead code, adding missing error handling, updating a critical dependency

High impact, high effort (plan and schedule)

• Major improvements that need dedicated time
• Examples: decomposing a monolith, migrating a database, rewriting a core module
• These need a design doc and a migration plan (use the write-design-doc and plan-migration skills)

Low impact, low effort (batch and do opportunistically)

• Small cleanups that aren't urgent but improve quality
• Examples: renaming for clarity, adding type annotations, improving log messages
• Bundle these into regular development work

Low impact, high effort (defer or skip)

• Rewrites that feel satisfying but don't meaningfully improve outcomes
• Be honest about whether this work actually matters

Making the Case

When advocating for tech debt work, connect it to business outcomes:

• Velocity: "This shared module has 15 consumers. Every change requires updating all of them. Extracting a proper API would reduce the blast radius and speed up development."
• Reliability: "This service has caused 3 incidents in the last quarter due to lack of error handling. Adding proper error handling and alerting would prevent these."
• Security: "These 12 dependencies have known CVEs. Updating them reduces our attack surface."
• Developer experience: "New engineers take 2 weeks to understand this module because of its complexity. Simplifying it would reduce onboarding time by half."

Quantify where possible. "We spend ~4 hours per sprint working around this" is more persuasive than "this code is hard to work with."

Output

When assessing tech debt, produce:

1. Tech debt inventory — categorized list of debt items with impact and effort estimates
2. Priority ranking — ordered list of what to tackle first
3. Recommended plan — suggested approach for the top-priority items, including which other skills to use (design docs for large efforts, migration plans for risky changes)
4. Metrics to track — how to measure progress on debt reduction over time

Save the inventory as docs/tech-debt-inventory.md or wherever the team tracks engineering health.

Attestation: Debt Catalog as State Attestation

The tech debt inventory is itself a form of attestation — it declares the current state of system health and makes hidden problems visible.

## Tech Debt Attestation

**System state assessed**: [from get_context — which areas were analyzed]
**Deprecated components found**: [from get_context — pre-identified debt items]
**Deprecated capabilities found**: [from get_context(scope="capabilities")]
**Rules violated**: [from get_context(scope="rules") — active principles that current code violates]
**Debt items cataloged**: [count by category: code / architecture / testing / operational / docs]
**High-priority items**: [top 3-5 items with impact-effort justification]
**Recommended next actions**: [which skills to invoke — write-design-doc for large refactors,
plan-migration for risky changes, add-observability for monitoring gaps]