Forem: Mohamed Hamed

AI Debugging: The 3-Context Framework That Closes Bugs in Minutes

Mohamed Hamed — Thu, 09 Apr 2026 19:41:56 +0000

AI Workflow · Module 5

AI Debugging

"You provide the evidence. AI generates hypotheses. You verify."

3 Pieces
3-Context Framework

4 Steps
The Debug Workflow

10×
Faster resolution

Two developers. Same AI tool. Same model. One resolves a bug in under 5 minutes. The other spends 40 minutes getting generic suggestions that miss the root cause.

The difference is not intelligence. It's not experience. It's context. The AI's debugging quality is directly proportional to the quality of context you give it. Give it a vague description and you get pattern-matched guesses. Give it the full picture and it becomes a
genuine investigation partner.

This article gives you that full picture — the three pieces of context that unlock AI debugging, the four-step workflow, and the advanced techniques for the hard ones.

Why AI Debugging Works (When Done Right)

Traditional debugging is a solo investigation: you examine the clues, form hypotheses, test them one by one. It's methodical but slow.

AI-assisted debugging transforms this into a collaborative investigation. You are the detective who understands the full case context — the codebase, the system, the history. The AI is a partner who can instantly scan every pattern it has ever seen and generate hypotheses at machine speed.

The crucial reframe: the AI is a hypothesis generator, not a fix button. You provide the crime scene evidence. The AI generates probable causes. You verify them with your engineering judgment.

When developers get poor results from AI debugging, it's almost always because they sent the equivalent of "my code is broken, fix it" — no evidence, no context, no crime scene.

The 3-Context Framework: Three Non-Negotiable Pieces

The difference between a 5-minute fix and a 40-minute struggle is almost always traceable to missing one of these three:

I: The Full Error Message + Stack Trace
Never say "I have a TypeError." Give the entire error message and the complete stack trace. This tells the AI exactly where the problem occurred and every function in the call chain that led there. Truncated stack traces hide the root cause.
❌ "I'm getting a TypeError"
✅ [paste full stack trace with file names and line numbers]

II: The Relevant Code
Reference the specific files involved — not the whole codebase, but the exact functions and modules in the call chain. The AI needs to see the code that's failing, the code that calls it, and any shared utilities it depends on.
❌ "Here's my component" [pastes 200 lines]
✅ Reference @UserProfile.tsx + @useAuth.ts + the specific function throwing

III: Expected vs. Actual Behavior
The AI doesn't know what your code was supposed to do. State it explicitly. "I expected X, but instead Y happened" gives the AI the final piece it needs — the intent — to distinguish root cause from symptom.
❌ "The component doesn't work"
✅ "Expected user.name to render. Instead, the component crashes silently."

Bonus: Add recent changes. If you changed something in the last 24 hours, mention it. Most bugs occur at the intersection of recent changes — this single detail can cut your debugging time in half.

The 4-Step AI Debugging Workflow

This isn't one prompt. It's a systematic loop.

Step 1: Provide the Full Crime Scene
Send all three pieces of the 3-Context Framework in a single structured prompt. Include recent changes. Context front-loads the analysis — the AI starts from your situation, not the average situation it has pattern-matched.

↓

Step 2: Read the Explanation, Not Just the Fix
Do not jump straight to the code suggestion. Read the AI's explanation of the root cause first. Does it make sense? Does it align with the stack trace? If the explanation is generic or vague, the AI is guessing. Ask a clarifying question before proceeding.

↓

Step 3: Critically Evaluate the Fix Before Applying
Does this fix the root cause or just suppress the symptom? Does it handle edge cases? Does it introduce new risks? Apply only after you've validated the fix with your own judgment — not just run it to see if the error goes away.

↓

Step 4: Test, Verify, and Loop if Needed
If the bug persists, don't restart from zero. Go back to Step 1 and add the results of the failed fix to the context. Each loop narrows the hypothesis space until the root cause is isolated. This edit-test loop is where AI debugging becomes genuinely powerful.

A Real Debugging Session: What This Looks Like

FRAME (what to send):

The component crashes when a user with no orders clicks "View History."

ERROR:
TypeError: Cannot read properties of undefined (reading 'length')
  at OrderHistory.tsx:47
  at renderWithHooks (react-dom.development.js:14985)
  at mountIndeterminateComponent (react-dom.development.js:17811)
  ...

RELEVANT CODE:
@components/OrderHistory.tsx (lines 40-60)
@hooks/useOrders.ts

EXPECTED BEHAVIOR:
The component should render an empty state ("No orders yet") when data is empty.

ACTUAL BEHAVIOR:
Crashes with TypeError when data is undefined (user has no order history — the API returns null, not []).

