assess-technical-debt

Name: assess-technical-debt
Author: tobihagemann

375stars29forks

How to install assess-technical-debt?

tobihagemann/turbo/assess-technical-debt

$npx -y skills add tobihagemann/turbo --skill assess-technical-debt

Installs into the current project.

Summary

Assess project-wide structural technical debt: complexity hotspots, deprecated API usage, duplication clusters, and architecture rot. Ranks findings by impact and refactor effort into a report at .turbo/technical-debt.md. Use when the user asks to \"assess technical debt\", \"fin

Files · 1

View on GitHub

SKILL.md

1	# Assess Technical Debt
2
3	Surface the structural debt that routine review keeps out of scope: long-lived complexity, deprecated APIs, duplication, and tangled architecture that need deliberate refactoring. Project-wide, analysis-only. Ranks each finding by impact and effort and writes `.turbo/technical-debt.md` and `.turbo/technical-debt.html`.
4
5	## Task Tracking
6
7	At the start, use `TaskCreate` to create a task for each phase:
8
9	1. Scope and partition
10	2. Run debt analysis agents
11	3. Run `/evaluate-findings` skill
12	4. Rank and write markdown report
13	5. Generate HTML report
14
15	## Step 1: Scope and Partition
16
17	If `$ARGUMENTS` specifies paths, assess those directly (skip the question).
18
19	Otherwise, use `AskUserQuestion` to confirm scope:
20
21	- All source files — assess the whole codebase
22	- Specific paths — user provides directories or file patterns
23
24	Once scope is determined:
25
26	1. Glob for source files in the selected scope. Exclude generated and vendored directories (`node_modules/`, `dist/`, `build/`, `vendor/`, `__pycache__/`, `.build/`, `DerivedData/`, `target/`, `.tox/`, and others appropriate to the project).
27	2. Partition files by top-level source directory. If a single directory holds far more files than its siblings, sub-partition it by its immediate subdirectories.
28
29	## Step 2: Run Debt Analysis Agents
30
31	Use the Agent tool to launch all agents below in a single assistant message so they run concurrently. Run them in the foreground so all their results return in this turn. Each Agent call uses `model: "opus"`. Each Agent's prompt instructs it to read [references/debt-reviewer.md](references/debt-reviewer.md) for the debt taxonomy, detection heuristics, the impact/effort rubric, and the finding output format before scanning, and to treat the shared working tree and its git index as read-only — any empirical check runs in an isolated `git worktree` the agent discards afterward.
32
33	Expect (one per partition, plus one project-wide architecture agent) Agent tool calls total. State the count explicitly when emitting the calls.
34
35	- Partition agents — one per partition from Step 1. Each scans its files for complexity hotspots, deprecated API usage, and duplication, and notes coupling it observes reaching outside the partition. Pass the partition's file list and the full project root path.
36	- Architecture agent — one project-wide pass over the scoped tree for architecture rot: tangled module boundaries, circular dependencies, layering violations, and refactor candidates that span modules. Pass the partition map and the full project root path.
37
38	If more partitions exist than fit a single fan-out, group related directories so the partition agents stay within a manageable batch, and note the grouping in the report.
39
40	## Step 3: Run `/evaluate-findings` Skill
41
42	Aggregate all findings from all agents. Deduplicate items that surface in more than one agent (e.g., duplication a partition agent and the architecture agent both flag). Run the `/evaluate-findings` skill once on the combined set to verify each finding against the actual code and weed out false positives.
43
44	## Step 4: Rank and Write Markdown Report
45
46	Assign each surviving finding an impact (maintenance drag, change risk, blast radius) and an effort (rough refactor size) per the rubric in [references/debt-reviewer.md](references/debt-reviewer.md). Sort findings into priority tiers:
47
48	- Quick wins — high impact, low effort
49	- Strategic refactors — high impact, high effort
50	- Incremental — low-to-medium impact, low effort
51	- Defer — low impact, high effort
52
53	Output the summary and priority matrix as text. Then write `.turbo/technical-debt.md` using the template below.
54
55	### Report Template
56
57	```markdown
58	# Technical Debt Assessment
59
60	Date: <date>
61	Scope: <what was assessed>
62
63	## Summary
64
65	\| Dimension \| Findings \| High impact \|
66	\|---\|---\|---\|
67	\| Complexity hotspots \| <N> \| <N> \|
68	\| Deprecated API usage \| <N> \| <N> \|
69	\| Duplication clusters \| <N> \| <N> \|
70	\| Architecture rot \| <N> \| <N> \|
71
72	## Priority Matrix
73
74	Ranked by impact against refactor effort. Take quick wins first; schedule strategic refactors deliberately.
75
76	### Quick Wins (high impact, low effort)
77	\| Item \| Dimension \| Location \| Recommended refactor \|
78	\|---\|---\|---\|---\|
79
80	### Strategic Refactors (high impact, high effort)
81	\| Item \| Dimension \| Location \| Recommended refactor \|
82	\|---\|---\|---\|---\|
83
84	### Incremental (low–medium impact, low effort)
85	\| Item \| Dimension \| Location \| Reco

People who liked this also viewed

6 picks

Type

assess-technical-debt

375stars29forks

View on GitHub

How to install assess-technical-debt?

tobihagemann/turbo/assess-technical-debt

$npx -y skills add tobihagemann/turbo --skill assess-technical-debt

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Assess Technical Debt
2
3	Surface the structural debt that routine review keeps out of scope: long-lived complexity, deprecated APIs, duplication, and tangled architecture that need deliberate refactoring. Project-wide, analysis-only. Ranks each finding by impact and effort and writes `.turbo/technical-debt.md` and `.turbo/technical-debt.html`.
4
5	## Task Tracking
6
7	At the start, use `TaskCreate` to create a task for each phase:
8
9	1. Scope and partition
10	2. Run debt analysis agents
11	3. Run `/evaluate-findings` skill
12	4. Rank and write markdown report
13	5. Generate HTML report
14
15	## Step 1: Scope and Partition
16
17	If `$ARGUMENTS` specifies paths, assess those directly (skip the question).
18
19	Otherwise, use `AskUserQuestion` to confirm scope:
20
21	- All source files — assess the whole codebase
22	- Specific paths — user provides directories or file patterns
23
24	Once scope is determined:
25
26	1. Glob for source files in the selected scope. Exclude generated and vendored directories (`node_modules/`, `dist/`, `build/`, `vendor/`, `__pycache__/`, `.build/`, `DerivedData/`, `target/`, `.tox/`, and others appropriate to the project).
27	2. Partition files by top-level source directory. If a single directory holds far more files than its siblings, sub-partition it by its immediate subdirectories.
28
29	## Step 2: Run Debt Analysis Agents
30
31	Use the Agent tool to launch all agents below in a single assistant message so they run concurrently. Run them in the foreground so all their results return in this turn. Each Agent call uses `model: "opus"`. Each Agent's prompt instructs it to read [references/debt-reviewer.md](references/debt-reviewer.md) for the debt taxonomy, detection heuristics, the impact/effort rubric, and the finding output format before scanning, and to treat the shared working tree and its git index as read-only — any empirical check runs in an isolated `git worktree` the agent discards afterward.
32
33	Expect (one per partition, plus one project-wide architecture agent) Agent tool calls total. State the count explicitly when emitting the calls.
34
35	- Partition agents — one per partition from Step 1. Each scans its files for complexity hotspots, deprecated API usage, and duplication, and notes coupling it observes reaching outside the partition. Pass the partition's file list and the full project root path.
36	- Architecture agent — one project-wide pass over the scoped tree for architecture rot: tangled module boundaries, circular dependencies, layering violations, and refactor candidates that span modules. Pass the partition map and the full project root path.
37
38	If more partitions exist than fit a single fan-out, group related directories so the partition agents stay within a manageable batch, and note the grouping in the report.
39
40	## Step 3: Run `/evaluate-findings` Skill
41
42	Aggregate all findings from all agents. Deduplicate items that surface in more than one agent (e.g., duplication a partition agent and the architecture agent both flag). Run the `/evaluate-findings` skill once on the combined set to verify each finding against the actual code and weed out false positives.
43
44	## Step 4: Rank and Write Markdown Report
45
46	Assign each surviving finding an impact (maintenance drag, change risk, blast radius) and an effort (rough refactor size) per the rubric in [references/debt-reviewer.md](references/debt-reviewer.md). Sort findings into priority tiers:
47
48	- Quick wins — high impact, low effort
49	- Strategic refactors — high impact, high effort
50	- Incremental — low-to-medium impact, low effort
51	- Defer — low impact, high effort
52
53	Output the summary and priority matrix as text. Then write `.turbo/technical-debt.md` using the template below.
54
55	### Report Template
56
57	```markdown
58	# Technical Debt Assessment
59
60	Date: <date>
61	Scope: <what was assessed>
62
63	## Summary
64
65	\| Dimension \| Findings \| High impact \|
66	\|---\|---\|---\|
67	\| Complexity hotspots \| <N> \| <N> \|
68	\| Deprecated API usage \| <N> \| <N> \|
69	\| Duplication clusters \| <N> \| <N> \|
70	\| Architecture rot \| <N> \| <N> \|
71
72	## Priority Matrix
73
74	Ranked by impact against refactor effort. Take quick wins first; schedule strategic refactors deliberately.
75
76	### Quick Wins (high impact, low effort)
77	\| Item \| Dimension \| Location \| Recommended refactor \|
78	\|---\|---\|---\|---\|
79
80	### Strategic Refactors (high impact, high effort)
81	\| Item \| Dimension \| Location \| Recommended refactor \|
82	\|---\|---\|---\|---\|
83
84	### Incremental (low–medium impact, low effort)
85	\| Item \| Dimension \| Location \| Reco

People who liked this also viewed

6 picks

Type