The Lesson Standard

Every lesson in this repository conforms to this specification. python3 -m tools.lesson_lint mechanically enforces directory layout, heading order, runnable examples, and solution test parity.

1. Directory Shape

Every executable lesson folder (NN-slug/) contains:

NN-slug/
├── README.md                 # Complete lesson text
├── examples/
│   ├── 01_<name>.py          # Runnable demonstration script
│   └── 02_<name>.py          # Demonstrates a common failure/trap (runs cleanly and prints the diagnostic)
├── exercises.py              # Starter code with 5 exercise rungs (learner edits this)
├── test_exercises.py         # Automated test suite (runs against exercises.py)
└── solution/
    ├── exercises.py          # Complete, verified solution passing test_exercises.py
    └── SOLUTION.md           # Trade-off analysis, complexity proof & interview answers

2. Required Headings in README.md (In Exact Order)

Every lesson README.md must contain these exact nine H2 headings in this order:

#Required HeadingPurpose
1## At a glance3 capability bullets starting with action verbs, time estimate, and prerequisite links
2## Reading CompanionExact book title, chapter, and focus points for deeper study
3## Why this matters in productionReal-world failure mode when engineers misunderstand this concept
4## Deep diveExhaustive, first-principles architectural explanation assuming ~10% prior recall, with detailed ASCII architecture diagrams, kernel/runtime mechanics, memory layout proofs, and step-by-step traces
5## Hands onStep-by-step instructions to execute the scripts in examples/ and what to observe
6## AI Trap & Code ReviewRealistic snippet of broken AI-generated code, why it fails in production, and how to review it
7## ExercisesSpecification for the 5-rung ladder in exercises.py (Rung 1 through Rung 5)
8## Wrapping up### Can you explain? self-check interview prompts and forward links
9## Further Reading & ReferencesVerified external links: official Python/Linux documentation, standard RFCs, PEPs, and engineering blog case studies (Netflix TechBlog, Cloudflare, Uber Eng, Meta)

3. The 5-Rung Exercise Ladder

Every exercises.py is structured into 5 progressive rungs:

  1. Rung 1 — Warm-up: Verify foundational syntax and data flow.
  2. Rung 2 — Fix the AI Bug: A pre-written function with a subtle bug (memory leak, race condition, edge-case crash, $O(n^2)$ trap) that the learner must diagnose and repair.
  3. Rung 3 — Implement: Build a clean, well-typed component from docstring specifications.
  4. Rung 4 — Refactor / Compose: Combine components or refactor procedural code into a maintainable abstraction.
  5. Rung 5 — Production Edge-Case: Harden the implementation against malformed inputs, partial failures, resource exhaustion, or concurrency edge cases.

4. Verification Rule

python3 -m tools.lesson_lint verifies that: