LegacyLens

The problem Developers spend up to 58% of their time understanding code rather than writing it (Xia et al., IEEE TSE 2018: 79 professional developers, 3,244 working hours). For a new developer on a legacy codebase, that cost peaks. Documentation drifts: Skateshop, the open source Next.js store we used, says in its README that its database is PlanetScale, but the code runs PostgreSQL. AI assistants can explain any file, but they can also cite paths and line numbers that do not exist. And nothing tells a newcomer, or their team lead, when they understand enough to change code safely. The result is slow ramp up, heavy senior hand holding and risky first contributions. Our solution LegacyLens is a verified onboarding system with three parts. 1. Analysis, done once in IBM Bob. Bob analyses the target repository and writes an onboarding pack: six JSON files covering overview, architecture, workflows, reading order, a knowledge check and first task candidates. Every claim is marked observed or inferred and cites file paths with line ranges. 2. A verification gate. A script checks every citation against the pinned commit before the app is built. For Skateshop, 212 of 212 citations resolve. When a citation failed, we fixed the evidence, never the check. 3. The LegacyLens web app, which renders only the verified pack. It never reads or runs the target code and needs no secrets. Target users: developers joining an unfamiliar or legacy codebase, and the leads and maintainers who onboard them. How they use it The developer moves through four phases. Understand: an overview and an interactive architecture map (6 layers, 8 dependencies). Trace: 5 critical workflows, 36 steps, each opening the exact code. Prove: a 9 step reading path and a 10 question knowledge check. A wrong answer does not reveal the right one; it points to the reading step to review, and retry unlocks only after that review. Change: at 80% readiness the first safe task unlocks, showing the one file to change, why it is low risk, the checks to run and a rollback command. Readiness is a visible formula, not an AI guess: 30% reading, 50% knowledge check, 20% workflows traced. Why it is new Most AI code tools help you explore. LegacyLens treats AI output as claims to verify, and treats the developer's understanding as something to prove before they touch code. Every claim opens a GitHub permalink at the analysed commit. Proof on real code We ran the full loop on Skateshop: using Bob, we fixed payment status badges that built invalid Tailwind classes (bg-600-red became bg-red-600). Typecheck, lint (0 errors, the 52 existing warnings unchanged), format and a Tailwind CSS check all passed, and Bob's code review confirmed the fix. Skateshop has no test suite, so we claim no tests. Today LegacyLens ships a verified Skateshop pack; the schema is generic, so the same Bob mode can onboard other repositories.