AGENTS.md

AGENTS.md — как продолжать работу над stem-task-hint

Этот файл — операционная памятка для ИИ-агента, который продолжает проект в новой сессии. Человекочитаемый обзор — в README.md. Прочитай оба, затем skills/stem-hint/SKILL.md и feedback/letnyaya-seriya-2026/results.md (там вся история решений — почему скилл такой, какой есть).

Что это за проект

Разрабатываем stem-hint — harness-независимый скилл, который даёт дозированные подсказки к олимпиадным задачам STEM, НЕ решая их за ученика. Скилл обкатывается на реальных задачах: генерируем карточки подсказок по уже решённым задачам, ученик (дочка пользователя, сильная олимпиадница) оценивает их по трём осям, по фидбеку правим скилл. Цикл повторяется.

Быстрый старт для новой сессии

1. Прочитай SKILL.md, domains/math.md, results.md (история итераций).
2. Спроси у пользователя номер решённой задачи из task-examples/ (или он сам назовёт). Карточки делаем только по решённым задачам.
3. Собери карточку по процессу ниже.
4. После оценки — запиши результат в results.md и обобщи фидбек в правку скилла (см. «Как править скилл»).

Карта репозитория

AGENTS.md                     # этот файл — для агента-продолжателя
README.md                     # обзор — для людей
skills/stem-hint/
  SKILL.md                    # ЯДРО скилла: методология подсказок
  domains/math.md             # доменная справка по математике
  profile-template.md         # опциональный профиль ученика (терминология, темы)
feedback/letnyaya-seriya-2026/
  protocol.md                 # методология обкатки + форма оценки
  results.md                  # результаты всех итераций + разбор + карта правок
  cards/NN.md                 # карточки подсказок по задачам (источник истины)
tools/card-template.html      # шаблон интерактивной карточки (копировать под задачу)
task-examples/                # наборы задач (PDF) — НЕ в репо (личные материалы),
                              # лежат локально; если нет — запросить у пользователя

Скилл: принципы, которые нельзя потерять

Полностью — в SKILL.md. Кратко, чтобы держать в голове:

• Реши → проверь → подсказывай. Сначала САМ реши задачу и проверь (численно/вырожденным случаем). Метка уверенности (verified / partial / unverified) идёт в карточку. Подсказка в неверную сторону хуже, чем никакой.
• Лестница переменной длины. 4 типа подсказок (ориентир → метод → аналог → теория) — это палитра, НЕ обязательный комплект. Ступень включай, только если она несёт концептуальный шаг сверх предыдущих. Пустую ступень — выкидывай (урок задачи 50).
• Информационная цена, а не тип. Порядок ступеней — по возрастанию спойлерности ДЛЯ ЭТОЙ задачи. «Это комбинаторика» и «примени Дирихле» — один тип, разная цена.
• Терминология. Называй факты в традиции ученика (русская школа/кружок), расшифровывай несущие термины инлайн. На ур.1–2 — простой язык без терминов, на ур.3–4 — расшифровывай свободно.
• Честность. Числовой пример фальсифицирует, но не доказывает. Для стандартных фактов сильнее работает атрибуция («это классическое соотношение, есть в учебнике»), для задач-аналогов — гарантия решаемости.

Как собрать карточку для новой задачи

1. Реши приватно и проверь. Реши полностью, проверь численно/вырожденно. Определи метку уверенности. Решение НИКОГДА не попадает в карточку.
2. Найди крукс(ы) — минимум идей, на которых держится решение.
3. Построй лестницу по правилам SKILL.md. Помни про переменную длину: если после называния метода остаётся только вычисление — аналог не нужен.
4. Напиши cards/NN.md (card mode, язык задачи = русский). Формат — как в существующих cards/03.md, cards/50.md.
5. Собери интерактивную страницу: скопируй tools/card-template.html в scratchpad, замени контент (инструкция — в комментарии вверху шаблона). Обязательно уникальный LS_KEY на каждый раунд.
6. Опубликуй артефактом. Проверь целостность: подними локальный http-сервер в scratchpad (python -m http.server PORT) и прогони через javascript_tool (заполнить уровни, проверить гейтинг и генерацию результатов). NB: скриншоты панели таймаутят, file:// в панель не грузится — только локальный http.
7. Отдай ссылку пользователю. Дочка проходит уровни, жмёт «Скопировать результаты», вставляет markdown-таблицу в чат.
8. Запиши и обобщи (ниже).

Как править скилл по фидбеку