RECENT CHANGE:
Yesterday we added caching to useOrders. The cached value initializes as undefined before the first fetch.

That prompt takes 90 seconds to write. The AI now has everything it needs to identify the exact issue: the hook returns undefined while loading instead of [], and the component doesn't guard against that.

Advanced Technique: AI-Guided Strategic Logging

For bugs where the root cause is unclear, don't spray console.log randomly. Ask the AI to tell you where to look.

I can't reproduce this reliably. The bug appears only under load.
Here's the relevant code: @OrderProcessor.ts

Add strategic logging to trace the value of `order.status`
from when it enters processOrder() to when it reaches updateInventory().
I need to see the state at each transformation step.

The AI will add targeted logging that creates a diagnostic trail — without cluttering your codebase with guesswork statements.

Multi-File Debugging: When the Bug Spans the Stack

For bugs that cross multiple files:

The data is correct in the API response but incorrect when rendered.
The bug is somewhere between the API and the UI.

Here's the complete chain:
@api/orders.ts (the endpoint)
@hooks/useOrders.ts (transforms the response)
@components/OrderTable.tsx (renders the data)

I suspect the issue is in the useOrders transformation, but I'm not certain.
Trace the data shape through all three files and identify where it diverges.

By giving the AI the full chain, you let it reason about the transformation at each step — something that's difficult to do in isolation for each file.

Debugging is one of the highest-leverage places to apply AI because the investigation is precisely the kind of pattern-matching work AI does well. The limiting factor isn't the AI — it's always the context you give it.

Give it the full crime scene. You'll be surprised how fast the case closes.

Part 5 — How AI Actually Learns: The Training Loop Explained

Mohamed Hamed — Tue, 07 Apr 2026 22:55:36 +0000

The AI figured it all out by failing — and failing — and failing — until it didn't.

Nobody programmed ChatGPT to write poetry. Nobody wrote rules for how to translate between Arabic and English. Nobody told the AI what "smart glasses" means.

In the previous article we built an artificial neuron and learned that it has weights — importance multipliers that determine how much each input influences the output. The question we left open: how does the AI learn the right weights?

The answer is the Training Loop — four steps, repeated millions of times, that turn random numbers into intelligence.

The Core Idea: Learning from Mistakes

Think about how a child learns to walk. Nobody programs the angles their legs need to maintain. Nobody writes rules for balance. The child:

Tries to take a step
Falls over
Somehow figures out what went wrong
Adjusts the next attempt
Repeats — until walking becomes automatic

An AI learns exactly the same way. The only difference is speed: a neural network can "fall" and "adjust" millions of times in a few hours.

The Training Loop: 4 Steps


📸 STEP 1	📊 STEP 2	🔍 STEP 3	⚙️ STEP 4
Forward Pass	Loss	Backpropagation	Weight Update
Make a guess	Measure the mistake	Find who's responsible	Fix a little bit

🔁 Repeat millions of times

Let's go through each step with a concrete example: classifying whether a device is smart glasses or a smart ring.

Step 1: Forward Pass — Make a Guess

Data enters the network at the input layer and flows forward through every neuron until it produces an output. We call this the Forward Pass.

At the very start of training, all the weights are random. So the output is essentially a random guess.

Input: Ray-Ban image (True label: Glasses)

Prediction Confidence

👓 Glasses 60%

💍 Ring 25%

🎧 Earbuds 15%

Should be 100% Glasses. Got 60%. The network is wrong — and that's expected at the start. ✅

Prediction	Confidence
👓 Glasses	60%
💍 Ring	25%
🎧 Earbuds	15%

The network isn't "bad" for being wrong here. It starts wrong. The whole point of training is to make it less wrong, step by step.

Step 2: Loss — Measure the Mistake

"How wrong was the guess?" is the job of the Loss Function (also called the Cost Function).

The most common version is Mean Squared Error (MSE):

loss = (true_label - prediction) ** 2

If we predicted 60% glasses and the true answer is 100% glasses:

loss = (1.0 - 0.60) ** 2 = 0.40 ** 2 = 0.16

A loss of 0.16 on a scale of 0–1. High is bad. Zero is perfect.

Note: For multi-class problems (3+ categories), Cross-Entropy loss is more common than MSE — it handles probability distributions better and trains faster on classification tasks.

Loss chart — early in training (first few epochs):

Epoch 0: 0.48
Epoch 25: 0.36
Epoch 50: 0.24
Epoch 75: 0.12
Epoch 99: 0.02 ⭐

The bigger the number, the more the AI is "lost". Training drives this number toward zero.

Step 3: Backpropagation — Find Who's Responsible

