Lab 01 · Legacy Comprehension Sprint

The deliverables are an architecture brief, a dependency map, and a "danger list" of things that would bite anyone changing the code. This is the highest-confidence AI win in the 2025 Stack Overflow survey ("explaining unfamiliar code"), and it is the exact ramp-up skill services engineers need every time a new client codebase lands on their desk.

Time & tier

~90 minutes hands-on · Core track, Foundation difficulty.

Setup

No hosted repo exists — you generate the scaffold yourself, then deliberately forget how it was made. Use any capable chat model (Copilot Free chat, Gemini, Claude free tier) in Session A to generate; do the lab in a fresh Session B so the lab session has no memory of the generation.

Paste this into Session A:

Generate a deliberately gnarly but runnable Python order-fulfilment service
(~3,000 lines across 10-14 files, standard library only, no framework).
It must contain, without any marking comments: (1) one module whose name
misleads about what it does; (2) one function with a hidden side effect
(mutates state or writes a file); (3) one dead module nothing imports;
(4) two modules with a hidden circular-ish dependency resolved by a
late import; (5) global mutable state shared across at least 3 modules;
(6) one config value read in two places with different defaults.
Include a `main.py` that runs one happy-path order end to end and prints
a receipt. Also write TRAPS.md documenting exactly where each of the six
hazards lives (file, line, one-line explanation). Output each file in a
separate fenced block with its path as the first comment line.

Save every file. Do not read TRAPS.md. Verification checklist for the scaffold (run before starting):

• •
  find . -name "*.py" | wc -l returns 10–14; wc -l **/*.py totals 2,000+.
• •
  python main.py runs and prints a receipt (fix trivial syntax errors in Session A if not).
• •
  grep -c "^" TRAPS.md returns a number ≥ 12 (six entries exist) — counted, not read.
• •
  No file contains the words "trap", "bug", or "deliberately" (grep -ril trap --include="*.py" . is empty). If not, have Session A strip them.

Guided steps

1. 1Open Session B (Copilot Chat with the folder open, Windsurf, or Gemini Code Assist). Set the ground rule in your first message: "You are in read-only mode. Do not propose edits. Do not open TRAPS.md under any circumstances."
2. 2First pass — structure. Prompt: "Walk this repository top-down. For each file: one sentence on its responsibility, its imports, and what imports it. Flag anything where the name and the behaviour disagree." Take notes; do not accept the summary — spot-check two claims by opening the files yourself.
3. 3Dependency map. Prompt: "Produce a text dependency graph (A -> B per line) of these modules, including any imports that happen inside functions rather than at the top of the file, and mark those separately." Decision point: if the AI reports no late imports, it has missed hazard 4 — push with "search every function body for import statements."
4. 4State and side effects. Prompt: "List every piece of module-level mutable state, every function that mutates state it doesn't own, and every function that touches the filesystem or environment. Cite file and line for each claim." Verify each citation by reading the cited lines.
5. 5Config audit. Prompt: "Find every place a configuration value or environment variable is read. Group by key. Flag any key read in more than one place, especially with different defaults."
6. 6Write the artifacts yourself (AI may critique, not draft): a one-page architecture brief (what the service does, the 3–4 core flows, where the seams are), the dependency map from step 3, and a danger list — at least six entries, each with file:line evidence and one sentence on what a careless change would break.
7. 7Self-quiz before the reveal. Answer in writing: Which module is dead code? Which module name lies? What breaks if main.py runs twice? Which config key is double-read and which default wins at runtime?

Verification

• •
  Open TRAPS.md only now. Score your danger list: 1 point per seeded hazard you identified with correct location. Pass = 5/6 or better.
• •
  Your dependency map includes the late-import edge, marked as such.
• •
  Two of your brief's claims were verified against source during the lab (your notes show the file:line checks).
• •
  Your self-quiz answers match TRAPS.md for the dead module and the misleading name.

Completion artifact

Keep one file, legacy-brief.md, containing the brief, dependency map, danger list, quiz answers, and your TRAPS.md score. Self-grading rubric:

• Coverage (0–2): found ≤3 hazards = 0; 4–5 = 1; all 6 = 2.
• Evidence (0–2): every danger-list entry cites file:line = 2; some uncited = 1; mostly uncited = 0.
• Accuracy (0–2): no claim in the brief contradicted by TRAPS.md or source = 2.
• Verification discipline (0–2): you can point to ≥4 AI claims you independently checked = 2.
• Usefulness (0–2): a teammate could make a safe first change using only your brief = 2.

Pass = 7/10.

Stuck?

• The AI summarises confidently but wrongly. Normal. Ask for citations on every claim and check them; a claim without a line number is treated as false.
• The scaffold is too clean (no hazards found because none exist). Your generation run under-delivered — re-run Session A's prompt and re-verify the checklist rather than lowering the bar.
• Context limits on free tiers. Feed the repo in 3–4 file batches, then ask for a merged model: "Here is your earlier summary of batch 1; reconcile it with these files."

Client-safe variant

On a client codebase where code may not leave the machine: use the client-sanctioned assistant only (Copilot Business with no-training flag, or Bedrock/Azure OpenAI in the client tenancy); if none exists, run a local model (Ollama + a Qwen-Coder-class model) — local models are genuinely adequate for comprehension even where they lag at agentic edits. Never paste client code into a personal free-tier chat. The artifact format is identical; the danger list becomes your ramp-up gift to the next engineer on the account.

Answer key (don't read before attempting)

There is no fixed key for this lab — your key is the TRAPS.md the generator wrote, which is why you must not read it until Verification. If TRAPS.md turns out to be inaccurate (the generator documented a hazard that isn't really in the code), score that hazard in your favour if your brief describes the code's actual behaviour correctly — the source is the ground truth, and noticing that documentation lies about code is itself the senior-engineer skill this lab trains.