Дополнительные источники: https://github.com/obra/superpowers#when-something-goes-wrong, https://github.com/obra/superpowers/tree/main/skills/diagnosing-superpowers (references/, prompts/, templates/)
Зачем это нужно
Любая система принуждения иногда сбоит: скилл срабатывает не тогда, молчит, когда надо, агент игнорирует план, повторяет работу или сжигает токены. README Superpowers честно признает: «Sometimes a session misbehaves» — иногда сессия ведет себя плохо. Для этого существует скилл diagnosing-superpowers: он разбиратель инцидентов самого Superpowers — переводит жалобу («заняло слишком долго») в отчет с доказательствами и, по запросу, готовит материалы для баг-репорта мейнтейнерам.
Для курса этот скилл показателен вдвойне. Во-первых, это образец диагностики по доказательствам: каждый вывод обязан цитировать path:line — правило, введенное в уроке 17.13, доведено здесь до юридической строгости. Во-вторых, это пример встроенной introspection: система, которая диагностирует собственные сбои и готовит обезличенный пакет для внешнего триажа.
Основная идея
Формула скилла: вы — reporting, не диагностируете Superpowers: «You report; you do not diagnose superpowers. Whoever triages the bundle or the issue decides whether superpowers changes» — вы отчитываетесь; решает, менять ли Superpowers, тот, кто триажирует пакет или issue. Ядро доказательственной дисциплины: «Every finding cites path:line. No citation, no finding» — каждый вывод цитирует путь:строку; нет цитаты — нет вывода. И каждое число — из транскрипта или из команды, которую вы запустили, никогда из памяти.
Как спросить
Из README (раздел When Something Goes Wrong): попросите вашего агента «figure out what went wrong with superpowers in this session» — разобраться, что пошло не так с superpowers в этой сессии; скилл diagnosing-superpowers вызовется сам. Для разбора прошлой сессии — назвать ее: «figure out what went wrong with superpowers in session <id>».
Симптомы и типичные жалобы
Скилл срабатывает по широкому списку признаков (из description): повторная работа, игнорирование плана, «спотыкания» (stumbles), слабые результаты, скилл, который не сработал, «заняло слишком долго», «почему так дорого», «что оно вообще делает». Таблица быстрой маршрутизации скилла — какая жалоба, что читать первым и чем лидировать в вердикте:
| Жалоба | Читать первым, лидировать |
|---|---|
| «Заняло слишком долго» | cost-and-time, stumbles |
| «Почему сделало эту лишнюю работу?» | repeated-work, plan-adherence |
| «Почему так дорого?» | cost-and-time |
| «Что оно делает?!» (еще работает) | skill-timeline; отметить in-progress в покрытии |
| «Игнорировало план» | plan-adherence, сначала строки компакции |
| «Скилл X так и не сработал» | skill-timeline |
Workflow
Семь шагов; todo на каждый; шаги 5-7 — только по своим условиям:
- Problem intake (прием жалобы). Спрашивать по одному вопросу, пока не получится утверждение, называющее: сессию(и), диапазон ходов (если известен), что партнер ожидал, что произошло, и наблюдаемое, которое его волнует (wall-clock, токены, повторные действия, одно конкретное действие). «Заняло слишком долго» — жалоба, не постановка проблемы. Зафиксировать, является ли целью баг-репорт Superpowers.
- Locate (найти сессии). Каждая сессия резолвится в проверенные абсолютные пути на диске (по
references/session-discovery.md); прошлые сессии подтверждаются цитатой первого промпта и таймстампом; перечислить всех отвергнутых кандидатов с причиной или «никого». Перечислить транскрипты сабагентов. Создать~/.superpowers/diagnosing-superpowers/<session-id>/, сообщить путь партнеру, заполнитьtemplates/case.mdпо правилам provenance для наблюдений окружения и скиллов. - Triage (разбор). Область проблемы читается самостоятельно. Затем — по аналитическому сабагенту на измерение, параллельно; каждому — путь к case-файлу,
prompts/analyst-common.mdи один файл измерения изprompts/: skill-timeline, plan-adherence, repeated-work, stumbles, quality-evidence, request-conflicts, cost-and-time. Длинный транскрипт — измерение делится по диапазонам ходов. Найти безpath:line— отбросить. - Report (отчет). Заполнить каждую секцию
templates/report.mdпо порядку, записать в workspace, показать и дать путь. Проверять, что цитируемое действительно доказывает; сопутствующий кейс сохраняется. - GitHub issues — когда отчет §7 говорит possible/likely или партнер просит: поиск открытых и закрытых issues по симптомам (
references/github-issues.md); показать совпадения и предложить приложить отчет к ближайшему; совпадений нет — заполнитьtemplates/issue.md, показать точный текст, создать issue только после одобрения.ghне прикрепляет файлы: есть bundle — дать партнеру путь для прикрепления в браузере. - Export (пакет) — только когда партнер просит; никогда не собирать без запроса. Спросить уровень редакции (redaction): skeleton (без тел результатов тулов), evidence (тела только для цитируемых событий), full. Собрать по
templates/bundle-README.md, прогнатьprompts/scrub.md, затемprompts/scrub-audit.md, повторять оба до CLEAN от аудита. Архивировать (zip -r/tar -czf) только после одобрения; с путем к архиву — что внутри, где scrub-лог, и честная оговорка: обезличивание может промахиваться — просмотреть каждый файл до передачи. - Similar sessions — по запросу: превратить подтвержденные находки в сигнатуру, отобрать кандидатов по mtime/размеру, найти маркерные строки, по кандидату параллельно
prompts/similar-session.md, дописать §9 отчета.
Жесткие правила
- Безопасность контекста: одна строка транскрипта может быть мегабайтом —
references/context-safety.mdна каждом файле сессии, каждый раз. - Read-only: никогда не изменять, не перемещать, не удалять файл сессии.
- Сабагентам — точные пути: «текущая сессия» сабагента — его собственная; передавать абсолютные пути и id.
- Только человеческие промпты: вывод хуков, system reminders и результаты тулов — не слова партнера; в транскрипте сабагента «user» — родительский агент.
- Не диагностировать Superpowers: §7 отчета констатирует вовлеченность и останавливается; называть дефект скилла или предлагать изменение запрещено — «партнер давит на фикс» не отменяет правило: указать на шаг issue и упомянуть, что bundle доступен по запросу. Советов партнеру — тоже нет.
- Ворота одобрения: нет архива до просмотра партнером scrub-лога и списка файлов; нет issue/комментария до одобрения их точного текста.
- Intake прежде анализа: шаги 2-7 не начинаются до ответа партнера; партнер далеко — написать вопросы и остановиться; утверждение, реконструированное за него, — не ответ. Уже-скоупированный запрос (одно конкретное событие; что сейчас работает; какой анализ прогнать) — сам является утверждением: ответить и спрашивать дальше. «Почему за всю сессию» — жалоба, не постановка.
Красные флаги
Выборка таблицы скилла:
| Мысль | Реальность |
|---|---|
| «Проблема очевидна, intake пропущу» | Постановка проблемы скоупирует все. Спросить. |
| «Партнер далеко, реконструирую заявление сам» | Вы не можете реконструировать, чего он хотел. Написать вопросы и остановиться. |
| «Прочитаю все сейчас, спрошу в конце» | Нескоупированный sweep тратит бюджет партнера не на тот вопрос. Сначала спросить. |
| «Цель — баг-репорт, соберу bundle сразу» | Bundle — данные его сессии, упакованные. Собирать только по его просьбе. |
| «Мелкая правка, реструктурировать нечего» | Не ваше решение, какой бы мелкой она ни была. Доказательства — триажеру. |
| «Цена за токен хорошо известна» | Числа, не посчитанные из транскрипта, — выдуманные. Цитировать или убрать. |
Типичный сбой: потеря бутстрапа после компакции
Практически важный кейс, стыкующийся с уроком 17.4: в каркасах без post-compaction hook (README приводит Hermes) очень длинная сессия, скомпактившаяся в первом ходу, теряет бутстрап — скиллы перестают срабатывать. Рекомендация README: если скиллы перестали срабатывать — начать свежую сессию. Диагностически это первый кандидат при жалобе «скилл X не сработал» в конце длинной сессии: искать строки компакции (маршрут plan-adherence из таблицы).
Пример структуры отчета
По templates/report.md (структура, не полный перевод): секции идут по порядку — от постановки проблемы через покрытие (какие ходы и транскрипты прочитаны) и измерения (семь аналитиков) до §7 — «вовлеченность Superpowers» (констатация, без диагноза) и последующих секций для issue/bundle/similar-sessions. Отчет пишется в workspace, показывается партнеру, путь — ему.
Практика
- Сформулируйте для своей «проблемной» сессии (реальной или гипотетической) постановку проблемы по правилам шага 1: сессия(и), диапазон ходов, ожидание, факт, наблюдаемое. Проверьте: это утверждение или жалоба?
- Для симптома «агент повторно выполнил задачу 3» составьте план разбора по таблице маршрутизации: что читать первым, какие измерения подключить, где искать строки компакции.
- Напишите запрос на диагностику с id сессии и просьбой собрать bundle уровня evidence. Какие ворота одобрения вы пройдете до архива?
Краткое резюме
diagnosing-superpowers — разбор инцидентов самого Superpowers: принять жалобу → превратить в постановку → найти и подтвердить сессии → семь аналитиков параллельно → отчет с path:line у каждого вывода → по условиям — issue и обезличенный bundle.
- Роль — reporting, не диагноз: «меняет ли Superpowers» решает триажер; скилл называет вовлеченность и останавливается.
- Intake прежде анализа: реконструированное за партнера заявление — не заявление; нескоупированный sweep — трата не туда.
- Ворота одобрения: архив — после просмотра scrub-лога и списка; issue — после одобрения точного текста.
- Жалоба «скиллы перестали срабатывать» в длинной сессии — первый кандидат: потеря бутстрапа после компакции (каркасы без post-compaction hook).
Вопросы для самопроверки
- Почему скиллу запрещено ставить диагноз самому Superpowers? Какая роль остается у него и кто решает вопрос об изменениях?
- Что означает «Every finding cites
path:line»? Приведите находку, которая была бы отброшена. - Опишите шаг intake. Чем «уже-скоупированный запрос» отличается от жалобы и как скилл поступает с каждым?
- Какие три уровня редакции (redaction) предлагает сборка bundle и что включает каждый?
- Какие ворота одобрения стоят перед архивацией и перед созданием issue?
- Свяжите потерю бутстрапа после компакции с механикой урока 17.4: что именно теряется и почему свежая сессия лечит?
Что дальше
Качество и диагностика разобраны; следующий урок, 17.15, открывает финальный блок: writing-skills — TDD-методология написания собственных скиллов и политика контрибуции в Superpowers.