article-structure-review

name

Article Structure Review

description

Структурный self-review технической статьи перед публикацией. Покрывает три дыры, которые не ловятся точечными скиллами типа humanize/infostyle: thesis/proof balance, жанровая чистота, обязательный блок ограничений. Применяется ПОСЛЕ написания первого черновика, ПЕРЕД humanize + infostyle. Основано на фидбеке реальных читателей на опубликованные статьи - классический паттерн "много тезисов / мало доказательств" и отсутствие честного блока про то, что не решено. Use AFTER first draft is done, BEFORE word-level audits.

Структурный review статьи

Когда применять

Между завершением черновика и финальным текстовым аудитом. Порядок:

1. jtbd-content - ПЕРЕД написанием (job statement, target state)
2. draft-narrative-purity - во время (код/деревья в technical-examples)
3. article-structure-review - ПОСЛЕ первого черновика ← этот skill
4. infostyle-audit - после структуры (усилители, zero-info)
5. humanize-russian / humanize-english - финал (LLM-маркеры)
6. {platform}-guide - подгонка под платформу

1. Thesis/Proof Balance (главная проверка)

Правило: каждый значимый тезис должен сопровождаться одним из:

• Конкретный пример из личного опыта
• Цифра с контекстом (число, процент, длительность, стоимость)
• Case study: ситуация → что пробовали → результат
• Код-сниппет (один, короткий, в тему)
• Ссылка на источник с указанием в чём именно согласны

Антипаттерн: 3+ тезиса подряд без ни одного proof-элемента.

Механический тест

Взять каждую H2-секцию. Пройтись по абзацам. Для каждого:

• Сколько тезисов (утверждений про свойство/преимущество/правило)?
• Сколько proof-элементов (из списка выше)?

Если отношение тезис/proof выше 2:1 в секции - пересобрать.

Примеры правки

Плохо (тезис без доказательства)	Хорошо (тезис + доказательство)
"Правила помогают избежать катастроф"	"Правило 'не менять localhost-адреса без контекста' появилось после того, как агент заменил SNI-proxy на реальный IP и сломал upload"
"Векторный поиск хуже графа"	"Эмбеддинги для карточек по 500-2000 токенов - lossy-сжатие: похожие на вектор карточки могут быть про разные домены, а operationally-adjacent карточки (Kafka + Python profiling) семантически далеки"
"Структура помогает"	"После ввода handoff между сессиями за 4 дня накопилось 27 переходов - ни один тупик не повторился"

2. Жанровая чистота

Статья обслуживает один основной жанр. Выбирается ДО написания:

Жанр	Характер	Пример заголовка
Story	Хронология, от лица автора, с неудачами	"Как я сломала прод и что нашла"
Reference	Факты, таблицы, паттерны	"Checklist: развёртывание K8s cluster"
Analysis	Данные → вывод, сравнения	"3 метода context compaction: бенчмарк"
Rant/Opinion	Точка зрения, аргументы	"Почему RAG - это regression"
Tutorial	Пошаговая инструкция	"Fine-tune модели за 4 часа"

Смешение жанров допустимо, если явно обозначить:

"Часть 1 - история как я столкнулась с проблемой. Часть 2 - разбор архитектуры."

Не обозначить = читатель теряется: "зачем это здесь? где закончилась одна тема и началась другая?"

Симптомы жанрового сбоя

• Читатель (или feedback-читатель) спрашивает "зачем этот блок?"
• Середина статьи визуально тяжёлая (перегруз другого жанра)
• Заголовок обещает одно, тело даёт другое
• Нет сквозной линии "зачем я это читаю"

Тест

Прочитать ТОЛЬКО первые абзацы каждой H2-секции. Читаются как одна последовательная мысль или как разрозненные блоки? Если блоки - определить где жанр сменился, обозначить явно или переписать в один жанр.

3. Блок ограничений (ОБЯЗАТЕЛЬНЫЙ)

