Stage 01 — Read the machine: explain before you touch

You will produce: no code changes — a written explanation of the timing pipeline and answers to a probe battery, kept in your project notes. Reading unfamiliar code is the skill; AI will hand you a lot of it in your career. Warm-up (from the farming project, if you've started it):

1. Definition vs runtime state — one sentence each.
2. Why does physics-adjacent code live in _physics_process?

Why this exists#

You can't audit what you can't narrate. This codebase's heart is ~40 lines in scripts/globals/conductor.gd that compensate for a chain of real-world delays between "the engine queued audio" and "you heard it." Every term exists for a physical reason — and one line exists for a reason that isn't in this repo at all.

Do it#

A — The conductor, line by line#

Open conductor.gd. In your own words, write down what each of these contributes to _song_time() and what would go wrong without it:

1. player.get_playback_position() — what clock is this, and how often does it update?
2. AudioServer.get_time_since_last_mix() — what gap does adding this close? (The official sync tutorial is the source; read it after forming a guess.)
3. - _output_latency — delete this term mentally: which direction do all judgments skew, and does the display skew with them?
4. - first_beat_offset_ms / 1000.0 — whose problem does this solve: the engine's or the song file's?
5. The odd one: if mix > 1.0: mix = 0.0. Nothing in this repo explains it. The official demo (rhythm_game/game_state/conductor.gd) does — find the comment, and note which platform it protects.

B — Trace one note's life#

From song_1.tres to queue_free(): write the path a single note travels — which file loads it, which spawns it, what moves it every frame, who judges it, what kills it. One paragraph, no code open while writing (open it to check afterwards).

Two structural questions to answer along the way:

• note.gd recomputes position from the current beat every frame instead of position.y += speed * delta. What bug does the second version accumulate that the first cannot?
• game_controller.gd's _on_note_manager_judged is connected in no .gd file. Where does that connection live, and what silently breaks if you rename the method only in the script?

C — The two latencies#

first_beat_offset_ms, _output_latency, and input_latency_ms (in note_manager.gd) compensate three different delays. Make a three-row table in your notes: what physical delay, what it shifts (display, judgment, or both), where it lives.

Checkpoint — definition of done#

• The five term explanations, the note-life paragraph, and the latency table are written down, dated
• You found the web-platform comment in the official demo
• You can answer cold: why does note movement stay in sync even after a lag spike?

Before the hunt: put the notes away for a day, then re-answer question 3 from nothing. Stage 02 assumes this map is right — make sure it survived the night.

If you get stuck#

• The formula won't gel → play the game with headphones, then with Bluetooth audio if you have it; hearing latency change makes the terms real.
• Can't find the editor-side connection → the Node dock's Signals tab shows connections the code never mentions; so does opening game.tscn as text.