For CEOs of software companies, engineering leaders, and engineers who want to work this way.
The first bug I solved for a new client took three days. The next three took one combined day—not because they were easier, but because I’d stopped solving bugs one at a time.
That shift is not about speed. It is about what you build while you are solving the first problem.
The First Fix Is Also Onboarding
The investigation time on the first bug in an unfamiliar system is rarely proportional to the complexity of the defect itself.
With this client, the bug turned out to have a straightforward fix. What took time was building the mental model first: understanding how the customer’s use of the CRM mapped to the backend code—which workflows triggered which functions, what got written to the database and what didn’t, and what correct output was supposed to look like. None of that is in the bug report. It has to be earned.
Roughly half the time on the first bug went into that context-building. The other half went into the fix, evidence gathering, testing, and producing documentation the client could use.
That’s not inefficiency. It’s the onboarding tax every first investigation pays. The real question: do you pay it once or repeatedly?
TRADITIONAL BUG WORKFLOW
─────────────────────────────────────────────────────────────────────────
Bug A reported (first bug for this client)
→ Engineer builds mental model
How does CRM usage map to backend code?
What gets saved to the database, and what doesn't?
What does correct output look like?
→ Root cause found, fix designed and tested
→ Bug A closed
→ Mental model: in the engineer's head
→ Investigation sequence: in closed ticket notes
Bug B reported (same class, different location)
→ Mental model rebuilt from scratch
(or a new engineer starts from zero)
→ Same investigation, re-derived
→ Fix designed, tested, documented — again
→ Bug B closed
Bug C, Bug D...
→ Same cycle
→ Each instance re-pays the onboarding tax
→ Time per bug stays flat
──────────────────────────────────────────────────────────────────
What you have after N bugs: N closed tickets
What you don't have: a faster path to the next instance
What Gets Encoded
By the end of the first bug, I had more than a fix. I had a sequence: how to approach a bug description for this type of system, how to investigate a codebase when tracing a defect, what principles to apply when analysing code, what to do the moment root cause files are found (back them up first, then create the working copy that will carry the fix), how to gather evidence before and after the fix, what to verify in the application UI and the exact navigation path to get there, when to rebuild the application cache after deploying changed files, and how to produce the handover documentation the client needed—with screenshots named and placed so they embed correctly in the final report.
I encoded that sequence into a skill—an executable methodology that an AI coding agent runs from start to finish. The critical design feature isn’t automation. It’s the human approval gates built into the process at every decision point.
The skill doesn’t run to completion on its own. It runs to a checkpoint, surfaces what it finds, and asks permission to continue. When the investigation phase concludes, it reports its findings and waits for review before moving to the fix. If it identifies something outside the original scope—a related defect, a follow-on issue—it stops and asks: address this in the current ticket, or log it separately and continue? When it reaches a step that requires the engineer to be physically present—logging into the application, navigating to a specific screen, taking a screenshot—it pauses and provides exact step-by-step instructions for what to do next.
Here’s what matters about the design: it encodes abstractions and principles, not specifics. It doesn’t say “look in module X for this class of defect” or “comment out line 127 in customHandler.php.” What it encodes is how to think about each phase—what to look for when analysing code, what to do when the root cause file is found (copy it first as a backup, then create the working copy that will carry the fix), how to name screenshots so they embed correctly in the handover document, and so on. The DB access credentials are already encoded, so every database step runs automatically—the skill connects, runs the query, and surfaces the results. The human never has to run a SQL script manually. What remains at the human gates is judgment: reviewing findings, making scope decisions, navigating the UI, and approving before the process continues.
SKILL EXECUTION: PHASES AND HUMAN GATES
─────────────────────────────────────────────────────────────────────────
[SKILL] Read bug description
↓
[SKILL] Investigate codebase — trace probable root cause
↓
[GATE] Report findings → Human reviews → Approve to continue?
↓
[SKILL] Set up workspace; generate SQL test scripts
↓
[SKILL] Reproduce bug — runs seed.sql automatically via encoded
DB credentials; surfaces results
↓
[GATE] UI evidence → Skill guides Human through CRM step-by-step
Human navigates, takes screenshots named before-fix.png
↓
[SKILL] Apply fix (root cause file backed up first; working copy
carries the change)
↓
[SKILL] Verify fix — runs verification queries automatically;
surfaces results
↓
[GATE] UI verification → Skill guides Human through CRM step-by-step
Human navigates, takes screenshots named after-fix.png
↓
[SKILL] Generate PDF handover — before-fix.png and after-fix.png
embedded at the correct positions automatically
↓
[GATE] Human reviews PDF → Feedback? → Skill revises if needed
↓
[SKILL] Teardown — removes all test artefacts from DB automatically
↓
Done
At any point: if additional findings emerge,
skill flags and asks — fix in scope or create a follow-on ticket?
─────────────────────────────────────────────────────────────────────────
The distinction between a document and a skill isn’t format. It’s this: a document waits to be read. A skill runs—and it knows exactly when to stop and ask.
What the Second Bug Felt Like
When the second bug came in, I invoked the skill.
The best way I can describe what followed: a movie started running. The script was already written. I was no longer the investigator improvising through an unfamiliar system—I was one of the actors, following a sequence that’d already been worked out. The skill read the new bug description, investigated the codebase, and came back with its findings. I reviewed them, confirmed the direction, and approved continuation.
Midway through, the skill surfaced something that hadn’t been in the original report—a related defect the investigation had uncovered. It stopped and asked: fix this within the current ticket, or log it as a follow-on? I made the call. It noted the follow-on and continued.
At every UI step, the skill paused and told me exactly where to go — which menu, which record, which field to check, which screenshot to take. Not a general reminder to gather evidence. Specific, step-by-step navigation for this system’s exact interface. It felt like a genuine caretaker making sure you walked the path and did each step correctly — not a tool waiting for you to figure out what came next.
By the end of the session: root cause confirmed, fix applied and verified, database evidence captured automatically, screenshots taken at the steps where my presence was required, PDF handover document generated with everything embedded in the right place. About an hour of active involvement, compared to the scattered hours the first bug’s investigation had required. That happened three times. One combined day.
One Engagement, The Numbers
First bug: three calendar days, three to four hours a day. Roughly half that time went into building the mental model and tracing the root cause. The other half went into the fix, evidence gathering, testing, and the handover document. The skill was built alongside that process — not as a separate exercise after, but as the methodology became clear during the investigation itself.
The next three bugs each ran through the skill. The investigation phase that had taken the bulk of the first day on bug one now took about an hour per bug. All three were completed in one working day.
Each subsequent bug, without the skill, would have required rebuilding the same mental model—re-tracing which code paths matter, which database tables to check, what evidence to gather. That’s not a hypothetical worst case. It’s exactly what the first bug required, and it would’ve been exactly what the second required if the methodology had stayed in my head. With the skill, that context was already encoded. Three bugs that would’ve stretched across the week were done in a day.
What the Client Sees
From my side, the shift is about where the work goes — less re-deriving context, more reviewing findings and making judgment calls.
From the client’s side, what changes is consistency and what arrives at the end.
Every bug fix produced the same artefacts in the same format: a structured workspace with the original and changed code files, SQL scripts for reproducing and verifying the fix, and a PDF handover report with embedded screenshots documenting both the bug and the fix. The second bug’s documentation looked exactly like the first — same structure, same evidence standard, same format — not because I spent extra time on it, but because generating it was part of the process rather than a separate effort after the fix was done.
When the skill identified a defect outside the original scope mid-investigation, the client didn’t discover it later as a surprise. It was flagged immediately, a decision was made, and it was handed over as a known, logged item. Scope discipline built into the workflow rather than depending on the engineer’s judgment under time pressure.
What Makes a Problem Worth Encoding
Not every bug justifies building a skill. A genuine one-off edge case in a rarely-touched corner of the system isn’t worth encoding. What makes a class of defects worth the investment:
Recurrence — the same root cause pattern appears in more than one location in the codebase, or will appear again as the system grows. If you can see the next instance coming, encoding the methodology now pays immediately.
Consistency requirement — defects with audit, financial, or handover implications benefit from reproducible investigation paths. If every fix has to be evidenced in the same way, a skill that generates that evidence as part of the process is more reliable than a one-off investigation documented differently each time.
Investigation depth — the more context-building the first instance required, the more valuable the skill. A surface-level configuration error probably doesn’t need encoding. A defect where finding the root cause requires understanding how user-facing workflows map to backend behaviour is exactly the kind of problem where re-deriving that understanding each time is the most expensive outcome.
Building the skill requires discipline during the first investigation: extracting the methodology while the understanding is still live, rather than closing the ticket and moving on.
The Asset That Stays When the Engagement Ends
A skill built for one client’s codebase—their specific architecture, their workflows, their business rules—doesn’t transfer to a different organisation. The general structure of the methodology may inform future work; the specifics don’t port.
What persists when an engagement ends is the skill living in the client’s system. The investigation sequence, the evidence standards, the fix pattern, the documentation process — all executable for whoever works in that system next. The methodology stays because it was built into the tools, not carried in the engineer’s head.
Skills need maintenance. If the codebase changes significantly—a major upgrade, a structural refactor—the encoded methodology should be reviewed alongside it. It’s a durable starting point, not a permanent fixture. That’s still a meaningfully better position than starting from a blank page each time.
The Question to Ask Before Engagement
One question changes what an engagement is worth:
After the first instance of this problem class is solved, will the practitioner have encoded how it was solved?
The answer tells you whether you are buying a fix or a methodology. Fixed bugs are necessary. But in mature, customised production systems, the same defect class tends to recur — in a different module, a different integration, a different workflow touching the same underlying logic. The methodology is what determines whether the next instance costs days or hours.
When I work this way, I do less investigating over time and more judging—reviewing the skill’s findings, confirming the direction, catching what the encoded methodology can’t catch on its own. The work shifts from rebuilding context to applying judgment on top of a consistent process.
The first bug is also your onboarding. Everything after should cost less.
If it doesn’t, the first bug’s work was only half done.
I work with software companies diagnosing production defects and building the AI-native workflows that make subsequent fixes faster and more consistent. When you’re at the point of asking that question before an engagement, I’d be glad to be in that conversation.