matlab-coach-debugging

# 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.