Skip to content

Diagnose Legacy Codebase

ContributorsPaul Atkins

When to use: Starting modernization, de-risking migration, or preparing technical strategy for a legacy or large unfamiliar codebase.

Instructions

1. Clarify intent first

Before deep exploration, ask the user what they care about most:

  • Focused interest — specific themes (e.g. delivery risk, dependency debt, testability, architecture boundaries, ops/CI, data platform practices), or
  • Open exploration — a general understanding of the codebase with no particular agenda.

Record the answer and use it to weight depth, related skills, and findings.

2. Match library skills and diagnostic prompts

Scan this library for diagnose-phase skills and diagnostic prompts that fit the codebase under investigation (stack, domain, and stated intent). Prefer:

  • library/skills/*/SKILL.md with phase including diagnose
  • skill-local prompts under library/skills/*/references/ (e.g. *-prompt.md, diagnostic-prompt.md, review-prompt.md)
  • related diagnose use cases under library/use-cases/diagnose/ for outcome shape

Propose which ones to run (or fold into this pass) and why they fit. Do not invent coverage that a more specific skill already owns — reuse or invoke it.

Especially useful for a legacy / unfamiliar codebase view:

  • control-adoption — dual-direction read of which library deterministic controls are already present vs what the repo does better that should be backported; matrix + run-log give a durable adoption baseline.
  • update-plan-from-evidence — once findings exist (or a prior plan is in play), rework sequencing and risk from the new evidence rather than freezing the first diagnosis.

Suggest these explicitly when the user wants a control/practice baseline or when diagnosis is feeding (or revising) a modernization plan.

3. Ask about other available diagnostics

Ask the user whether any other skills, prompts, or checklists are available to the agent outside this library (IDE/agent skills, org playbooks, engagement prompts, prior review templates). If they name any, suggest using those as well when they fit the codebase and intent.

4. Produce the diagnosis

Use the matched prompts, templates, and any agreed extra diagnostics to produce:

  • repository overview
  • adoption baseline by practice
  • findings by area with evidence
  • prioritized actions
  • progress delta against previous review (when a prior review exists)

References

Troubleshooting

Symptom Likely cause Fix
Generic findings only Skipped library skill/prompt match Re-scan diagnose skills and prompts; run the best-fit ones
Wrong depth or noise Intent not clarified Re-ask focused interest vs open exploration; re-weight the pass
Missed specialist coverage Only used this skill Ask again for non-library skills/prompts available to the agent