You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Project: VisualDebugger — AI Bug Tutor for VS Code
Theme: Education | Healthcare
Event: 24-Hour Hackathon (CHD)
Team Size: 3 Engineers (Full Stack)
Last Updated: 2026-02-14
1. Problem Statement
Error messages were designed by experts for experts. For the 15–20% of CS students who are neurodivergent — ADHD, dyslexia, dyscalculia, processing disorders — they are not just confusing. They are an accessibility barrier.
CS has a 40% dropout rate; frustration with debugging is the #1 cited reason.
Neurodivergent students drop STEM at 1.5x the rate of their neurotypical peers (NSF, 2019).
For a dyslexic student, a stack trace is a wall of unreadable text — dense symbols, camelCase identifiers, nested parentheses.
For a student with ADHD, it's a working memory overload — too much information, no clear entry point, no prioritization.
When students and junior developers compile or run their code and hit an error, they're met with a wall of cryptic error messages they don't understand. They can't read stack traces. They don't know what "TypeError: Cannot read properties of undefined" actually means. So they copy-paste the error into an AI tool, accept the fix, and move on — without ever understanding what went wrong.
The result: Students never learn to read error messages. They never build debugging intuition. They can't distinguish a syntax error from a logic error from a runtime crash. They become dependent on AI to fix problems they should be able to diagnose themselves.
2. Solution
A VS Code extension with a two-phase learning loop that activates when a student hits an error:
Phase 1 — Error Explanation (before the fix)
When the student compiles/runs code and gets an error:
Locates exactly where the bug is in their code
Explains what the error message means in plain English
Teaches how to fix it and how to prevent it in the future
Shows best practices related to this type of bug
Phase 2 — AI Fix Review (after the fix)
When the student prompts an AI tool (Copilot, Cursor, ChatGPT) to fix the code:
Shows a visual diff of what the AI changed (green = added, red = removed)
Explains what the AI did and why that fixes the problem
Reinforces the lesson from Phase 1
Three Bug Categories
Category
What It Covers
Example
Syntax Error
Code that can't be parsed — missing brackets, typos, malformed expressions
SyntaxError: Unexpected token '}'
Logic Error
Code that runs but produces wrong results — wrong operators, bad conditions, off-by-one
Counter shows wrong number, condition never triggers
Runtime Error
Code that crashes during execution — null refs, type errors, missing imports
TypeError: Cannot read properties of undefined
Accessibility by Design
Every feature in VisualDebugger maps to a clinical accommodation backed by learning science research:
Feature
Research Basis
Accommodates
Plain-English explanations
Cognitive Load Theory (Sweller, 1988) — reduce extraneous load
ADHD working memory limitations + dyslexia decoding difficulty
Visual diffs (red/green)
UDL Principle 2: Multiple Means of Representation
Processing disorders, visual learners
TTS read-aloud
Mayer's Modality Effect — dual-channel processing
Dyslexia + visual impairment
Card-based sections
Segmenting Principle (CLT) — break complex info into chunks
ADHD attention regulation
"Test Yourself" Quiz
Active recall + UDL Principle 3: Multiple Means of Action & Expression
All learners — reinforces comprehension
Bug Dashboard
Self-monitoring — UDL Guideline 9.3: Develop self-assessment and reflection
ADHD metacognition, executive function support
3. Target Users
User
Context
Need
CS students (bootcamp / university)
Learning to code, using AI assistants daily
Understand error messages and bugs, not just fix them
Junior developers
First job, can't read stack traces
Build debugging intuition, learn to self-diagnose
Self-taught devs
Learning from YouTube / tutorials + AI
Understand the difference between bug types
Students with ADHD
5–10% of developers; reduced working memory, wall-of-text avoidance
Visual step-by-step, concrete examples over abstractions
Students with processing disorders
Difficulty with information-dense output
Progressive disclosure, multi-modal presentation
Scope for hackathon: Web developers working with HTML/CSS/JavaScript/TypeScript/React.
4. Features
P0 — Must Ship (Demo-Critical)
ID
Feature
Description
Acceptance Criteria
F1
Extension Shell
VS Code extension that activates on web projects, registers commands, and hosts webview panels
Extension installs from VSIX, activates on JS/TS files, opens side panel
F2
Error Interception
Detects compiler/runtime errors from the terminal or diagnostics API and captures the error output
Catches errors from terminal output and VS Code diagnostics, extracts error message + file + line
F3
Error Explanation Panel
Webview panel that explains the error: where the bug is, what it means, how to fix it, how to prevent it, best practices
Panel shows error location, plain-English explanation, fix suggestion, prevention tips, and best practices — all readable by a beginner
F4
Bug Classification
LLM classifies the error into one of 3 categories (Syntax, Logic, Runtime)
Returns JSON with category, explanation, fix guidance, prevention tips, and best practices — under 5 seconds
F5
Diff Detection
Detects when a file changes after the user prompts an AI tool to fix the code, captures before/after state
Captures old content vs new content on file save, produces a structured diff
F6
Visual Diff Panel
Webview panel showing syntax-highlighted diff of what the AI changed
Diff renders with color-coded additions (green) and deletions (red), syntax highlighted, with explanation of what the AI did
F7
Demo App
A small React app with 3 pre-planted bugs (one per category) for the live demo
Each bug is triggerable, produces a clear error, and is fixable by AI with a visible diff
F10
TTS Read-Aloud
ElevenLabs-powered "read aloud" button on explanation cards — a core accessibility accommodation for dyslexia and visual impairment
Clicking button plays natural TTS of the explanation. Accessible for visual learners. Screen reader fallback with browser SpeechSynthesis API
P1 — Should Ship (Strengthens Demo)
ID
Feature
Description
Acceptance Criteria
F8
Bug Dashboard
Webview panel showing bug history — category breakdown, trend over time
Bar chart of bug categories, line chart of bugs over sessions, "focus area" recommendation
F9
"Test Yourself" Quiz
After showing the error explanation, prompts user with a multiple-choice question to test understanding
Quiz renders in webview, user selects answer, gets feedback (correct/incorrect + why)
F11
Seed Data
Pre-populated bug history for demo (simulating a week of student coding)
Dashboard shows realistic data: 15–20 bugs across categories with timestamps
F16
TL;DR One-Liner
Add tldr field to Gemini schema — one sentence under 15 words, always visible as Layer 0
Error panel shows one-line summary before expanded sections
F17
Progressive Disclosure
Collapsible sections with details/summary. TL;DR always visible, sections expand on click
Sections start collapsed, user expands what they need
F18
Simplified Mode Toggle
Toggle between Standard and Simplified (5th grade level, analogies, no jargon)
Toggle visible in panel, re-explains at simpler level
F19
Error Key-Term Highlighting
Add keyTerms array to Gemini schema, highlight 1–3 most important words in error message
Key terms visually highlighted
F20
Section Icons
Visual icons for each section (lightbulb, wrench, shield, star, brain)
Each section has an icon cue
F21
ARIA Labels + Keyboard Nav
aria-live, aria-label, role attributes, focus-visible styles
Screen reader compatible, keyboard navigable
F22
Focus Mode
One card at a time with Next/Previous navigation
Toggle activates single-card view
P2 — Nice to Have (Polish)
ID
Feature
Description
F12
Animations
Smooth transitions when panels open, explanation cards slide in
F13
Live Preview Panel
Embedded iframe showing the running app — updates on file change
F14
Export Report
"Download your bug report" as PDF/PNG from the dashboard
F15
Streaks/Gamification
"You've gone 5 compiles without a syntax error!" encouragement messages
5. User Stories
Phase 1 — Error Explanation
AS A student who just hit a compile/runtime error,
WHEN I see a confusing error message I don't understand,
I WANT VisualDebugger to explain where the bug is, what the error means,
how to fix it, and how to prevent it in the future,
SO THAT I learn to read and understand error messages on my own.
Phase 2 — AI Fix Review
AS A student who just asked AI to fix my code,
WHEN the AI changes my file,
I WANT to see exactly what the AI changed (red/green diff)
and an explanation of what it did and why,
SO THAT I understand the fix instead of blindly accepting it.
Dashboard Flow
AS A student reviewing my progress,
WHEN I open the Bug Dashboard,
I WANT to see my bug patterns over time (syntax vs logic vs runtime),
SO THAT I know which type of bugs I struggle with most.
ADHD Accommodation
AS A student with ADHD who just hit a compile error,
WHEN I see a wall of text I can't focus on,
I WANT a one-line summary that tells me what went wrong
SO THAT I can quickly understand without being overwhelmed.
Dyslexia Accommodation
AS A dyslexic student,
WHEN I see a cryptic error message full of symbols and jargon,
I WANT to hear the explanation read aloud while seeing key words highlighted
SO THAT I can understand through multiple channels.
Learning Disability Accommodation
AS A student with a learning disability,
WHEN I don't understand the standard explanation,
I WANT to toggle to a simpler mode with everyday language
SO THAT I get the same information at my reading level.
Need rich UI panels (error explanation, diff, dashboard) — webviews are the only way
Error detection
VS Code Diagnostics API + Terminal output parsing
Diagnostics API catches linter/compiler errors; terminal parsing catches runtime crashes
Bundler
esbuild
Industry standard for VS Code extensions. 100x faster than webpack, builds extension host + webview in parallel
Diff computation
diff npm library + diff2html for rendering
diff computes diffs, diff2html renders syntax-highlighted side-by-side/inline diffs out of the box
LLM provider
Gemini API
Targets MLH "Best Use of Gemini API" prize. Gemini handles structured JSON output well
Dashboard rendering
Chart.js v4 in webview
Canvas-based, no framework dependency, small bundle, proven in VS Code webviews
Webview framework
@vscode-elements/elements (Lit-based)
Replaced deprecated @vscode/webview-ui-toolkit. ~5kb, native VS Code look-and-feel, used by GitLens
State storage
VS Code globalState
Built-in, always available, no external dependencies
Secrets
context.secrets API
Encrypted storage for API keys (Gemini, MongoDB, ElevenLabs)
TTS
ElevenLabs API (P0)
"Read aloud" for bug explanations. Targets MLH "Best Use of ElevenLabs" prize. Core accessibility accommodation for dyslexia and visual impairment
Demo app hosting
DigitalOcean App Platform
Targets MLH "Best Use of DigitalOcean" prize. Shows production-ready deployment
Scaffolding
yo code (Yeoman)
Still the official standard, no real competitor
7. Core Flows (Detailed)
Phase 1: Error → Explanation
1. Student runs/compiles code
2. Error occurs (terminal output or VS Code diagnostic)
3. Extension captures:
- Error message (e.g., "TypeError: Cannot read properties of undefined (reading 'map')")
- File path + line number
- Surrounding code context (±10 lines around the error)
4. Extension sends to Gemini API:
- Error message + code context
- Prompt: "Classify this bug (syntax/logic/runtime), explain it for a beginner"
5. Gemini returns JSON:
- category: "Runtime Error"
- location: "line 15, App.tsx"
- tldr: "You called .map() on a variable that doesn't exist yet."
- explanation: "You're trying to call .map() on a variable that is undefined..."
- howToFix: "Check that 'data' is defined before calling .map() on it..."
- howToPrevent: "Always initialize state with a default value..."
- bestPractices: "Use optional chaining (data?.map) or provide a fallback..."
- keyTerms: ["undefined", ".map()"]
6. Error Explanation Panel opens with TL;DR visible, sections collapsed (progressive disclosure)
7. TTS read-aloud button available on every card
Phase 2: AI Fix → Diff Review
1. Student prompts AI tool (Copilot/Cursor/ChatGPT) to fix the bug
2. AI modifies the file
3. Extension detects file change (onWillSave captures before, onDidSave captures after)
4. Extension computes diff (before vs after)
5. Extension sends diff to Gemini API:
- Prompt: "Explain what this AI fix changed and why it fixes the problem"
6. Gemini returns JSON:
- whatChanged: "Added a null check on line 15 before calling .map()"
- whyItFixes: "The original code assumed 'data' was always an array, but..."
7. Diff Panel opens:
- Red highlighted: removed/changed code
- Green highlighted: new code
- Explanation card: what the AI did and why
"19% of CS students have a learning disability or ADHD. Error messages were designed by experts for experts. For a neurodivergent student, this isn't just confusing — it's an accessibility barrier. VisualDebugger is assistive technology for debugging."
0:15–0:30
Show the broken app
React app running. Student clicks a button — app crashes. Terminal shows: TypeError: Cannot read properties of undefined (reading 'map')
Student prompts Copilot/Cursor: "fix this error". AI modifies the file.
1:10–1:30
Phase 2: VisualDebugger shows what AI changed
Diff Panel opens. Red = removed code, Green = new code. Explanation card: "The AI added a null check before calling .map() and initialized the state with an empty array." Student now understands the fix.
1:30–1:40
TTS read-aloud moment
Click the read-aloud button. "For a dyslexic student, hearing this explanation activates dual-coding — research-backed multi-modal learning." Natural ElevenLabs voice reads the explanation while key terms stay highlighted.
1:40–1:50
Show the dashboard
Bug Dashboard with seeded week of data. Bar chart: Runtime (8), Logic (5), Syntax (3). "Focus area: Runtime errors — practice null checking and defensive programming."
1:50–2:00
Close with impact
"VisualDebugger turns every error into a lesson. It's not just education — it's assistive technology that makes coding accessible for the 1 in 5 students who learn differently."
11. Bug Categories (Classification Taxonomy)
Category
What It Covers
Example Error
Concept Link
Syntax Error
Code that can't be parsed — missing brackets, typos, malformed expressions, invalid JSX
SyntaxError: Unexpected token '}'
Syntax fundamentals, language grammar
Logic Error
Code that runs without crashing but produces wrong results — wrong operators, bad conditions, off-by-one, wrong return values
Button does nothing, counter shows wrong number
Boolean logic, control flow, boundary conditions
Runtime Error
Code that compiles but crashes during execution — null/undefined references, type errors, missing imports, async issues
TypeError: Cannot read properties of undefined
Defensive programming, error handling, type safety
12. Planted Demo Bugs
#
Bug
Category
Error Output
The Fix
1
Missing closing parenthesis in JSX return statement
Syntax
SyntaxError: Unexpected token, expected ","
Add the missing ) to close the return statement
2
<= instead of < in loop condition, rendering one extra undefined item
Logic
No crash — but app renders an extra empty/broken item in the list
Change <= to < in the loop condition
3
Calling .map() on state that is undefined before fetch resolves
Runtime
TypeError: Cannot read properties of undefined (reading 'map')
Initialize state as [] and/or add null check before .map()
13. Risk Register
#
Risk
Likelihood
Impact
Mitigation
Owner
R1
VS Code webview takes too long to set up
Medium
High
Start with yo code template. Eng 1 owns this exclusively for first 4h. Test webview "hello world" in first 30 min.
Eng 1
R2
LLM returns inconsistent/bad JSON
Medium
High
Use Gemini with structured output mode. Add JSON schema validation. Have 3 fallback hardcoded responses for demo bugs.
Eng 3
R3
Error interception misses errors or catches noise
Medium
Medium
Use VS Code Diagnostics API as primary source (reliable). Terminal parsing as secondary. Test with planted bugs early.
Eng 1
R4
Diff detection misses AI changes or fires on manual saves
Medium
Medium
Track "error active" state — only show diff panel if an error was recently explained. Use onWillSave + onDidSave pair.
Jargon decoded; simplified mode uses 5th-grade language
2.5: Illustrate through multiple media
Visual Diff (F6) + Text + Audio
Same information in text, visual (diff), and audio (TTS)
3.1: Activate background knowledge
Error Key-Term Highlighting (F19)
Highlights the 1–3 most important concepts to anchor understanding
Principle 3: Multiple Means of Action & Expression
The "how" of learning — how students demonstrate understanding.
UDL Guideline
VisualDebugger Feature
How It Works
4.1: Vary methods for response
Quiz (F9)
Multiple-choice quiz tests comprehension after explanation
5.2: Use multiple tools
Keyboard Nav (F21)
Full keyboard navigation for motor accessibility
6.4: Enhance capacity for monitoring progress
Bug Dashboard (F8)
Visual progress tracking across bug categories
Appendix: Prompt Templates
Phase 1 — Error Explanation Prompt
You are a coding education assistant. A student just hit an error they don't understand. Your job is to explain it clearly so they can learn from it.
## Input
- Language: {{language}}
- File: {{filename}}
- Error message: {{errorMessage}}
- Code context (lines around the error):
{{codeContext}}
## Instructions
Analyze this error and respond in JSON:
{
"category": "one of: Syntax Error | Logic Error | Runtime Error",
"location": "File and line number where the bug is",
"tldr": "One sentence under 15 words. The single most important thing to know.",
"explanation": "2-3 sentences explaining what this error message MEANS in plain English. Write for a student who has never seen this error before.",
"howToFix": "Step-by-step instructions for how to fix this specific bug. Reference the actual code.",
"howToPrevent": "1-2 sentences on how to avoid this type of bug in the future.",
"bestPractices": "1-2 sentences on the industry best practice related to this bug type.",
"keyTerms": ["array of 1-3 key words/phrases from the error message to highlight"],
"quiz": {
"question": "A question testing if the student understands WHY this error occurred",
"options": ["A) ...", "B) ...", "C) ...", "D) ..."],
"correct": "B",
"explanation": "Why the correct answer is right"
}
}
## Rules
- Explain for beginners, not experts
- Reference the actual code, not abstract concepts
- The error explanation should decode the error message — what does each part mean?
- Keep explanation under 60 words
- Keep howToFix actionable and specific
- The tldr must be a single sentence under 15 words — the most important takeaway
- keyTerms should be 1-3 of the most important words/phrases from the error that the student needs to understand
Phase 2 — AI Fix Explanation Prompt
You are a coding education assistant. A student had a bug, and an AI tool just fixed it. Your job is to explain what the AI changed and why.
## Input
- Language: {{language}}
- File: {{filename}}
- Original error: {{originalError}}
- Diff (before → after):
{{diff}}
## Instructions
Analyze this diff and respond in JSON:
{
"whatChanged": "1-2 sentences describing exactly what the AI modified in the code",
"whyItFixes": "2-3 sentences explaining WHY these changes fix the original error. Connect it back to the root cause.",
"keyTakeaway": "One sentence the student should remember from this fix"
}
## Rules
- Explain for beginners, not experts
- Reference specific lines from the diff
- Connect the fix back to the original error
- Keep whatChanged under 30 words
- Keep whyItFixes under 50 words