# Course guide — the path, the pacing, the point

Five investigations, each building on the last. The verb this course keeps
using is **predict**: every exercise asks you to write down what you expect
*before* running anything, because a prediction you committed to is what
turns an output into a lesson.

## Arc

| # | Exercise | The question it answers | Time |
|---|---|---|---|
| 01 | First message | Is Kafka a queue? What does reading move? | ~30 min |
| 02 | Keys and partitions | Where do my records land, and what exactly is ordered? | ~45 min |
| 03 | Consumer groups | Who gets which partition, and what happens when members come and go? | ~45 min |
| 04 | Retries and the dead-letter topic | What happens to the *healthy* records when one record keeps failing? | ~60 min |
| 05 | Capstone: the order investigation | Put it all together on a real Spring app and explain every line of evidence | ~60 min |

**Total: ~4–5 hours.** Suggested pacing: 01–03 in one sitting (they share
one mental model), then a break, then 04–05 (they share the Spring app).
One exercise per evening works too — each is self-contained once the cluster
is up.

## How each exercise is built

Every exercise file has the same skeleton, in this order:

1. **Goal and time** — what you will be able to do afterwards.
2. **Prerequisites** — earlier exercises, running services.
3. **The situation** — a short, realistic problem framing.
4. **Predict first** — questions to answer *in writing* before any command.
5. **The experiment** — exact commands, all from the `kafka-lab` directory,
   each with the working directory stated.
6. **Expected observations** — what you should see, stated before you run
   (so you can catch surprises, not just confirmations).
7. **Understanding checks** — questions whose answers are in *your* output.
8. **Hints** — nudges that point without revealing.
9. **Troubleshooting pointers** — section references into
   `TROUBLESHOOTING.md`.
10. **Verification** — the command(s) that prove you did it.
11. **Solution link** — `../solutions/NN-….md`, to open only after your
    attempt.

## The discipline the course is really teaching

Exercises 01–04 each contain one moment where the obvious answer is wrong:

- Reading a record does not consume it (01).
- `--from-beginning` does not beat a committed offset (01).
- A small unkeyed burst can land entirely on **one** partition (02–03:
  Kafka's sticky partitioner).
- A committed offset is not a receipt: a consumer that dies between "work
  done" and "offset committed" replays the work (03–04).

These are the moments that cost teams outages in production. The habit that
saves you is in the capstone and in the agent guide: **read the evidence
(logs, group describes, DLT headers) before touching a config value.**

## Outcomes, mapped to exercises

| You will be able to… | Where |
|---|---|
| Explain topics, partitions, keys, offsets | 01, 02 |
| Produce and consume with Java | 02, 03 (the `lab.ProducerLesson` / `lab.ConsumerLesson` runs) |
| Explain group assignment and rebalances | 03 |
| Diagnose duplicate delivery; the role of idempotency | 03, 04, 05 |
| Configure/observe Spring Kafka retries + DLT (blocking and non-blocking) | 04, 05 |
| Gather evidence before changing configuration | every exercise, graded in 05 |

## If you get stuck

- Re-read the exercise's **Hints** section before the solution.
- Use `agent-guide/PROMPTS.md` with any capable coding agent (it gives you
  the copy-paste prompt that gets a hint, not the answer).
- `TROUBLESHOOTING.md` covers the connection, port, and version errors
  learners actually hit with this stack.
