grade-report

name	grade-report
description	Use when analyzing class grades — анализ успеваемости класса, отчёт по успеваемости, средний балл, качество знаний, группа риска. Accepts XLSX/CSV from electronic journals (МЭШ, Дневник.ру, ЭлЖур, Сетевой Город) or simple `ФИО,5,4,3,...`. ФИО анонимизированы в LLM-промптах.
argument-hint	[путь к XLSX/CSV/JSON, или 'ввести вручную']
allowed-tools	Read, Write, Skill, mcp__plugin_teacher-assistant_teacher__grade_analytics

Анализ успеваемости и отчёт

Данные: $ARGUMENTS

Принципы

1. Учительский UX: учитель не должен ничего пересохранять. Принимаем XLSX напрямую из электронного журнала (МЭШ, Дневник.ру, Сетевой Город, ЭлЖур), а также CSV/TSV/JSON.
2. Анонимизация в LLM-промпте: в общении с моделью используем псевдонимы Ученик #1, Ученик #2, ... — реальные ФИО приходят из инструмента только в name_map и никогда не отправляются в LLM-сообщения. Реальные имена попадают только в локальный файл-отчёт через Write.
3. Двухслойный анализ: статистика (числовая) + аналитика поверх (паттерны, динамика). Чётко разделяй: «слой 1 — что считает grade_analytics», «слой 2 — что увидел я как читатель данных».

Шаги

Шаг 1. Получить данные

• Если в $ARGUMENTS путь к файлу — переходи к шагу 2.
• Если «ввести вручную» — предложи учителю упрощённый формат ФИО,оценка1,оценка2,... и сохрани во временный CSV.

Шаг 2. Вызвать grade_analytics

mcp__plugin_teacher-assistant_teacher__grade_analytics(
  data_path: "<file>",
  metrics: ["average", "quality", "success_rate", "distribution",
            "students_at_risk", "top_students", "attendance"],
  anonymize: true     // ← по умолчанию true; не отключай, если учитель явно не попросит
)

Если учитель явно спросит за конкретный период или по конкретному типу работ, добавь параметры:

period: "q2"               // или date_from / date_to для произвольного диапазона
work_type: ["КС", "КР"]    // например, только классные сочинения и контрольные

Шаг 3. Fallback при total_students == 0

Если grade_analytics вернул пустой результат — это значит формат файла непривычный (новая система или ручной XLSX). Не показывай ошибку учителю, сделай тихий fallback:

1. Прочитай файл напрямую через Read (для XLSX используй Read с извлечением текста; для CSV — текстовое чтение).
2. Нормализуй данные «по смыслу»: в твоём контексте есть ФИО и последовательности отметок 2-5/Н/Б. Преобразуй в простой формат ФИО,оценка1,оценка2,... и запиши во временный файл /tmp/grades_normalized_<класс>.csv через Write.
3. Повторно вызови grade_analytics с этим временным файлом.
4. Учителю показывай результат как обычно — не упоминай fallback.

Шаг 4. Сформировать отчёт

Структура отчёта (см. подробный шаблон в templates/grade-report.md):

1. Общая статистика

• средний балл по классу,
• качество знаний (% на 4-5),
• успеваемость (% без 2),
• распределение отметок (5, 4, 3, 2),
• посещаемость (Н/Б) если есть.

2. Индивидуальный анализ — слой 1 (по статистике)

• ученики на 4-5 (top_students) — рекомендация: олимпиады, проекты, роль наставника;
• хорошисты, среднеуспевающие, на грани (между 3.0 и 3.5) — мониторинг;
• группа риска (students_at_risk с reason: "low_average") — индивидуальная работа, дифференциация;
• не-аттестованные (reason: "not_attested") — выяснить причины, организовать индивидуальную аттестацию.

3. Индивидуальный анализ — слой 2 (паттерны, поверх статистики)

То, что не видит базовая статистика, но видит читатель данных. Применяй только если в данных есть даты (поле date у grades):

• синхронные изменения — несколько учеников показывают одинаковую динамику (например, у 4 учеников после 7-го урока — провал). Сформулируй педагогические гипотезы (общее событие, психологическая реакция на формат работы, социальная динамика). Никогда не утверждай причину — предлагай для проверки классным руководителем.
• прогресс отдельного ученика — оценки растут от начала к концу периода. Это часто упускается за усреднением.
• провалы по типу работ — например, если средний по work_type=КС на 1 балл ниже общего, это сигнал по подготовке к сочинениям.

4. Рекомендации (содержательные приоритеты для учителя)

5. Сводная карточка для пятиминутной планёрки с завучем

6. Что делал плагин и где заканчивается его ответственность

Дай учителю явное разделение «слой 1 — числовая статистика плагина», «слой 2 — анализ ИИ поверх данных». И зафиксируй: «истинную причину аномалий определит только живой разговор с детьми».

Шаг 5. Анонимизация в LLM ↔ ФИО в файле

Внутри ответов и обоснований используй псевдонимы из основного вывода grade_analytics («Ученик #1»). При записи итогового MD-отчёта в файл учителя — разреши себе использовать реальные ФИО из name_map, потому что файл локальный, не отправляется в LLM. Технически:

1. собери текст отчёта с псевдонимами,
2. в самый последний шаг перед Write сделай замену Ученик #N → name_map["Ученик #N"] локально,
3. запиши файл отчёт_успеваемость_<класс>.md. Если учитель попросит DOCX — вызови встроенный anthropic-skills:docx с параметрами ГОСТ из .claude/rules/document-formatting.md.

Если учитель явно сказал «работай с псевдонимами и в файле» (например, для отправки во внешнюю систему) — оставь псевдонимы.

Шаг 6. Self-validation перед завершением

Перед тем как сообщить учителю «готово», убедись, что в выходном MD-отчёте есть:

• Класс
• Предмет (явно или из metadata)
• Период (II четверть, или диапазон дат)
• Привязка к нормативной базе (ФГОС / ФОП / ФРП)
• Чётко обозначенный слой 1 vs слой 2 (что от плагина, что от ИИ)
• Рекомендации, не диагнозы
• Никаких ФИО реальных учеников в твоих сообщениях, только в файле

Поддерживаемые форматы файлов

• XLSX — основной путь. Прямой экспорт из ЭлЖур / МЭШ / Дневник.ру / Сетевого Города. С шапкой и multi-line ячейками.
• CSV/TSV — авто-разделитель , ; \t; авто-кодировка UTF-8 / UTF-8 BOM / Windows-1251.
• Простой CSV ФИО,5,4,3,... — для быстрых вводов.
• JSON [{student, grades}] — для интеграций.

Шаблоны отчётов

templates/grade-report.md — структура с примерами заполнения.

Эталонный кейс

/test-fixtures/grades/grades_8b_literature_q2_full.csv (8Б, литература, II четверть 2025-2026): 25 учеников, 334 отметки, средний 3.22, в данных заложен паттерн «синхронное снижение четвёрки» — учеников 8Б-13..16 после 7-го урока. Хороший плагин-ИИ должен этот паттерн увидеть.