Секция "Что НЕ решено / Чего не знаю / Где сломается" - обязательна в конце любой технической статьи про собственный инструмент / подход / систему.

Что туда писать

• Границы масштабирования: "при 10K+ записей это сломается, потому что..."
• Непроверенные гипотезы: "Не уверена что принцип X работает вне моего use case"
• Tradeoffs: "Это стоит N - если у вас меньше бюджет, смотрите на ..."
• Известные дыры: "Семантическое протухание не ловится автоматически"
• Пределы личного опыта: "Не тестировала на production scale"

Что туда НЕ писать

• Ложная скромность ("я не профи, но...") - не информативно
• Внешние проблемы не под твоим контролем ("LLM иногда тупят")
• Преодолимые ограничения без оценки сложности

Почему обязательна

• Читатель доверяет больше, когда видит границы явно
• Антидот к "рекламному тону" - ограничения показывают, что автор думал, а не хайпил
• Коммуникация уровня зрелости: "готов к критике по этим пунктам"
• Удерживает от publishing "половины решения" как "готовой системы"

4. Paragraph Variety

Правило: длины абзацев должны скакать. 1-sentence абзац ок, 5-sentence ок, но не три 3-sentence подряд.

Антипаттерн ИИ

Три абзаца одинаковой длины ~3 предложения каждый, каждый начинается с глагола или "Moreover/Также/Кроме того", каждый содержит ровно один тезис + пол-доказательства. Характерный ритм "тыры-пыры" - LLM-generated.

Тест

Взять статью, посчитать длины абзацев в основной части. Стандартное отклонение должно быть > среднего. Если "все абзацы по 3-4 предложения" - ручная пересборка: часть объединить, часть разбить, одно предложение вынести в отдельный абзац для акцента.

5. Middle-Section Overload

Симптом: в середине статьи один блок перегружен тезисами/концепциями - сложнее читать, чем начало и конец.

Причина: автор вырос в понимании темы за время написания, в середину положил самые интересные/глубокие мысли, а уровень контекста читателя не вырос.

Тест

Посчитать количество тезисов по секциям. Если середина содержит > 40% всех тезисов при 33% веса - разгружать:

• Вынести часть в technical-examples.md или в отдельную статью
• Добавить visual aid (схема, таблица, график)
• Разбить одну большую секцию на две

6. Visual vs Prose Check

Правило: если объясняешь структуру данных, архитектуру, связи - покажи визуал, не проза.

Прозой лучше: идеи, последовательности действий, личные истории, аргументация.

Визуалом лучше:

• Связи между сущностями (граф, диаграмма)
• Распределение по категориям (таблица, pie chart)
• Иерархия (tree)
• Временная последовательность (timeline, swim-lane)
• Сравнение (side-by-side таблица)
• Архитектура (block diagram)

Тест

Каждую секцию которая описывает структуру - спросить "можно ли это одной картинкой показать яснее, чем абзацами?". Если да - заменить.

Чеклист перед сдачей в infostyle/humanize

• Жанр определён и выдержан (или смешение обозначено)
• Отношение тезис/proof в каждой секции не выше 2:1
• Секция "Что не решено / Ограничения" присутствует
• Длины абзацев разные, не три одинаковых подряд
• Середина не перегружена относительно начала и конца
• Структурные блоки визуализированы (таблица/схема/граф), не описаны прозой
• Каждая H2-секция имеет чёткий "зачем она тут" (связь с JTBD)

Источник

Сформирован по фидбеку реальных читателей на опубликованные технические статьи. Характерные замечания, которые регулярно ловят LLM-ассистированные черновики:

• "Мало конкретных примеров при большом количестве тезисов"
• "Местами рекламный и слишком уверенный тон"
• "Перегруженность середины"
• "Не хватает блока с ограничениями подхода"
• "Некоторые части непонятно для чего - лучше картинку приложить"

Этот skill формализует ответ на такие замечания, чтобы следующая статья не повторяла те же ошибки.