Tech Debt Remediation — Scoring & Format

Field	Value
Type	Agent Reference
Source	~/.copilot/agents/_refs/tech-debt-remediation-plan/metrics.md
Description	Not specified

Source Content

Tech Debt Remediation — Scoring & Format

Reference for the metric scales, the document structure, and GitHub issue conventions used by the agent.

---

Core Metrics (1–5 scale)

Ease of Remediation

How hard is the fix to implement?

Score	Meaning
1	Trivial — minutes, single-file edit
2	Small — a few hours, well-scoped
3	Moderate — 1–3 days, touches several modules
4	Hard — a week+, cross-cutting refactor
5	Complex — multi-sprint, architectural change

Impact

Effect on codebase quality / developer velocity if fixed.

Score	Icon	Meaning
1	⚪	Minimal — cosmetic improvement
2	🔵	Low — small DX or hygiene win
3	🟢	Moderate — measurable quality lift in one area
4	🟡	High — unlocks velocity across multiple teams
5	🔴	Critical — removes a systemic blocker

Risk

Consequence of leaving the debt unaddressed.

Score	Icon	Meaning
1	🟢	Negligible — no foreseeable impact
2	🟢	Low — minor friction, easy to live with
3	🟡	Medium — recurring incidents or slowdowns likely
4	🟡	High — outage / data / security risk increasing
5	🔴	Severe — failure is a matter of when, not if

Use the icon column when rendering the summary table to make priority visible at a glance.

---

Required Document Sections

Each plan returns a single Markdown document with the following sections, in order:

1. Overview — the technical debt in one paragraph.
2. Explanation — problem details and the chosen resolution approach.
3. Requirements — prerequisites for remediation (people, access, tooling, sequencing).
4. Implementation Steps — ordered, imperative action items.
5. Testing — verification methods (unit, integration, regression, perf, manual).

The summary table precedes the detailed plan.

Summary Table Columns

Item	Ease	Impact	Risk	Explanation

One row per debt item. Sort by descending priority — see scoring below.

Prioritization

Default ranking formula:

priority_score = (Impact + Risk) - (Ease - 1)

Higher score = address sooner. Break ties by Risk, then Impact. Surface the top 3 items in an executive summary.

---

Common Technical Debt Types

• Missing or incomplete test coverage.
• Outdated or missing documentation.
• Unmaintainable code structure (god objects, long methods).
• Poor modularity or excessive coupling.
• Deprecated dependencies or APIs.
• Ineffective design patterns or copy-paste duplication.
• Outstanding TODO / FIXME markers.
• Flaky tests, slow CI, or unreliable build pipelines.
• Security/compliance debt (unpatched libs, missing audit trails).

---

GitHub Issue Integration

• Search first — call search_issues before opening anything new; reference duplicates instead of recreating.
• Apply the repository’s chore_request.yml template (path: /.github/ISSUE_TEMPLATE/chore_request.yml) for remediation tasks.
• Title format: chore(tech-debt): <area> — <short summary>.
• Body must include: link to the plan section, scores (Ease/Impact/Risk), suggested owner, and acceptance criteria.
• Cross-link related issues; if the work is multi-step, file a tracking issue and child issues.
• Add labels: tech-debt, plus a domain label (area:frontend, area:backend, area:infra, etc.) and a risk label (risk:low|med|high).
• The plan document includes the resulting issue URLs in a “Tracked Issues” appendix.