This is the magic step. Once we know the total loss, we need to figure out: which weights caused the error, and by how much?

Imagine a factory with 1,000 workers. The product came out defective. How do you fix it?

❌ Blame everyone equally	✅ Ask each worker: "How much did you contribute to the defect?"
Unfair and inefficient. Workers who did nothing wrong get punished.	Adjust the biggest contributors more. Leave innocent workers alone.

Backpropagation is the mathematical version of that second approach. It uses calculus (specifically the chain rule) to calculate the exact contribution of each weight to the total loss.

Think of it like tracing a string of Christmas lights: one bulb goes out and the whole string fails. You don't replace every bulb — you trace backwards from the dead end of the string to find which single bulb broke the chain. Backpropagation does this mathematically, tracing backwards from the output error through every layer to find which weights contributed most.

The output: a number for each weight called the gradient — which tells us: "if we increase this weight by a tiny amount, how much does the loss increase or decrease?"

Step 4: Weight Update — Fix a Little Bit (Gradient Descent)

Now we know which way to adjust each weight. But how much should we adjust?

Too little: training takes forever. Too much: the network overshoots and bounces around without ever converging.

The formula for updating each weight is:

new_weight = old_weight - (learning_rate × gradient)

The Learning Rate is the key hyperparameter here. Think of it as the size of each step when walking down a hill toward the lowest point (minimum loss):

LR = 0.9 (too large)	LR = 0.0001 (too small)	LR = 0.01 (just right)
Takes giant steps, overshoots the minimum, bounces around forever	Takes tiny steps, will eventually get there — in weeks	Steady progress, reaches minimum efficiently ✅

This process of adjusting weights following the gradient is called Gradient Descent — mathematically walking downhill on the loss landscape.

The Loss Landscape — gradient descent finds the lowest valley

(Visual: A curve representing loss vs weights, showing a path from 'start' through a 'local min' down to the 'global min')

Labels: Loss, Weights, local min, global min.

The ball (your model) rolls downhill one step at a time. Learning rate = step size. Goal: reach the global minimum.

Key Training Vocabulary

Three terms appear in every AI paper and framework:

Epoch
One complete pass through the entire training dataset. If you have 10,000 images, one epoch = the network has seen all 10,000.

Batch
We don't update weights after every single example — we process a small group (e.g., 32 images) first, average the loss, then update. A batch of 32 is far more efficient than 32 individual updates.

Iteration
One batch processed = one iteration. With 1,000 images and batch size 32: ~31 iterations per epoch. After 100 epochs: 3,100 weight updates.

The Problem That Derails Training: Overfitting

Here's the trap: a network can get very good at the training data while becoming terrible at real-world data it's never seen. This is called Overfitting — the AI memorized the answers instead of learning the pattern.

This is exactly why the embedding model from Article 2 needed to train on billions of multilingual sentence pairs — a smaller dataset would have overfit to memorized phrases rather than learning the underlying geometry of meaning.

📉 Underfitting	📚 Overfitting	🎯 Just Right
Student who didn't study at all. Fails everything.	Student who memorized last year's questions word-for-word. Fails any new question.	Student who understood the material. Passes any exam on the topic. ✅

Four Ways to Fix Overfitting

1. More Data — The most reliable fix. If the network has seen 100,000 examples instead of 100, memorizing becomes impossible. It has to generalize.

2. Dropout — During training, randomly "turn off" some neurons in each forward pass. The network is forced to not rely on any single neuron, so it develops redundant, distributed knowledge.

# PyTorch Dropout example
import torch.nn as nn

model = nn.Sequential(
    nn.Linear(10, 64),
    nn.ReLU(),
    nn.Dropout(p=0.3),   # 30% of neurons randomly disabled during training
    nn.Linear(64, 3),
    nn.Softmax(dim=1)
)

