M4 · Lesson 3 — Reproducing Works

Building an
Implementation Plan

Before writing a single line of code — plan everything.
Surprises in implementation come from surprises in planning.

01
M4 · L3 — Why Plan First

The most common reproduction mistake

Coding before
planning wastes days

"I started implementing the model on Day 1. On Day 4 I realised the data preprocessing step the paper described in one sentence took 3 days to get right."

A good implementation plan forces you to:

  • List every equation you need to implement
  • List every hyperparameter and its search space
  • List every data preprocessing step
  • Identify missing details before hitting them mid-code
  • Estimate complexity and order of implementation
02
M4 · L3 — The Phases

Before opening your IDE

5 phases of
a good plan

Phase 01

Data

Download, preprocess, split. What format? What filtering?

Phase 02

Model

List every equation. Map each to a module or layer.

Phase 03

Training

Loss function. Optimiser. Batch size. Negative sampling. Epochs.

Phase 04

Evaluation

Which metrics? Which split? Full ranking or candidate-based?

Phase 05

Hyperparams

Which values to tune? What search space? How many runs?

Rule: You should be able to write the full plan in one sitting, before touching code. If you can't — you haven't read the paper carefully enough.

03
M4 · L3 — The Template

What a plan looks like

Implementation plan
for MF-BPR

Data
Dataset
MovieLens-1M · download from GroupLens
Split
Leave-one-out: last interaction = test, second-last = val
Threshold
⚠ r_ui ≥ 4 → implicit positive (assumption — paper unclear)
Model equations to implement
Eq. 1
ŷ_{ui} = p_u^⊤ q_i — dot product scorer
Eq. 2
ℒ_BPR = −Σ ln σ(ŷ_{ui} − ŷ_{uj}) + λ(‖P‖²+‖Q‖²) — loss
Hyperparameters
d (dims)
Search: {32, 64, 128, 256}
λ (reg)
Search: {1e-4, 1e-3, 1e-2}
α (lr)
⚠ Not specified in paper — default: 0.001 with Adam
04
M4 · L3 — Complex Model Plan

More complex — K-RagRec

The order of
implementation matters

Recommended build order for K-RagRec:

Step 1: KG loading + entity/relation encoding # PLM(x_n) → z_n, PLM(x_e) → r_e Step 2: GNN_Indexing forward pass # z^(l)_n = GNN({z^(l-1)_m, r_e}) Step 3: Vector database construction # store z_g per subgraph Step 4: Popularity filter logic # if pop(item) < p: retrieve Step 5: Retrieval + re-ranking # Eq. 5 + Eq. 6 Step 6: GNN_Encoding + MLP projector # Eq. 7 + Eq. 8 Step 7: LLM inference + cross-entropy training # Eq. 9, freeze LLM params

WHY BUILD IN THIS ORDER?

Each step depends on the previous. You can test Steps 1–3 independently of the LLM. If you start at Step 7, you can't debug anything.

Key insight

Build and test incrementally

Verify shapes and outputs at each step. A silent bug in Step 2 will corrupt everything downstream.

05
M4 · L3 — Plan Quality

What separates good plans from bad ones

Specificity is
everything

❌ Vague plan
  • Load the dataset
  • Build the model
  • Train it
  • Evaluate on the test set

This is a wish list, not a plan. No shapes, no equations, no missing details flagged.

✅ Specific plan
  • Load ML-1M · filter ratings ≥ 4 · leave-one-out split → train/val/test
  • P ∈ ℝ^{6040×d}, Q ∈ ℝ^{3952×d} · initialise N(0, 0.01)
  • BPR loss · Adam lr=0.001 · batch 1024 · 1 neg/positive
  • Recall@10, NDCG@10 on full item ranking · no candidate sampling

Specific enough that a second person could implement it independently.

06
M4 Complete — Reproducing Works

Module 4 complete

L1 · Equations → Pseudocode

Translate math to logic

Σ = loop. argmin = optimiser. ← = update. List inputs, outputs, loops, updates — in that order.

L2 · Missing Details

Find what's not written

Initialisation, negative sampling, LR schedule, preprocessing. Check appendix → code repo → cited papers → field defaults.

L3 · Implementation Plan

Plan before coding

5 phases: Data → Model → Training → Evaluation → Hyperparams. Specific enough that someone else could implement it.

Next: M5 · Mathematical Reasoning — definitions, theorems, proofs

07
← → arrow keys to navigate
1 / 7