Hire an AI code maintenance reviewer

Everything it can hand back

Your task sets the actual outputs. The specialist picks the methods that cover them.

• New, gone and still-open debt against last month, with the counts
• A check of each fix you agreed to last time, marked done, did not work or not started
• Up to five fixes to approve, each cut into small reviewable steps
• A design cause, when many items share one area

How it does the job well

• Read the existing code, its conventions and its tests before changing anything. Match the project's patterns.
• Make the smallest change that fully solves the request. Keep unrelated refactors out.
• Reproduce a bug before fixing it, and add a test that fails without the fix.
• Treat input from users, files and networks as untrusted. Validate it at the boundary.

Mistakes it avoids

• Calling debt "high" without a count or a cost beside it.
• Picking fixes because they are easy to do. Pick them because they cost the team the most.
• Planning a big rewrite. Keep each fix small enough to review alone.
• Scoring new code against old standards the team never agreed to.
• Claiming code works without running it or its tests.
• Inventing APIs, package versions or settings instead of checking the installed ones.

What a good result looks like

An example, not your task: You work in a codebase that gets slower to change each quarter.

• This month in one line. Counts of items that are new, gone and still open, against last month.
• Last month's fixes. Each agreed fix marked done, did not work or not started, with item counts before and now.
• Fixes to approve. Up to five fixes with items, size, who knows the code and a first reviewable step.
• Design cause. The shared cause when three or more top items sit in one area, or none found.
• Left for later. The rest of the ranked list, one line each.
• Files and missing. Each step's saved file, then every MISSING line in one list.

How the work is checked

• Every count is shown with the two snapshots it came from.
• Every fix on the list has a first step that one person can review in a short sitting.
• No fix repeats an approach that did not work last month.
• The list fits the time the team said it has.
• States which checks passed, failed or could not run, and names missing inputs.

These checks have not been run against a model yet. Your AI uses them to check its own work.

A second opinion

Before it hands back, your AI reviews the draft the way Kent Beck and Linus Torvalds would. This is a way of reviewing the work. It does not mean they wrote or endorse it.

Capabilities

• Scan the code. Finds debt, scores each item and saves a dated list.
• Compare with last month. Counts what is new, gone and still open, by area.
• Check last month's clean-up. For each agreed fix, did its items leave the list? A fix that did not work is not picked again the same way.
• Rank by cost. Orders open items by what they cost in slowed work, bugs and risk, and fits the list to your time.
• Look for the cause. If one person alone knows the code, it checks ownership. If three or more items share an area, it looks for the design cause.
• Split each fix. Cuts every chosen fix into tidy-up steps small enough to review alone, then stops for your yes.

How the role works

1. Checks your task, context and available tools.
2. Picks the methods needed and prepares a work plan.
3. Carries out supported tasks, with each method's limits and review gates.
4. Checks the real deliverables and corrects supported faults.
5. Hands back files, evidence and unresolved gaps.

Your specialist's working setup

Download the base specialist without a task form or account. README.md and SETUP.md explain how to use the folder. SOUL.md defines its scope. INTAKE.md asks missing questions inside your AI. PLAYBOOK.md, SKILLS.md, BEST_PRACTICES.md, CHECKS.md and HANDOFF.md guide the work and its checked deliverables.

Complete associated skills, supporting files and licences are included. Choose only the methods needed for the actual task. Keep context, working files and accepted feedback in your AI project.

Use this specialist through MCP or the API

Call prepare_specialist with role_id monthly-tech-debt-keeper only. No task is required to load it. Your AI asks what job you need done, what you want back and which relevant context it can use.

For task-led hiring, call find_specialist, explain the suggested specialists and let the user accept or change the team.

Complete ZIP: Download base specialist. API: GET /api/v1/specialists/monthly-tech-debt-keeper/pack. The host AI supplies its own model, tools and execution; a pack does not connect accounts or run a task.

Inputs and helpful context

The specialist starts from the task brief. Only active methods require their inputs.

For the primary method, when used

• The code, as a folder or repo the AI can open
• How many people work on it and how many days a month can go to clean-up (optional)
• The parts that hurt most (optional)
• Last month's folder, after the first run

Helpful context (optional)

• A list of the bugs or outages from the last month and the files they touched
• The tickets your team closed last month

Tools and access

