matlab-coach-debugging
Use when tutoring a learner through MATLAB debugging, error interpretation, failed tests, incorrect outputs, array-shape problems, indexing mistakes, function argument issues, or code repair practice. Use for guided debugging sessions, debugging drills, teach-the-agent critique, and evidence-based MATLAB troubleshooting.
git clone --depth 1 https://github.com/matlab/agent-skills-playground /tmp/matlab-coach-debugging && cp -r /tmp/matlab-coach-debugging/demos/ai-tutoring/skills/matlab-coach-debugging ~/.claude/skills/matlab-coach-debuggingSKILL.md
# MATLAB AI Tutor Debugging Coach
## Purpose
Coach learners through MATLAB debugging as evidence gathering. Help the learner
locate the failing assumption, inspect program state, design a small test, and
repair the code without turning the interaction into solution delivery.
For instructors, this skill supports one of the most important MATLAB learning
outcomes: students learn to use evidence from MATLAB, not guesswork, to explain
and repair code. It is especially useful in labs where many students encounter
similar indexing, shape, or function-interface errors.
Use with `matlab-tutor-learners`, `matlab-coach-programming`, and the
MATLAB Agentic Toolkit `matlab-debugging` skill when execution, breakpoints, or
runtime evidence are needed.
## Debugging Loop
1. **State expectation**: Ask what the learner expected the code to do.
2. **Capture evidence**: Get the exact error text or observed wrong output.
3. **Localize**: Identify the file, line, expression, and variable involved.
4. **Inspect state**: Ask for or run `size`, `class`, `whos`, and representative
values.
5. **Reduce**: Build a minimal reproduction with the smallest input that still
fails.
6. **Hypothesize**: Ask the learner to explain the likely cause before fixing.
7. **Test repair**: Apply one change and verify with a normal case and edge case.
8. **Transfer**: Ask how the same bug pattern would appear in nearby code.
## Coaching Rules
- Ask one diagnostic question at a time during active tutoring.
A single copy-paste block of related inspection commands counts as one ask.
- Prefer inspection prompts over edits until the failure is localized.
- Do not rewrite the full program when a focused repair will teach the concept.
- Make MATLAB evidence visible: sizes, classes, values, stack traces, and tests.
- Name the bug pattern after feedback: shape mismatch, wrong indexing form,
matrix/operator confusion, scope issue, type mismatch, tolerance issue, or
off-by-one loop bounds.
- If code execution matters, use MATLAB tools rather than guessing.
When a student asks "what is wrong with my code?", the tutor should avoid
starting with a replacement solution. Start with the evidence MATLAB already
provides, then guide the student toward the smallest useful repair.
## MATLAB Bug Patterns
- `*`, `/`, `^` used where `.*`, `./`, `.^` is intended.
- Row and column vectors silently producing larger arrays through implicit
expansion.
- `length` used when `height`, `width`, `numel`, or `size` is the real intent.
- Table extraction confused across `T.Var`, `T(:, "Var")`, and `T{:, "Var"}`.
- Cell contents confused with cells: `C{i}` versus `C(i)`.
- Script variables assumed to exist inside a function.
- Floating-point equality used where a tolerance is needed.
- Loop bounds based on the wrong dimension.
## Teach-the-Agent Debugging
Use this pattern when the learner needs conceptual practice rather than help with
their own file:
1. Present a short flawed MATLAB explanation or snippet.
2. Ask the learner to identify the false claim or failing line.
3. Ask for evidence that proves the issue.
4. Ask for the smallest correction.
5. Ask for one test that distinguishes the flawed and corrected versions.
Read [references/debugging-patterns.md](references/debugging-patterns.md) for
debugging prompts, minimal reproduction templates, and teach-the-agent drills.
## Instructor Adoption Notes
- Use this skill for lab support, office-hour preparation, and post-lab
reflection.
- Ask students to include the exact error text and the output of `size`,
`class`, or `whos` when requesting help.
- Encourage students to keep a short "bug pattern" log: issue, evidence,
repair, and how to recognize it next time.>
Use this skill when the user wants to author, design, scope, or refine an Agent Skill (a SKILL.md file). Trigger phrases include "build a new skill", "design an agent skill", "scope a SKILL.md", "how should I structure this skill", "write a skill for X", "my skill isn't working well", or any request to improve an existing SKILL.md. Walks the user through an empirical, test-first process — probe the agent for real failures, design only for genuine knowledge gaps, iterate against runnable examples, and verify across models.
Use this skill for any work involving a MATLAB Project (.prj file) — creating a new project, tracking files, managing the project path, configuring Simulink cache and code-generation folders, running project health checks, or writing build scripts that keep the project in sync with the file system. Trigger phrases include "set up a MATLAB project", "create a .prj", "track this file in the project", "project health check", "build script conventions". This skill is the generic foundation; domain-specific skills (e.g. `mbse-workflow`) build on it.
Use this skill for the architecture phases of an MBSE workflow in MATLAB, when writing idempotent buildXxx.m scripts that produce a three-layer RFLPV architecture (Functional, Logical, Physical) with interface dictionaries, stereotype profiles, allocation sets, and requirements Implement links. Trigger for defining stereotype properties, functional-to-logical / logical-to-physical allocation, mapping requirements to components via slreq Implement links, or running quantitative roll-up analysis on the architecture. Do NOT trigger for ad-hoc structural edits to an already-built System Composer model (adding one component, rewiring a port) — use `building-simulink-models` with `model_edit` for that. Works alongside the `system-composer` skill for detailed SC API patterns.
Use this skill for guided MBSE work in MATLAB — starting a new project, resuming work mid-workflow on an existing project, or answering orientation questions about how the MBSE skills fit together. Trigger when the user says they want to create, start, or set up a new MBSE project; work on a model-based systems engineering / RFLPV project; or asks which skill covers which phase. Walks through phases one at a time — propose → approve → generate → run → confirm. Use proactively whenever someone mentions starting or continuing an MBSE project.
Use this skill for all requirements-related work in a MATLAB MBSE project using the Requirements Toolbox (slreq). Covers creating and populating requirement sets, derivation links, test case requirements, verification coverage, reading and tracing links across requirement sets and models, checking link health, allocating requirements to components (Implement links), and building traceability reports. Trigger when the user asks about slreq API, slreqx files, slmx link files, outLinks/inLinks, traceability matrices, coverage analysis, broken links, or mapping requirements to architecture components. Use proactively for any requirements or traceability task.
Use this skill when authoring reusable, idempotent MATLAB scripts that build System Composer architecture models via the architecture-modeling API — `systemcomposer.createModel`, `addComponent`, `addPort`, `setInterface`, `connect(srcPort, dstPort)`, interface dictionaries (.sldd) with `addInterface`/`addElement`, profiles/stereotypes with `Profile.createProfile` and `addStereotype`, or `systemcomposer.allocation.createAllocationSet`. Also trigger when debugging these APIs (connections that don't appear, interfaces that don't resolve, profile save errors, `createAllocationSet` signature-mismatch errors). Do NOT trigger for ad-hoc structural edits to an already-built model (adding one SubSystem, rewiring a port) — use `building-simulink-models` with `model_edit` for that.
Optimize MATLAB code for better performance through vectorization, memory management, and profiling. Use when user requests optimization, mentions slow code, performance issues, speed improvements, or asks to make code faster or more efficient.