---
name: article-structure-review
description: |
  Структурный self-review технической статьи перед публикацией. Покрывает три дыры,
  которые не ловятся точечными скиллами типа humanize/infostyle:
  thesis/proof balance, жанровая чистота, обязательный блок ограничений.
  Применяется ПОСЛЕ написания первого черновика, ПЕРЕД humanize + infostyle.
  Основано на фидбеке реальных читателей на опубликованные статьи - классический паттерн
  "много тезисов / мало доказательств" и отсутствие честного блока про то, что не решено.
  Use AFTER first draft is done, BEFORE word-level audits.
  Do NOT use for word-level / sentence-level style fixes or removing AI-generation markers
  (use humanize-english or humanize-russian for that); this skill only reviews macro-structure
  (thesis/proof balance, genre purity, limitations block), not phrasing.
---

# Структурный 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 формализует ответ на такие замечания, чтобы следующая статья не повторяла те же ошибки.