3. Early Stopping — Monitor validation loss (on data the network hasn't trained on). When validation loss starts rising while training loss keeps falling — stop. The network has started memorizing.

4. Data Augmentation — For images: flip, rotate, change brightness, add noise. For text: paraphrase, translate and back-translate. The network sees the same concept presented differently, so it learns the concept — not the presentation.

Complete Python Implementation

Here's the full training loop working end-to-end to classify devices as glasses vs. rings:

import numpy as np
# This is a single-neuron version of the neuron we built in the previous article

# Training data: [price_normalized, weight_normalized] → label
X_train = np.array([
    [0.55, 0.48],   # mid price, mid weight → glasses
    [0.45, 0.72],   # lower price, heavier  → glasses
    [0.35, 0.03],   # low price, very light → ring
    [0.20, 0.03],   # very low, very light  → ring
])
y_train = np.array([1, 1, 0, 0])   # 1=glasses, 0=ring

# Initial weights (random start)
weights       = np.array([0.5, 0.5])
bias          = 0.0
learning_rate = 0.1

# The training loop
for epoch in range(100):
    total_loss = 0

    for x, y_true in zip(X_train, y_train):
        # Step 1: Forward Pass — make a prediction
        prediction = np.clip(np.dot(x, weights) + bias, 0, 1)

        # Step 2: Loss — measure the mistake
        loss        = (y_true - prediction) ** 2
        total_loss += loss

        # Step 3 + 4: Backprop + Weight Update
        error    = y_true - prediction
        weights += learning_rate * error * x
        bias    += learning_rate * error

    if epoch % 25 == 0:
        print(f"Epoch {epoch:3d}  Loss={total_loss:.4f}  "
              f"Weights=[{weights[0]:.3f}, {weights[1]:.3f}]")

Output:

Epoch   0  Loss=0.4823  Weights=[0.618, 0.523]
Epoch  25  Loss=0.1204  Weights=[0.743, 0.611]
Epoch  50  Loss=0.0312  Weights=[0.819, 0.684]
Epoch  75  Loss=0.0089  Weights=[0.867, 0.731]
Epoch  99  Loss=0.0021  Weights=[0.891, 0.752]

The loss dropped from 0.48 to 0.002 in 100 epochs. Now test on a new device:

test = np.array([0.50, 0.55])   # new device: mid price, mid weight
pred = np.clip(np.dot(test, weights) + bias, 0, 1)
label = "Glasses ✅" if pred > 0.5 else "Ring ❌"
print(f"Prediction: {pred:.2f} → {label}")
# Prediction: 0.98 → Glasses ✅

The network learned to distinguish glasses from rings — without a single rule written explicitly. It learned the pattern from 4 examples, 100 epochs, and the four-step training loop.

Real-World Scale

The base model behind early ChatGPT (GPT-3) was trained on roughly 300 billion tokens of text (about 500 billion words — most of the internet). The training loop ran for months on thousands of GPUs running in parallel. The estimated compute cost: over $100 million.

Our example: 4 examples, 100 epochs, 0.001 seconds.

The math is identical. The scale is incomprehensible.

The GPT training answer: If you trained GPT-3 on a single modern consumer GPU (RTX 4090), it would take approximately 355 years. That's why distributed training across thousands of specialized chips (H100s, TPUs) isn't optional — it's required.

How This Loop Created the 384-Dimensional Embeddings from Article 2

In Article 2, we used a model that converted any sentence into a 384-dimensional vector. Now you know exactly how that model was built:

The embedding pipeline:

Data: Billions of multilingual sentence pairs — "I need coffee" paired with "محتاج قهوة" labeled as similar; "coffee" paired with "sleep" labeled as different

Loss: Contrastive loss — penalizes the model when similar sentences produce vectors that are far apart, rewards it when different sentences produce vectors that are far apart

Loop: The same 4-step training loop, run for millions of iterations on thousands of GPUs — until the 384 output neurons learned to encode meaning as geometry

The training loop IS how embeddings are made. Now you've seen both ends of the pipeline.

The Core Insight

Training isn't programming.

It's controlled failure at scale.

Guess → Measure → Blame → Fix → Repeat. The intelligence isn't in any single step. It's in the repetition.

Every AI capability you've ever used — image recognition, translation, text generation, code completion — is the result of this loop running billions of times on massive amounts of data.

Pro Tips for Builders

Start with lr=0.01 — it's the safest default for most problems; tune from there with a learning rate scheduler

Watch both losses — always track training loss AND validation loss. If training falls but validation rises, you're overfitting

Batch size affects generalization — smaller batches (16–32) add noise that helps escape local minima; larger batches train faster but can overfit more easily

Use Adam, not plain SGD — Adam adapts the learning rate per weight automatically; it's more forgiving and converges faster in practice

The 4-step loop is universal — whether you're fine-tuning GPT or training a 2-neuron toy model, the loop is identical. Only the scale changes.

Try It Yourself

Experiment with the learning rate in the code above:

# Experiment 1: learning_rate = 0.9  (too large)
# Change the learning_rate line to 0.9 and re-run.
# Watch the loss BOUNCE — it overshoots the minimum and never converges.

# Experiment 2: learning_rate = 0.001  (too small)
# Loss drops but very slowly — training would need 10x more epochs.

# Experiment 3: learning_rate = 0.1   (just right — default above)
# Smooth, steady convergence. Loss reaches near-zero by epoch 99.

Try adding a 5th training example that contradicts the pattern slightly — watch how the loss floor rises. That's the model struggling to generalize. This is overfitting in miniature.