Debugging Is the Skill AI Can't Do for You
AI can write the code, but finding out why it's wrong is still your loop: reproduce, isolate, hypothesize, verify. A real Laravel walkthrough with stack traces, git bisect and the fix at the boundary.
المحتويات
Consider this hypothetical: an AI assistant writes the import feature in four minutes. It passes review, the types look right, and a week later finance asks why every invoice total is off by a factor of a hundred. AI made the writing faster. It did not remove the part where someone finds out why the code is wrong - that part is a loop, it has a shape, and you can practice it.
This article is that shape - reproduce, isolate, hypothesize, verify - applied to a Laravel walkthrough: a CSV invoice import that breaks when the export format changes. Every output below is a real run on PHP 8.4 and Laravel 13, not a retyped approximation.
The loop#

AI tools fit inside this loop: with authorized access to your repo and environment they can run the failing test, drive git bisect, and propose a patch - and debugging genuinely is faster for it. What they don't own is the accountability: your goal, your permissions, your production data, and the call that a fix is safe to deploy. Use them as a fast pair inside the steps; keep ownership of the loop.
Step 1: Reproduce#
"Totals are sometimes wrong" is not a bug report you can fix. The first job is a failure you can produce on demand - ideally a failing test, because it survives the fix and becomes the proof. Here is the reproduction: the new CSV export and the total it should produce.
namespace Tests\Feature;
use App\Services\CsvInvoiceImport;
use App\Services\InvoiceTotals;
use InvalidArgumentException;
use Tests\TestCase;
class DebugWalkthroughTest extends TestCase
{
// The new CSV export (decimal major units) used by the repro.
private string $csv = "MUG,2,19.99\nTEE,1,45.00";
public function test_imported_csv_totals(): void
{
$lines = (new CsvInvoiceImport)->parse($this->csv);
// 2 x 19.99 + 1 x 45.00 = 84.98 -> 8498 minor units
$this->assertSame(8498, (new InvoiceTotals)->total($lines));
}
public function test_import_converts_to_integer_minor_units(): void
{
$lines = (new CsvInvoiceImport)->parse($this->csv);
$this->assertSame(
[['sku' => 'MUG', 'qty' => 2, 'unit_price_minor' => 1999],
['sku' => 'TEE', 'qty' => 1, 'unit_price_minor' => 4500]],
$lines
);
}
public function test_import_rejects_a_malformed_row_with_its_line_number(): void
{
$this->expectException(InvalidArgumentException::class);
$this->expectExceptionMessage('row 2');
(new CsvInvoiceImport)->parse("MUG,2,19.99\nTEE,lots,45.00");
}
public function test_import_rejects_a_row_with_the_wrong_field_count(): void
{
$this->expectException(InvalidArgumentException::class);
$this->expectExceptionMessage('expected 3 fields');
(new CsvInvoiceImport)->parse("MUG,2");
}
public function test_import_rejects_excessive_quantity(): void
{
$this->expectException(InvalidArgumentException::class);
(new CsvInvoiceImport)->parse("MUG,99999,19.99");
}
public function test_import_rejects_excessive_price_precision(): void
{
$this->expectException(InvalidArgumentException::class);
(new CsvInvoiceImport)->parse("MUG,2,19.999");
}
public function test_import_rejects_empty_sku(): void
{
$this->expectException(InvalidArgumentException::class);
(new CsvInvoiceImport)->parse(",2,19.99");
}
public function test_import_rejects_too_many_rows(): void
{
$this->expectException(InvalidArgumentException::class);
$this->expectExceptionMessage('10000');
(new CsvInvoiceImport)->parse(str_repeat("MUG,1,19.99\n", 10001));
}
public function test_worst_case_total_fits_a_64_bit_int(): void
{
// 10000 rows x qty 10000 x 9,999,999.99 major: the largest import the bounds allow
$line = ['sku' => 'MUG', 'qty' => 10000, 'unit_price_minor' => 999999999];
$total = (new InvoiceTotals)->total(array_fill(0, 10000, $line));
$this->assertSame(99999999900000 * 1000, $total); // 99,999,999,900,000,000 < PHP_INT_MAX
$this->assertLessThan(PHP_INT_MAX, $total);
}
}Run it, and the failure is real and repeatable, with the frames PHPUnit actually printed:
1) Tests\Feature\DebugWalkthroughTest::test_imported_csv_totals
TypeError: App\Services\InvoiceTotals::total(): Return value must be of type int, float returned
/tmp/laravel/scratch/app/Services/InvoiceTotals.php:14
/tmp/laravel/scratch/tests/Feature/DebugWalkthroughTest.php:18Two lessons already. The suite now fails the same way every time - no more "sometimes". And the error is not "totals are wrong": it is a type boundary reporting that a float escaped into a function declared to return int.
Step 2: Isolate#
Now shrink the world until only the bug is left. The second test isolates the data itself - expected integers, actual strings:
Array &0 [
0 => Array &1 [
'sku' => 'MUG',
- 'qty' => 2,
- 'unit_price_minor' => 1999,
+ 'qty' => '2',
+ 'unit_price_minor' => '19.99',
],
1 => Array &2 [
'sku' => 'TEE',
- 'qty' => 1,
- 'unit_price_minor' => 4500,
+ 'qty' => '1',
+ 'unit_price_minor' => '45.00',
],
]'unit_price_minor' => '19.99' is the whole mystery in one line: the new export writes decimal major units, the importer passed the raw strings through, and PHP's arithmetic happily multiplied numeric strings into floats. Two wrongs - wrong type, wrong unit - one boundary.
When the question is not "what input fails" but "when did it break", the isolating tool is git bisect: give it a good commit, a bad commit, and a test script, and it binary-searches the history. This next output is a separate, deliberately small demo repo - a shipping-fee calculation with the same "worked yesterday" regression shape, not the invoice code above:
Bisecting: 4 revisions left to test after this (roughly 2 steps)
[019e3c87a700519e138bff7ed1dae767af12cd76] refactor pass 5
running './test_total.sh'
310
Bisecting: 2 revisions left to test after this (roughly 1 step)
[174a3df292f87bb1fa696addc0e4778cf587a26b] docs tweak 7
running './test_total.sh'
304
Traceback (most recent call last):
File "/tmp/bisectdemo/./calc.py", line 12, in <module>
assert total == 250 + 30 + int(2.5 * 12), f"expected 310, got {total}"
AssertionError: expected 310, got 304
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[3462b502b400313f328435c3fc01a457fac73268] simplify shipping math
running './test_total.sh'
304
Traceback (most recent call last):
File "/tmp/bisectdemo/./calc.py", line 12, in <module>
assert total == 250 + 30 + int(2.5 * 12), f"expected 310, got {total}"
AssertionError: expected 310, got 304
3462b502b400313f328435c3fc01a457fac73268 is the first bad commit
commit 3462b502b400313f328435c3fc01a457fac73268
Author: Demo <demo@example.com>
Date: Mon Nov 9 14:35:09 2026 +0200
simplify shipping math
calc.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
bisect found first bad commitTen commits, three test runs, one culprit commit: "simplify shipping math", which quietly changed int(weight_kg * 12) into int(weight_kg) * 12. Reading that one diff is a five-minute job instead of an afternoon of guessing - that is what isolation buys you.
Step 3: Hypothesize#
Look again at the trace in step 1. The exploding frame is InvoiceTotals.php:14 - the return $sum; line. But InvoiceTotals is not wrong: it correctly refused to return a float. A stack trace tells you where the mistake was noticed, not where it was made. The faulty frame - the importer passing strings through - appears nowhere in that trace, because it ran earlier and returned quietly. Read traces as "where do I start looking", not "what do I edit".
A hypothesis is one falsifiable sentence with a prediction: "the importer is passing raw CSV strings, and the new export uses decimal major units - so converting at the import boundary makes the failing test pass without touching InvoiceTotals." One guess, one predicted observation. If the prediction fails, the loop gives you the next hypothesis instead of five simultaneous edits that each might be the fix.
Step 4: Verify#
The fix lives exactly at the boundary - validate field count, SKU, quantity and price; then convert to integer minor units with exact decimal-string arithmetic. No floats anywhere near money:
declare(strict_types=1);
namespace App\Services;
use InvalidArgumentException;
class CsvInvoiceImport
{
// Tutorial scope: one flat record per line. str_getcsv on pre-split lines
// cannot handle quoted fields containing newlines - use a streaming CSV
// library if your export has those. Inputs are bounded on purpose.
private const MAX_QTY = 10000;
private const MAX_ROWS = 10000; // bounds the worst-case total: 10k rows x 10k qty x 999,999,999 minor ~ 1e17, safely inside a 64-bit int
/**
* Parses "SKU,qty,unit_price" rows from the new export, which uses
* decimal major units ("19.99"). The boundary is exactly where the
* conversion belongs: validate, then convert to integer minor units
* with exact decimal-string arithmetic - no floats, ever.
*/
public function parse(string $csv): array
{
$lines = [];
foreach (explode("\n", trim($csv)) as $n => $row) {
$where = 'row ' . ($n + 1);
if ($n >= self::MAX_ROWS) {
throw new InvalidArgumentException("$where: more than " . self::MAX_ROWS . ' rows in one import');
}
$fields = str_getcsv($row);
if (count($fields) !== 3) {
throw new InvalidArgumentException("$where: expected 3 fields, got " . count($fields));
}
[$sku, $qty, $price] = $fields;
if ($sku === '') {
throw new InvalidArgumentException("$where: sku must not be empty");
}
if (!ctype_digit($qty) || (int) $qty < 1 || (int) $qty > self::MAX_QTY) {
throw new InvalidArgumentException("$where: qty must be a whole number between 1 and " . self::MAX_QTY . ", got \"$qty\"");
}
// exact decimal parse: 1-7 whole digits, optional 1-2 decimal digits;
// the pattern itself caps the price at 9,999,999.99 (999,999,999 minor)
if (!preg_match('/^(\d{1,7})(?:\.(\d{1,2}))?$/', $price, $m)) {
throw new InvalidArgumentException("$where: price must be a decimal amount with at most 2 decimal places, got \"$price\"");
}
$minor = (int) $m[1] * 100 + (int) str_pad($m[2] ?? '', 2, '0');
$lines[] = ['sku' => $sku, 'qty' => (int) $qty, 'unit_price_minor' => $minor];
}
return $lines;
}
}The unchanged InvoiceTotals for contrast - typed boundaries are what turned a silent wrong answer into a loud, traceable error:
declare(strict_types=1);
namespace App\Services;
class InvoiceTotals
{
/**
* Sums validated importer output. The importer's bounds (10k rows x 10k qty
* x 999,999,999 minor) cap the worst case near 1e17, inside a 64-bit int -
* this assumes 64-bit PHP, which is the standard build.
*
* @param array<int, array{sku: string, qty: int, unit_price_minor: int}> $lines
*/
public function total(array $lines): int
{
$sum = 0;
foreach ($lines as $line) {
$sum += $line['qty'] * $line['unit_price_minor'];
}
return $sum;
}
}Verify means the original failing test goes green and the neighboring behavior holds - the new tests guard the validation itself (wrong field count, excessive quantity, excessive precision, empty SKU, too many rows, and a malformed row reported with its line number):
OK (9 tests, 13 assertions)The failing test from step 1 is now a regression test. That is the quiet payoff of reproducing as a test instead of in your browser.
For the record, the broken version that produced every red output above - note the docblock admitting the bug, which is what a post-incident comment should look like:
declare(strict_types=1);
namespace App\Services;
class CsvInvoiceImport
{
/**
* Parses "SKU,qty,unit_price" rows.
* BUG: passes the raw CSV strings straight through. When the export
* switched from minor units ("1999") to decimal major units ("19.99"),
* every downstream total silently became a float in the wrong unit.
*/
public function parse(string $csv): array
{
$lines = [];
foreach (explode("\n", trim($csv)) as $row) {
[$sku, $qty, $price] = str_getcsv($row);
$lines[] = ['sku' => $sku, 'qty' => $qty, 'unit_price_minor' => $price];
}
return $lines;
}
}When the loop needs better eyes: logs and Telescope#
Some bugs refuse to reproduce locally because the failing input only exists in production. Then step 1 becomes "capture the failure in the wild":
- Log context, not noise.
Log::warning('invoice import failed', ['rows' => count($lines), 'source' => $source])beatsLog::debug('here'). Numbers and identifiers, not prose. - Log at boundaries. The exact place our bug lived - external data entering the system - is where a logged payload sample saves hours later.
- Redact before you log, and before you share. Secrets, tokens and personal data never go into log lines - and a raw production payload never goes into an AI tool. Share the smallest anonymized excerpt that still shows the failure.
- Laravel Telescope is the local/staging microscope: it records requests, exceptions, queries, jobs and mail per request, so "what exactly did this request do" stops being archaeology. Install it in development, restrict it anywhere else, and reach for it when the failing request is too big to hold in your head.
Which tool for which symptom#
| Symptom | First tool |
|---|---|
| Wrong value, no error | a failing test with the exact expected value |
| It worked last week | git bisect run with that test |
| 500 / exception | the stack trace - start at your frame, not the framework's |
| Works locally, fails in production | logs with context, Telescope on a staging replay |
| Fails "sometimes" | keep reproducing until it's deterministic; flaky usually means shared state or time |
Common mistakes#
| Mistake | What it costs |
|---|---|
| Editing before reproducing | You fix a guess and never know if the real bug survived |
| Changing three things at once | Green again, but no idea which change mattered - and one of them was wrong |
| Reading only the top stack frame | You "fix" the function that noticed the bug, not the one that caused it |
| Deleting the failing test after fixing | The regression returns in six months, unnoticed |
| Asking an AI to "fix the bug" with no repro | Confident patches against a bug nobody has seen fail |
Key takeaways#
Debugging is a loop, not an event: reproduce on demand, isolate to the smallest failing input, hypothesize one falsifiable guess, verify with the test that now guards the fix. Stack traces tell you where the mistake was noticed; git history tells you when it arrived; logs tell you what production saw. AI assistants can run inside every step with the right access - the loop, the permissions, and the accept-or-reject call stay with you.
References#
- Laravel Telescope documentation: https://laravel.com/docs/telescope
- git-bisect documentation: https://git-scm.com/docs/git-bisect
- Companion piece: /en/blog/learn-to-code-with-ai-without-dependency
- Integer minor units and floats near money: /en/blog/money-bugs-currency-rounding-discounts-vat
Hunting a bug that refuses to reproduce? See /en/services.