matlab-report-tutor-sessions

# MATLAB AI Tutor Session Report

## Purpose

Create clear HTML reports for MATLAB tutoring. Single-session reports help the
learner reflect on what was covered, what they demonstrated, where they need
more practice, and what evidence supports those conclusions. Aggregate reports
summarize patterns across multiple session reports for instructor review,
including recurring misconceptions, topic coverage, activity metrics, revision
behavior, and unresolved growth areas. Instructor dashboard artifacts present
the same evidence as a compact HTML dashboard with in-page drilldown panels for
key metrics.

Use this skill with:

- `matlab-tutor-learners`
- `matlab-coach-programming`
- `matlab-create-hands-on-exercises`
- `matlab-create-mcq-practice`
- `matlab-coach-debugging`
- `matlab-log-tutor-sessions`
- `matlab-evaluate-tutor-quality`

## Reporting Principles

- Base the report only on evidence from the current session or provided
  transcript.
- Do not infer grades, exam readiness, or personal traits beyond the evidence.
- Separate observed performance from recommendations.
- Use supportive, factual language that helps the learner plan next steps.
- If a metric is unavailable, write "Not observed" or "Not enough data" rather
  than estimating.
- Keep instructor-shareable notes professional and concise.
- Do not include sensitive personal information unless the learner explicitly
  asks to include it.
- Produce an HTML file by default, not Markdown, unless the user explicitly asks
  for another format.

## Mode Selection

- Use **single-session mode** when the user asks for a report of the current
  session, a provided transcript, or one tutoring interaction.
- Use **aggregate mode** when the user asks for multiple sessions, session
  analytics, progress over time, report aggregation, a date range, or an
  instructor overview across reports.
- Use **dashboard mode** when the user asks for an instructor dashboard,
  dashboard artifact, metric dashboard, drilldown view, or compact overview of
  key metrics across session reports.
- Use **quality dashboard mode** when the dashboard is based on transcript
  reviews or tutor quality reports rather than learner session reports. Include
  MATLAB accuracy, active learning, assignment guardrails, feedback quality,
  debugging support, and transfer prompt metrics.

## Single-Session Report Workflow

1. Identify the session context: topic, course context if given, practice mode,
   and learner goal.
2. Extract topics covered and the evidence for each topic.
3. Summarize learner strengths by topic.
4. Summarize growth areas by topic.
5. Compute activity metrics from observed MCQs, hands-on exercises, and
   debugging tasks.
6. Summarize important MATLAB evidence: script results, Code Analyzer feedback,
   test outcomes, error messages, or output mismatches.
7. Recommend 2-4 next practice actions.
8. Include an instructor-shareable summary if requested or useful.
9. Save the report as an `.html` file using the required filename pattern.

Read [references/report-template.md](references/report-template.md) for the
complete single-session and aggregate report formats, metric definitions, and
date-range rules.

This demo includes an example report at
`assets/examples/session-report-example.html`, relative to the demo folder that
contains `skills/` (not relative to this skill folder). Use it as a
visual and structural example when creating reports, but replace its fictional
session content with evidence from the current session.
When that file is not available (for example when only `skills/` was
installed), follow the template in `references/report-template.md` alone.

## File Naming

Autoname each report:

```text
matlab-ai-tutor-session-YYYY-MM-DD-HHMMSS.html
```

Use the local session start datetime when available (not the report-generation
time). If no session start was recorded, use the report-generation time and say
so in the report header. Use 24-hour time. Omit colons from the time so the
filename is portable across operating systems. Example:

```text
matlab-ai-tutor-session-2026-06-02-143015.html
```

If saving into a course or learner folder, keep this base filename and only
change the directory.

For aggregate reports, use:

```text
matlab-ai-tutor-aggregate-YYYY-MM-DD-to-YYYY-MM-DD.html
```

If the user supplies precise start and end datetimes, use:

```text
matlab-ai-tutor-aggregate-YYYY-MM-DD-HHMMSS-to-YYYY-MM-DD-HHMMSS.html
```

Use the earliest and latest included session dates when no date range arguments
are provided.

For instructor dashboard artifacts, use:

```text
matlab-ai-tutor-dashboard-YYYY-MM-DD-to-YYYY-MM-DD.html
```

If the user supplies precise start and end datetimes, use:

```text
matlab-ai-tutor-dashboard-YYYY-MM-DD-HHMMSS-to-YYYY-MM-DD-HHMMSS.html
```

## Aggregate Report Arguments

Aggregate and dashboard modes accept two optional arguments:

1. `start_datetime`: earliest session report datetime to include.
2. `end_datetime`: latest session report datetime to include.

If both arguments are provided, include session reports whose report datetime is
within the inclusive range. Accept common datetime formats such as
`YYYY-MM-DD`, `YYYY-MM-DD HH:MM`, and `YYYY-MM-DD HHMMSS`.

If no arguments are provided, use all available MATLAB AI Tutor session reports
in the current working directory for this tutoring session. Match files named
like `matlab-ai-tutor-session-YYYY-MM-DD-HHMMSS.html` and exclude aggregate
reports unless the user explicitly asks to include them.

## Aggregate Report Workflow

1. Find candidate single-session HTML reports in the current working directory.
2. Parse each report datetime from the filename first, then from the report
   header if needed.
3. Filter reports by `start_datetime` and `end_datetime` when provided.
4. Extract visible metrics and evidence from the included reports. Do not invent
   missing values.
5. Aggregate topic coverage, MCQ results, hands-on script results, debugging
   tasks, revisi