Annotate code to document technical debt, link tickets, set priorities, and auto-generate an HTML report visualizing all marked issues with priority levels and an easy-to-read summary for stakeholders.
Surfaced from shared tags and platforms — no rankings paid for.
TechDebt is a Kotlin Symbol Processing (KSP) tool designed to help developers track and visualize technical debt
directly within their codebase. By using the @TechDebt annotation, you can document technical debt, link it to
tickets, and assign priority levels. The tool then generates a comprehensive HTML report summarizing all marked
technical debt.
The primary goal of TechDebt is to make technical debt visible and manageable. Instead of letting TODOs get lost in the code, TechDebt allows you to:
TechDebt uses KSP (Kotlin Symbol Processing) to scan your source code for the @TechDebt annotation during the
compilation process. Each module generates its own local report, which is then collected and consolidated by the
TechDebt Gradle Plugin into a single, comprehensive HTML report.
In your build.gradle.kts:
plugins {
id("io.github.igorescodro.techdebt") version "<latest-version>"
}
Use the @TechDebt annotation to mark areas of technical debt:
@TechDebt(
description = "Quick fix to handle edge case, needs proper refactoring.",
ticket = "JIRA-123",
priority = Priority.HIGH
)
fun complexMethod() {
// ...
}
The annotation can be applied to:
The report is generated by the generateTechDebtReport task. Simply run:
./gradlew generateTechDebtReport
The consolidated HTML report will be generated in the root build directory:
build/reports/techdebt/consolidated-report.html
You can customize the output file path and other options in your root build.gradle.kts:
techDebtReport {
// Customize the output file path (Optional)
outputFile.set(layout.buildDirectory.file("custom/path/report.html"))
// Enable the collection of @Suppress annotations (Optional, default is false)
collectSuppress.set(true)
// Enable the collection of TODO and FIXME comments (Optional, default is false)
collectComments.set(true)
baseTicketUrl.()
enableGitMetadata.()
}
Copyright 2026 Igor Escodro
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
@Suppress("MagicNumber")) in the report.TODO and FIXME comments from your source code.LOW, MEDIUM, and HIGH priority levels (and NONE).baseTicketUrl is configured,
tickets will automatically become clickable links in the report.