matlab-report-tutor-sessions

name	matlab-report-tutor-sessions
description	Use when a learner or instructor asks for a report, summary, reflection, progress note, performance recap, activity metrics, instructor-shareable record of a MATLAB AI tutoring session, aggregate report across multiple MATLAB tutoring session reports, or instructor dashboard artifact with metric drilldowns. Supports optional start and end datetime arguments for multi-session report and dashboard ranges.
license	MathWorks BSD-3-Clause (see LICENSE)
metadata	{"author":"MathWorks","version":"1.0"}

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 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:

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:

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:

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

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

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:

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

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

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, revision behavior, and unresolved growth areas.
6. Identify recurring misconceptions and repeated strengths only when supported by more than one report or by explicit repeated evidence.
7. Include a table of included reports with dates, focus, and evidence basis.
8. Save a standalone HTML aggregate report using the aggregate filename pattern.

Dashboard Artifact Workflow

1. Use the same report discovery, datetime parsing, and date-range filtering as aggregate mode.
2. Build one standalone HTML file. Do not require separate CSV files unless the user explicitly asks for export files or an implementation uses CSV as a temporary intermediate.
3. Show dashboard cards for key metrics. For learner session dashboards, include MCQ accuracy by topic, hands-on script pass rate, common debugging patterns, Code Analyzer issues, and unresolved topics needing instructor follow-up. For tutor quality dashboards, include MATLAB accuracy, active learning, assignment guardrails, feedback quality, debugging support, and transfer prompts.
4. Add drilldown controls for each key metric. Each control should open an in-page panel, modal, or expandable section with the supporting sessions, evidence snippets, affected topics, and recommended instructor action.
5. Include an "Included Reports" section and an "Evidence Limits" section so the instructor can see exactly what was and was not counted.
6. Save the dashboard using the dashboard filename pattern.

Metrics to Track

Track only metrics visible in the session:

• MCQs: attempted, correct, incorrect, skipped, accuracy, most common misconception.
• Hands-on exercises: attempted, completed, passed on first run, passed after revision, unresolved, MATLAB execution result, Code Analyzer issues.
• Debugging tasks: errors investigated, root causes identified, repairs verified, minimal reproductions created.
• Engagement evidence: predictions made, explanations given, tests designed, revisions attempted, transfer tasks completed.

Topic-Level Strengths and Growth Areas

For each major topic, include:

• Topic: MATLAB concept or workflow.
• Evidence: learner answer, code behavior, execution result, or feedback moment.
• Strength: what the learner demonstrated.
• Growth area: what still needs practice.
• Recommended next step: one focused action.

Avoid generic comments such as "needs more practice" without naming the MATLAB behavior to practice.

Instructor-Shareable Notes

When creating an instructor-shareable section:

• Keep it factual and evidence-based.
• Avoid overly personal phrasing.
• Include enough detail to support instructional follow-up.
• Make clear whether the report is based on a complete session transcript or only the visible conversation.

Use this framing:

This report summarizes the observed tutoring session. It is not a formal grade.
Metrics reflect only activities completed in the session.

When Data Is Missing

If the session did not include MCQs, hands-on exercises, or debugging tasks, do not invent metrics. Instead, include:

No MCQs were attempted in this session.
No hands-on MATLAB script was executed in this session.
No debugging task was worked in this session.

Output Length

Default to a concise report that an instructor could skim in 2-3 minutes. If the session was long, multiple reports are included, or the learner asks for detail, include a longer topic-by-topic appendix.