tech-debt

## Phase 1: Parse Subcommand Determine the mode from the argument: - `scan` — Scan the codebase for tech debt indicators - `add` — Add a new tech debt entry manually - `prioritize` — Re-prioritize the existing debt register - `report` — Generate a summary report of current debt status If no subcommand is provided, output usage and stop. Verdict: **FAIL** — missing required subcommand. If no subcommand is provided, ask the user with a concise plain-text choice list instead of failing: > "Which tech-debt workflow do you want?" > `[A] scan — inspect the codebase for debt indicators` > `[B] add — record a debt item manually` > `[C] prioritize — re-rank the debt register` > `[D] report — summarize the current register` > `[E] Stop here` > > Stop after asking. Do not continue until the user answers. --- ## Phase 2A: Scan Mode Search the codebase for debt indicators: - `TODO` comments (count and categorize) - `FIXME` comments (these are bugs disguised as debt) - `HACK` comments (workarounds that need proper solutions) - `@deprecated` markers - Duplicated code blocks (similar patterns in multiple files) - Files over 500 lines (potential god objects) - Functions over 50 lines (potential complexity) Categorize each finding: - **Architecture Debt**: Wrong abstractions, missing patterns, coupling issues - **Code Quality Debt**: Duplication, complexity, naming, missing types - **Test Debt**: Missing tests, flaky tests, untested edge cases - **Documentation Debt**: Missing docs, outdated docs, undocumented APIs - **Dependency Debt**: Outdated packages, deprecated APIs, version conflicts - **Performance Debt**: Known slow paths, unoptimized queries, memory issues Present the findings to the user. Ask: "May I write these findings to `docs/tech-debt-register.md`?" If yes, update the register (append new entries, do not overwrite existing ones). Verdict: **COMPLETE** — scan findings written to register. If no, stop here. Verdict: **BLOCKED** — user declined write. --- ## Phase 2B: Add Mode Prompt for: description, category, affected files, estimated fix effort, impact if left unfixed. Present the new entry to the user. Ask: "May I append this entry to `docs/tech-debt-register.md`?" If yes, append the entry. Verdict: **COMPLETE** — entry added to register. If no, stop here. Verdict: **BLOCKED** — user declined write. --- ## Phase 2C: Prioritize Mode Read the debt register at `docs/tech-debt-register.md`. Score each item by: `(impact_if_unfixed × frequency_of_encounter) / fix_effort` Re-sort the register by priority score and recommend which items to include in the next sprint. Present the re-prioritized register to the user. Ask: "May I write the re-prioritized register back to `docs/tech-debt-register.md`?" If yes, write the updated file. Verdict: **COMPLETE** — register re-prioritized and saved. If no, stop here. Verdict: **BLOCKED** — user declined write. --- ## Phase 2D: Report Mode Read the debt register. Generate summary statistics: - Total items by category - Total estimated fix effort - Items added vs resolved since last report - Trending direction (growing / stable / shrinking) Flag any items that have been in the register for more than 3 sprints. Output the report to the user. This mode is read-only — no files are written. Verdict: **COMPLETE** — debt report generated. --- ## Phase 3: Next Steps - Run `$sprint-plan` to schedule high-priority debt items into the next sprint. - Run `$tech-debt report` at the start of each sprint to track debt trends over time. ### Debt Register Format ```markdown ## Technical Debt Register Last updated: [Date] Total items: [N] | Estimated total effort: [T-shirt sizes summed] | ID | Category | Description | Files | Effort | Impact | Priority | Added | Sprint | |----|----------|-------------|-------|--------|--------|----------|-------|--------| | TD-001 | [Cat] | [Description] | [files] | [S/M/L/XL] | [Low/Med/High/Critical] | [Score] | [Date] | [Sprint to fix or "Backlog"] | ``` ### Rules - Tech debt is not inherently bad — it is a tool. The register tracks conscious decisions. - Every debt entry must explain WHY it was accepted (deadline, prototype, missing info) - "Scan" should run at least once per sprint to catch new debt - Items older than 3 sprints without action should either be fixed or consciously accepted with a documented reason