Template
GitHub issue roadmap template from a codebase audit
A codebase audit becomes useful when the findings enter the same planning system as feature work. This template turns a repo audit into issues, milestones, and roadmap fields a team can actually manage.
Section 1
Triage findings before creating issues
Do not create one issue for every scanner warning. Group findings into work that has a clear owner, acceptance criteria, and reason to exist.
- Critical: security, data loss, auth, billing, or broken deploy risk
- High: missing tests around core flows, vulnerable dependencies, brittle boundaries
- Medium: duplication, oversized files, dead code, docs drift
- Low: style cleanup and non-blocking improvements
Section 2
Issue format
Every issue should preserve the evidence from the audit and define what completion means.
- Problem statement in one or two sentences
- Affected files, routes, modules, or dependencies
- Impact and risk if ignored
- Acceptance criteria and suggested verification command
Section 3
Project fields
Use project metadata to make cleanup tradeoffs visible beside product work.
- Priority: Critical, High, Medium, Low
- Risk type: security, architecture, debt, testing, docs, dependency, operations
- Effort: small, medium, large, unknown
- Target date, milestone, iteration, and owner
Section 4
Roadmap views
A roadmap view is most useful when it shows sequencing and dependency pressure instead of becoming a decorative timeline.
- 30 days: containment issues and critical tests
- 60 days: dependency upgrades, module boundaries, CI and docs repairs
- 90 days: recurring audit loop, ownership, and maintenance budget
- Blocked view for issues waiting on credentials, product decisions, or migration windows
Section 5
Operating cadence
Keep the roadmap alive by re-scanning and closing the loop after each batch of work.
- Review roadmap status during planning, not as a separate cleanup ritual
- Open small PRs that map to individual issues
- Re-run the audit after merged fixes
- Track score movement and repeated findings over time
How to use this template
- Use this template when an audit report is ready but the work has not entered GitHub yet. It creates the bridge from findings to assignable, reviewable implementation.
- Create fewer issues than findings. Group repeated symptoms by root cause, but split work when ownership, release timing, or verification differs.
- Give every issue a verification path. If the fix cannot be tested, scanned, reviewed, or manually checked, it is not ready for a cleanup sprint.
Sources and standards
Generate this from a real repository
CodeTruss fills the report with architecture evidence, health scores, findings, and a prioritized issue roadmap.
Start free