Module 3: Clean Code: Mistake Clinic

This clinic turns wrong moves into reusable judgment. Use it after each practice page and again before the quiz or checkpoint.

---

Module-Specific Mistake Radar

Start with these traps. Replace or extend them with real mistakes from your own work.

Mistake to look for	Where it shows up	Symptom	Repair evidence
Finishing Diagnose Readability Debt with only a final answer	Diagnose Readability Debt	The work has no failed case, trace, test, proof gap, or design stress point.	Add the smallest broken example and show the repair that changes the result.
Finishing Refactor a Function Without Lying with only a final answer	Refactor a Function Without Lying	The work has no failed case, trace, test, proof gap, or design stress point.	Add the smallest broken example and show the repair that changes the result.
Finishing Use Tests to Unlock Design Changes with only a final answer	Use Tests to Unlock Design Changes	The work has no failed case, trace, test, proof gap, or design stress point.	Add the smallest broken example and show the repair that changes the result.
Finishing Run a Clean Code Review with only a final answer	Run a Clean Code Review	The work has no failed case, trace, test, proof gap, or design stress point.	Add the smallest broken example and show the repair that changes the result.
Treating Clean Code Is a Change Strategy as vocabulary instead of a tool	Clean Code Is a Change Strategy	The explanation names the concept but cannot decide between two cases.	Write one example, one non-example, and the rule that separates them.
Treating Names Carry Design Intent as vocabulary instead of a tool	Names Carry Design Intent	The explanation names the concept but cannot decide between two cases.	Write one example, one non-example, and the rule that separates them.

---

Practice Mistake Checks

Pull any miss from these checks into your mistake log.

Diagnose Readability Debt

Source: practice/01-diagnose-readability-debt.md

If your review notes say only "rename things" without naming the specific ambiguity, the diagnosis is too weak. If you keep comments that simply repeat the next line, you are preserving noise. If the file has no visual separation between phases of work, readability debt is probably higher than it first appears.

Refactor a Function Without Lying

Source: practice/02-refactor-a-function-without-lying.md

Do not split a function into three helpers that still depend on hidden shared state. Do not rename a function to sound pure if it still mutates data. Do not bury errors by catching everything and returning a default.

Use Tests to Unlock Design Changes

Source: practice/03-use-tests-to-unlock-design-changes.md

If changing a private helper breaks many tests, the suite may be over-coupled to structure instead of behavior. If your tests require huge setup for tiny cases, design boundaries may be wrong. If the tests are too messy to trust, they will not protect a refactor for long.

Run a Clean Code Review

Source: practice/04-run-a-clean-code-review.md

Do not fill the review with low-value style nits while ignoring responsibility and boundary problems. Do not call something "unclean" without naming the specific heuristic behind the concern. Do not recommend abstraction unless you can explain what repeated pressure it resolves.

---

Repair Protocol

For each real mistake:

1. Reproduce the failure on the smallest example, trace, proof, query, command, or design sketch.
2. Name the hidden assumption.
3. Repair the artifact.
4. Save evidence that changed: failing then passing test, corrected proof step, revised diagram, safer command, benchmark, or review note.
5. Add one retrieval card beginning with Check... before... or Do not use... when....

---

Mistake Log

Date	Mistake	Symptom	Root cause	Repair evidence	Retrieval card
Starter	Pick one radar row above	Explain how it would fail in this module	Name the assumption	Add a counterexample or corrected artifact	Write the card before closing the page

---

Completion Standard

• At least five real mistakes are logged.
• At least two mistakes include a counterexample or failing test.
• At least one mistake connects to an older semester skill.
• At least one correction changes code, a proof, a diagram, a command transcript, a query, or a design decision.