• Claude Code: It can open the code, keep the debt folder. You start each run. It does not run on a timer. Claude Code is a paid tool (a paid plan or an API key), and you should check whether your plan allows a scheduled run.
• Any good chat AI: Labelling edits and ordering steps is text work any strong chat AI does.
• Your version control tool: Each step maps to one save point you can review and undo.

Functions and deliverables

• Code maintenance reviewer: Track code maintenance problems across reviews. Get a few high-value fixes sized to your team’s available time.
  • New, gone and still-open debt against last month, with the counts
  • A check of each fix you agreed to last time, marked done, did not work or not started
  • Up to five fixes to approve, each cut into small reviewable steps
  • A design cause, when many items share one area
• Code maintenance issue tracker: Provide codebase access and Python. Scripts scan debt signals, rank fixes against capacity and compare saved scan results.
  • A debt inventory with severity scores
  • A prioritised clean-up order
  • Summary counts by type
  • A trend dashboard over time
  Source: Alireza Rezvani.
• Tech debt prioritiser: Share repository code and change history. Get ranked debt items with impact, cost and bounded fixes.
  • A ranked debt list
  • Cost and effort per item
  • Quick wins marked
  • A staged fix plan
  Source: sickn33.
• Code ownership analyst: Share a git repo. Get who owns the sensitive code and where one person is the only owner.
  • A map of which people changed which files
  • Flags on sensitive files that only one person owns
  • Sensitive files nobody has touched in a long time
  • Groups of files that change together
  • Files you can load into graph tools such as Neo4j or Gephi
  Source: OpenAI.
• Codebase architecture reviewer: Share your code. Get an HTML report of design improvements, then work through the one you pick.
  • An HTML report of design opportunities
  • Reasons for each
  • A short list ranked by payoff
  • A guided walkthrough of the one you choose
  Source: Matt Pocock.
• Process and behavior change planner: Split a messy change into small tidy-up steps and new-behaviour steps, so each one is easy to review and undo. Paste your diff or edit list.
  • Every edit labelled as structure or behaviour, with how easy it is to undo
  • A set of small tidy-up steps and a set of behaviour steps
  • Which tidy-ups help the behaviour change, and which are optional
  • The order, with when to run tests
• AI project context organiser: Share your project and next task. Get a short rules file, a focused file list and a clear handoff for later sessions.
  • A ready rules file for your project
  • A list of which files to load for each task
  • Rules for when to reset or trim the session
  • A checklist for spotting drifting answers
  Source: Addy Osmani.
• Kent Beck: Plan a software change using Kent Beck’s recorded approach. List the cases, take small steps and keep code tidying separate from new behaviour.
  • Your problem worked on the way Kent Beck would: their questions, their method, their push-back
  • The answer or the work, in Kent Beck's voice, using their ideas by name
  • Anything that goes beyond their public record, marked
  • One suggested next step
• Linus Torvalds: Review a code change using Linus Torvalds’s recorded approach. Ask what works, what breaks for existing users and who owns the fix.
  • Your problem worked on the way Linus Torvalds would: their questions, their method, their push-back
  • The answer or the work, in Linus Torvalds's voice, using their ideas by name
  • Anything that goes beyond their public record, marked
  • One suggested next step

Tasks you can use it for

• You work in a codebase that gets slower to change each quarter.
• You agree clean-up work in planning but never see whether it helped.
• One person is the only one who understands a part of the code.

Limits to check before starting

• You want a first look at code you have never seen: ask a developer for a one-off code review instead.
• You are chasing one bug: debug that bug by itself, or ask a developer to pair with you on it.
• You want the AI to change your code on its own: this agent only suggests fixes and waits for your yes.

Best way to use this role

Give it one clear outcome, the actual files and a definition of done. Keep the work in one AI project so it can reuse checked context and earlier files.

• Start a chat with the agent. In Claude Code, add it as a skill or save it in .claude/agents, then ask it to run this month's check.
• Open it in the folder with your code. The first run builds the base list.
• Read the fixes. Say yes to the ones you want, and it records them for next month.
• Make the fixes in your normal way, or say yes to one and let it make only that change on its own branch.
• Run it again next month. It checks whether the fixes worked.

Read it as data

Read the complete role setup as JSON. Connect your AI to the AI Blocks MCP library and read aiblocks://roles/monthly-tech-debt-keeper for its role instructions and pinned sources.

This is a prepared AI role. No task has run. Your AI carries out authorized work using its available tools and reports the actual deliverables and checks.