/article-structure-review

name: article-structure-review
description: |
  Проверить структуру технической статьи после черновика: задача читателя, жанр,
  опора значимых утверждений на доказательства и честные ограничения.
  Use after the first draft, before publication. Исправлять структуру, когда это
  входит в запрос; не создавать обязательный конвейер из других навыков.
  Для локальной языковой редактуры — humanize-english или humanize-russian.
metadata:
  version: "2.0.0"
  reviewed: "2026-09-06"

Структурный review технической статьи

Проверяй, помогает ли статья выполнить обещанную читателю задачу и поддержаны ли её существенные выводы. Количество иллюстраций, длины абзацев и отношение тезисов к примерам сами по себе не измеряют достоверность.

Вход и границы

Используй существующий запрос, черновик, первичные материалы и правила площадки. Не запускай все смежные writing-навыки подряд: подключай только нужный для конкретного оставшегося дефекта. Запрос «проверить» означает review без правок; «исправить/подготовить/опубликовать» включает соответствующую работу.

1. Задача читателя и жанр

| Жанр | Что должно быть понятно | |---|---| | Reference | где найти факт, условие, контракт или действие | | Tutorial | исходные условия, шаги, результат и проверка | | Analysis | данные, метод, вывод и границы переноса | | Story | что действительно произошло и чему научился автор | | Opinion | что является позицией автора и чем она обоснована |

Выбери основной жанр из запроса и назначения текста, не из привычки. Смешение допустимо, если читатель понимает переход. Не превращай справочник в историю или отчёт в рекламный материал, чтобы он выглядел «живее».

Для каждой секции назови её пользу читателю. Определение, таблица или короткий блок могут быть достаточны; им не требуется выдуманная личная история.

2. Тезис и соответствующее доказательство

Различай факт, предположение, вывод из данных, проектную рекомендацию и гипотетический пример. Подбирай основание по типу утверждения.

| Утверждение | Подходящее основание | Чего недостаточно | |---|---|---| | API ведёт себя так | текущая документация нужной версии или реальный probe | похожий пример другой версии | | изменение исправляет дефект | failing case и свежая проверка изменённого пути | компиляция или объяснение автора | | результат получен в продукте | соответствующий runtime/result receipt | source review, макет, синтетический тест | | метод быстрее | сопоставимый baseline, условия и измерение | субъективное впечатление | | подход рекомендуется | явно названные условия и инженерное обоснование | представление мнения как доказанного закона | | событие произошло с автором | реально предоставленное свидетельство | правдоподобный придуманный рассказ |

Источник должен подтверждать конкретное утверждение, а не просто быть о той же теме. Код иллюстрирует механизм; его наличие не доказывает правильность или запуск. Гипотетический пример помогает объяснить, но не заменяет наблюдение.

Не требуй фиксированного отношения 2:1, трёх чисел или отдельного примера под каждым определением. При нехватке основания сузь тезис, проверь источник в рамках исследовательской задачи либо обозначь неизвестное. Не заполняй пробел вымышленной метрикой, цитатой, личным опытом или статусом PASS.

3. Ограничения и статус готовности

Технический текст должен ясно сообщать существенные ограничения своего вывода: версию, область применимости, неподтверждённый runtime, допущения и компромиссы. Для статьи о собственном инструменте/подходе удобен отдельный блок ограничений. В коротком справочнике условия можно поставить непосредственно рядом с правилом.

Не придумывай поломку «после 10K записей» или ложную скромность ради раздела. Не прячь известную зависимость только потому, что она внешняя. Назови её влияние. Различай «проверено в исходнике», «прошёл fixture», «установлено» и «работает в нужном сценарии». Сильнее имеющегося доказательства статус не становится.

4. Организация без искусственных квот

• Порядок секций следует задаче: необходимый контекст перед зависимым выводом.
• Повтор полезен для точного термина или параллельного сравнения; повтор того

же вывода без новой информации обычно можно убрать.

• Разгружай середину, если читатель теряет ход мысли, а не потому что превышен

произвольный процент тезисов.

• Не максимизируй дисперсию длин абзацев. Один цельный абзац может быть лучше

нескольких искусственно разрубленных.

• Добавляй таблицу/схему только когда она заметно проясняет сравнение, связи,

иерархию или последовательность. Не дублируй уже ясную прозу картинкой.

• Длинные самостоятельные примеры выноси только если это нужно структуре

площадки; не плодить отдельный файл ради формального прохождения проверки.

5. Закрытие редакторского этапа

Для каждого существенного замечания назови место, нарушенную задачу читателя или неподдержанный тезис и конкретную правку. При разрешённой редактуре внеси её, затем перепроверь затронутый смысл и ссылки. Независимый reviewer нужен для рискованных/спорных утверждений по принятому процессу, не бесконечно.

Если критерии статьи выполнены, редакторский этап закончен. Продолжай оставшуюся запрошенную публикацию; файл с замечаниями или успешное review её не заменяют. Не заявляй видимость статьи по одному Git-коммиту.

Gotchas

• **Пример вместо доказательства:** убедительный вымысел не подтверждает факт.
• **Арифметический стиль-гейт:** отношения и квоты заставляют раздувать уже

достаточный текст. Проверяй понимание и смысл.

• **Смена жанра:** личная история не обязательна для reference.
• **Переоценка готовности:** source/fixture/install/runtime — разные утверждения.
• **Review self-feed:** повтор без изменённого риска тормозит реальную публикацию.

Troubleshooting

| Симптом | Причина для проверки | Действие | |---|---|---| | много тезисов, мало оснований | утверждения сильнее источников | проверить, сузить или обозначить гипотезу | | читатель теряется в середине | пропущен переход или предпосылка | переставить/у