• Запиши сырые оценки в results.md новой секцией «Итерация N».
• Обобщай, не оверфить. Каждая правка должна улучшать скилл для ЛЮБОЙ задачи, а не подгонять карточку под один комментарий. Оси фидбека → разделы: неверное направление → протокол «реши→проверь»; спойлерность → калибровка лестницы; «не помогла» → типы/формулировки подсказок; тон → раздел Tone.
• Веди карту «наблюдение → правка» в секции итерации (см. прошлые).

Технические грабли (проверено на практике)

• charset utf-8 в HTML обязателен (в шаблоне уже есть) — иначе кириллица.
• LS_KEY уникален на раунд — иначе браузер подтянет ответы прошлого раунда.
• Скриншоты браузерной панели таймаутят — проверяй через javascript_tool.
• file:// не грузится в панель — используй локальный http.server.
• Браузерная панель бывает целиком недоступна (перебои классификатора) — запасной путь: npm install jsdom в scratchpad и офлайн-прогон логики карточки (гейтинг, раскрытие уровней, генерация markdown, LS_KEY); ошибки scrollIntoView в jsdom — шум (метода там нет), не дефект карточки.
• Артефакты приватные. URL опубликованных карточек — в персональной памяти агента (не в репо, т.к. привязаны к аккаунту пользователя). Чтобы обновить существующий артефакт из новой сессии — передавай его url в вызов Artifact, иначе создастся новый URL.

Текущее состояние (обновляй при каждой итерации)

Дата последнего обновления: 2026-07-19.

