Tutorial 04 — A Structured Three-Prompt Debugging Workflow
Tutorial 04 — A Structured Three-Prompt Debugging Workflow
AI and PicBasic Pro Tutorial Series — Post 4 of 6
Content produced with AI assistance and reviewed by the forum administrator.
Why One Prompt Is Not Enough
The instinct when debugging code with AI is to paste the code and ask it to fix the problems. Sometimes this works. More often the AI pattern-matches on symptoms, misses underlying causes, and produces a corrected version it cannot fully justify — because it went straight to fixing without properly understanding what it was looking at.
The structured workflow below forces a different sequence. The AI must understand the code before it audits it, and audit it before it touches it. Each step produces a clearly marked output block that feeds directly into the next prompt. You do not summarise or paraphrase between steps — you paste the raw output. This keeps the AI working from its own verified reasoning rather than reconstructing from memory at each stage.
The Three-Step Sequence
Step 1 — Understand
The AI explains what the code does and how it works. This forces it to build an accurate model of the code before forming any opinions about what is wrong with it.
Step 2 — Audit
The AI checks the code against a specific list of known fault categories and produces a numbered fault list. It does not make any changes at this stage.
Step 3 — Fix
The AI receives the fault list and the original code together and produces a corrected version with every change annotated and justified.
How Chaining Works
Each prompt ends with an instruction to output results in a clearly delimited block. You copy that block exactly — including the markers — and paste it at the top of the next prompt before the new instructions. The AI works from its own prior output rather than starting fresh.
Never paraphrase or summarise between steps. Copy the raw output block.
Prompt 1 — Understand the Code
Paste your source code after this prompt, then send it. Adjust the description to match what your code actually does.
Code:
; ============================================================
; PROMPT 1 — UNDERSTAND
; Adjust the description to match your code before use
; ============================================================
You are an embedded systems engineer with knowledge of PicBasic Pro 3
(PBP3) by melabs and PIC architecture. Analyse the code below and
explain: the overall purpose of the program; what the port and register
configuration implies about the hardware; any conditional compilation
guards and what they do; the main logic flow and how it works.
Reference the workspace documents where relevant. Write for someone
who understands embedded systems but has not seen this code before.
At the end, output the original source code unchanged inside:
===ORIGINAL CODE START===
(code here)
===ORIGINAL CODE END===
Before moving to Prompt 2: copy everything between and including the ===ORIGINAL CODE START=== and ===ORIGINAL CODE END=== markers and paste it at the top of Prompt 2.
Prompt 2 — Audit the Code
Paste the original code block from Prompt 1 at the top. Adjust the device and clock references for your target.
Code:
===ORIGINAL CODE START===
(paste Prompt 1 code block here)
===ORIGINAL CODE END===
; ============================================================
; PROMPT 2 — AUDIT
; Replace [YOUR DEVICE] and [YOUR CLOCK] before use
; ============================================================
Audit the source code above for [YOUR DEVICE] at [YOUR CLOCK] MHz.
Use the workspace documents as your reference. Do not make any changes.
Check the following specifically:
1. CONFIG blocks — count them, identify any conflicting bits, confirm
settings are correct for the target device and clock speed.
2. DEFINE OSC — confirm correct value and placement. It must appear
before any timing-dependent code.
3. Register widths — check every literal assigned to an 8-bit register
and flag any that exceed 8 bits.
4. Floating inputs — list every pin configured as input with no
pull-up enabled and no reference in the code.
5. Timing — verify any PAUSE or PAUSEUS values and any timer period
calculations against the declared clock speed.
6. ISR logic — if the code contains interrupt service routines,
trace the branch logic step by step. Confirm STATUS flag values
at each branch point and whether the branch instruction is correct.
For each fault state: location, what is wrong, why it is wrong.
===FAULT LIST START===
FAULT 1: [location] | [what is wrong] | [why it is wrong]
FAULT 2: [location] | [what is wrong] | [why it is wrong]
===FAULT LIST END===
Then output the original code unchanged:
===ORIGINAL CODE START===
(code here)
===ORIGINAL CODE END===
Before moving to Prompt 3: copy the entire ===FAULT LIST START=== block and the entire ===ORIGINAL CODE START=== block and paste both into Prompt 3.
Prompt 3 — Fix and Verify
Code:
===FAULT LIST START===
(paste fault list from Prompt 2 here)
===FAULT LIST END===
===ORIGINAL CODE START===
(paste code block from Prompt 2 here)
===ORIGINAL CODE END===
; ============================================================
; PROMPT 3 — FIX
; Replace [YOUR DEVICE] and [YOUR CLOCK] before use
; ============================================================
Fix every fault in the fault list. Use the workspace documents as
your reference for all syntax, DEFINE values, and CONFIG bits.
Requirements:
- Produce a single clean CONFIG block. Remove any duplicate.
- DEFINE OSC must appear before any timing-dependent code.
- Correct any oversized register literals.
- Resolve floating inputs — justify the approach against circuit intent.
- Verify all timer calculations and PAUSE values against clock speed.
- Preserve all existing functionality exactly.
Mark every change in the code: ; FIX [n]: description
===FIX SUMMARY START===
FIX 1: [what was wrong] | [what was changed] | [why]
===FIX SUMMARY END===
===CORRECTED CODE START===
(corrected code here)
===CORRECTED CODE END===
If the Code Still Will Not Compile
Paste the full compiler error output and the corrected code block from Prompt 3 into a follow-up message in the same conversation:
Code:
; ============================================================
; COMPILER ERROR FOLLOW-UP
; ============================================================
The corrected code above produced the following compiler errors.
Identify the cause of each error by reference to the workspace
documents and produce a corrected version.
COMPILER OUTPUT:
(paste full compiler output here — do not paraphrase it)
===CORRECTED CODE START===
(paste code from Prompt 3 here)
===CORRECTED CODE END===
Paste the raw compiler output — do not describe it in your own words. The error messages give the AI precise location and fault information that a description loses.
Important Notes
The prompts above are templates. Before using them:
- Replace [YOUR DEVICE] with your actual target PIC part number
- Replace [YOUR CLOCK] with your actual clock speed in MHz
- Adjust the Prompt 1 description to match what your code actually does
- The audit checklist in Prompt 2 covers the most common fault categories — add device-specific checks if you know your device has particular quirks
The corrected code the AI produces must still be tested. A compile-clean result is not the same as correct behaviour on hardware. The workflow removes a significant class of errors before the code reaches you — it does not replace hardware testing.
Previous: Tutorial 03 — Setting a Profile Instruction
Next: Tutorial 05 — Working With Complex Documents
This tutorial series was produced with AI