• Скилл прошёл 11 итераций (+ доп. 4.5 из обсуждения). Обкатанные задачи: №3 (геометрия, v4), №50 (алгебра, v2), №5 (метод линейного движения, v4 — оценена дважды: правка тона + fallback подтверждены), №35 (комбинаторика, v1 — стресс-тест сухого метакогнитива; тон удержан), №26 (теория чисел, v1 — тон в ТЧ подтверждён; спойлер-пол закрыт с обратной стороны), №48 (алгебра/неравенство, v1 — протокол поймал опечатку в печатном условии; честное примечание принято), №33а (числовой процесс, v2 — мёртвый эксперимент-ориентир вскрыт и удалён; правило линзы), №47 (арифметика средних, v2 — переупакованная ступень вскрыта; правило «одна ступень — один шаг» + пин формы ответа), №33b (числовой процесс / поглощающий класс mod 4, v2 — первая лестница по правилу «одна ступень — один шаг», прошла; вскрыто незаявленное исключение → правило скоупа утверждения).
• Накопленные правки скилла: протокол верификации; терминологические расшифровки + profile-template.md; честность (пример≠доказательство, атрибуция); лестница переменной длины; тон при метакогнитивном крене (итерация 4) — метакогнитивные/ориентирующие подсказки давать сжато, как реплику равного, не разворачивать в пошаговый гайд и не разжёвывать очевидное (иначе тон читается как поучающий); выбор пути при нескольких решениях (итерация 4.5, раздел SKILL.md «Choosing among solution paths») — критерий «меньше случаев» (профиль-фильтр → минимум случаев → тай-брейк), в card mode решать несколько путей, + fallback: текстовая секция «если не пошло — вход в другой путь»; спойлер-пол мелкой задачи (итерация 6, раздел SKILL.md Ladder length) — глубина задачи задаёт нижнюю границу спойлера ур.1: на одношаговой задаче ур.1 неизбежно выдаёт метод (это норма, не дефект), лестница очень короткая, номер нельзя занижать расплывчатостью (=загадка); dismissing ≠ over-explaining (итерация 7, SKILL.md Tone) — закрыть очевидный-но-забываемый случай одной фразой — контент (снимает ветку, на которой застревают), не снисходительность; поучением становится только при развороте в абзац «почему»; посильность поискового ориентира (итерация 8, SKILL.md Ladder п.1) — ориентир, предлагающий поиск объекта (случай равенства, контрпример, экстремальная конфигурация), не обещает непроверенной лёгкости; широкое пространство поиска сужается одной фразой (с учётом её цены в спойлере) — поисковый аналог правила про якорь (анти-загадка); правило линзы (итерация 9, SKILL.md Ladder п.1 + оговорка в Ladder length) — ориентир-эксперимент («разыграй первые ходы, проверь малые случаи») сперва спрашивает, не провёл ли застрявший этот эксперимент уже сам (очевидную первую игру процесса — почти наверняка); голое повторное предписание («сделай и заметишь закономерность») — пустая ступень, загадка в экспериментальной форме; чтобы ступень жила, к эксперименту добавляется линза — признак, за которым следить, — и её цена считается в лестнице; если самая дешёвая работающая линза называет метод — дешёвого ур.1 у задачи нет, честно принять спойлер-пол. Единый принцип трёх правил (якорь / сужатель / линза): ступень 1 передаёт то, чего у ученика ещё нет; израсходованное наблюдение дешёвой ступенью не считается; одна ступень — один шаг / баланс приращений (итерация 10, SKILL.md Ladder, абзац «One rung, one step») — ступень не выдаёт несколько отделимых идей разом (переупакованная ступень = вываливание в форме лестницы: шаг до неё велик, ступени под ней мертвы); многошаговый кандидат делить, лишнее спускать вниз; «новый шаг» оценивается с позиции ученика, усвоившего предыдущие ступени — автоматичное (бухгалтерское ограничение, завершающее вычисление) есть исполнение и ступени не держит; проверка «что осталось найти после этой ступени?» → «только арифметика» = конец лестницы; пин формы ответа (итерация 10, SKILL.md Ladder п.1) — формулировка ориентира-вопроса фиксирует форму ожидаемого ответа («какая именно оценка пришла?», не «что это говорит об оценке?»), чтобы качественный полуответ не удовлетворял вопросу; скоуп утверждения (итерация 11, SKILL.md Honesty rules) — факт в подсказке утверждается в его истинной области: лемму «с одним мелким исключением» не уплощать до абсолютной (сильный ученик проверяет границы, находит протечку и вынужден аудировать подсказку — «вторая проблема» ит.1/2); либо скоупить явно, либо флажить исключение без локализации («одно мелкое исключение есть — найди и проверь, что здесь не мешает») — флажок дёшев и сам является контентом; флажки не размножать на утверждениях без исключений.
• Гипотеза «метод нельзя называть рано» проверена (итерация 4, задача 5). Метод (комплексный инвариант формы + жёсткость дробно-линейной функции) спойлерный — лестница выдержала: метод на ур.2, специфика вниз в ур.3, ур.1 на метакогнитиве; спойлерность росла 1→2→3. Побочка — поучающий тон (см. правку выше).
• Итерация 5 (задача 5 v3, оценена): правка тона подтверждена (тон вернулся к «норм» при неизменном содержании ур.1–3); fallback принят (верное, помогла бы, путь A не спойлерит; спойлер 2). Пойман баг: интро называло альтернативы → карточка v4 (интро обезымянено) + правило в SKILL.md Fallback. Артефакт по ссылке пока со старым интро (v3); перепубликовать v4 — если нужен перепрогон.
• Итерация 6 (задача 35 v1, оценена): правка тона выдержала максимальный метакогнитивный крен комбинаторики (тон «норм», лишнего нет, остановка после ур.1) — сухой метакогнитив устойчив. Новое: спойлер-пол мелкой задачи (ур.1=2, ур.2=3 — интринсик, не дефект) → правка в SKILL.md. Гипотеза 2 (выбор пути + fallback) НЕ выстрелила: задача оказалась одноидейной — механизм корректно промолчал (нет fallback, нет пометки «путь не единственный»).
• Итерация 7 (задача 26 v1, ТЧ, оценена): все три фокуса подтверждены. Тон «норм» на теории чисел — оба названных в SKILL.md Tone домена максимального крена (комбинаторика + ТЧ) пройдены, вопрос тона закрыт. Спойлер-пол закрыт с обеих сторон: на задаче промежуточной глубины с дешёвым ориентиром (чётность), отдельным от метода (старшая степень двойки), ур.1=1 при лестнице из 3 ступеней, монотонность 1→2→3, остановка после ур.2 — новый абзац Ladder length к переукорачиванию не толкнул (контраст-пара с задачей 35 замкнулась). Механизм путей — корректный no-op второй раз (задача одноидейная). Новая правка: dismissing ≠ over-explaining (из комментария к ур.1).
• Итерация 8 (задача 48 v1, неравенство, оценена): первая опечатка в печатном условии, пойманная протоколом «реши → проверь» (строгое «>» опровергается контрпримером-равенством; карточка вела к «⩾» с явным примечанием, точек равенства не называвшим). Примечание принято без кризиса доверия и жалоб на спойлер. Новый тип ориентира ур.1 «найди случай равенства»: спойлер 0 (рекорд обкатки), но «помогла бы: наверное» — подбор труден с позиции застрявшего → правка «посильность поискового ориентира». Спойлер-профиль 0→1→3, остановка после ур.2, тон «норм». Механизм путей — корректный no-op ×3 (задачи 35, 26, 48).
• Итерация 9 (задача 33а v1 → v2, числовой процесс, оценена): первое «помогла бы: НЕТ» за обкатку — на ур.1-эксперименте со спойлером 0 («разыграй дерево на 3–4 хода» с сужателем и проверенной посильностью). Вскрыт новый провал: эксперимент застрявший уже провёл сам, голое повторное предписание без линзы (за чем следить) — пустая ступень с фальшивым обещанием озарения (вторая мёртвая ступень обкатки после аналога задачи 50). Честная половина правки итерации 8 удержана (жалоб на трудность нет). → Правка «правило линзы» (см. накопленные правки). Ошибка классификации спойлер-пола исправлена оговоркой в Ladder length (израсходованное наблюдение — не дешёвая ступень; задача оказалась класса 35, не 26). Спойлер-профиль 0→1→2, остановка после ур.2, тон «норм» (сарказм в комментарии ур.1 — про пустоту содержания, не про тон). Карточка → v2 (лестница из 2 ступеней: метод → ключевой факт); артефакт остался на v1, republish по необходимости. Механизм путей — корректный no-op ×4.
• Итерация 10 (задача 47 v1 → v2, арифметика средних, оценена): вскрыта новая ось калибровки — размер шага между ступенями. Ур.2 нёс три отделимых куска разом (вынужденность + динамика + окно 0..10): «слишком большой шаг между уровнем 1 и уровнем 2», «ничего на уровень 3 уже не остается»; ур.3 (стартовое ограничение) — «пользователь не нуждается: ему всё на уровне 2 рассказали» — третий вид мёртвой ступени (исполнение, убитое переупаковкой предыдущей; первые два — пустой аналог з.50 и сожжённый эксперимент з.33а). → Правки «одна ступень — один шаг» и «пин формы ответа» (см. накопленные). Линза (ит.9) с конструктивной стороны сработала: ур.1 живой, спойлер 1 (контраст с 33а v1), но «наверное» из-за допущенного полупрочтения — отсюда пин формы. Спойлер-профиль 1→2→3 ровно по прогнозу, остановка после ур.2, тон «норм». Карточка → v2 (2 ступени с выровненным шагом); артефакт остался на v1. Механизм путей — no-op ×5.
• Итерация 11 (задача 33b v1 → v2, поглощающий класс mod 4, оценена): первая лестница, собранная по правилу «одна ступень — один шаг», прошла проверку (спойлер 2→3 ровно по прогнозу, ни переупаковки, ни мёртвых ступеней, остановка после ур.1 — вторая такая за обкатку). Пол при израсходованности «соседним пунктом» подтверждён (всё дешёвое сожжено пунктом а) → ур.1 = линза mod 4 со спойлером 2, принят с «да»). Новый урок: ур.2 утверждал ловушку плоско, без исключения (однозначные 2 и 6) — оценщица потребовала («исключение где, уважаемый?») → правка скоуп утверждения (см. накопленные). Карточка → v2 (ур.2 с флажком исключения); артефакт остался на v1. Механизм путей — no-op ×6.
• Что дальше: главное открытое — чистый тест Гипотезы 2: нужна задача с ДВУМЯ сущностно разными путями (напр. биективное + подсчётное доказательство, или игра с двумя инвариантами) — задачи 35, 26, 48, 33а, 47 и 33b его не дали (все одноидейные, no-op ×6). Проверить скоуп утверждения (итерация 11) на следующем леммо-образном хинте (флажок снимается оценкой «да» без роста спойлера; флажки без исключений не плодить — фальшивая загадка). «Одна ступень — один шаг» — первая проверка пройдена (ит.11), следить за обратным перекосом (не дробить один шаг на псевдоступени). Кейс правки итерации 8 «сужатель поднимает "помогла бы" до "да"» на поиске-охоте (не эксперименте) всё ещё не проверен. Следить, чтобы уточнение «dismissing» не читалось как лицензия на разжёвывание (граница — в длине разворота).
• Висит: ничего — итерации 1–11 закоммичены (9–11 одним коммитом: правки переплетены в общих файлах).

Бэклог

• Доменные справки domains/physics.md, chemistry.md, cs.md — после обкатки ядра на разных разделах математики.
• Скилл-«роутер» для выбора доменного модуля — только если модули разрастутся. Пока классификация — шаг внутри ядра; задача «на стыке» подгружает два модуля.

Язык и стиль

• Ядро скилла (SKILL.md, domains/) — по-английски (лучше переносится между моделями), с требованием отвечать на языке задачи.
• Карточки и подсказки — по-русски (язык задач и ученика).
• Общение с пользователем — по-русски, неформально.