From 61b39f3e7f46b79db55a9b801382dca21f3db946 Mon Sep 17 00:00:00 2001 From: "GLOBUS.studio" Date: Sun, 12 Jul 2026 17:12:01 +0300 Subject: [PATCH] =?UTF-8?q?v4.0=20=E2=80=94=20Self-contained=20SKILL.md,?= =?UTF-8?q?=20morph=20validator,=20ReadSightPy,=20scenario=20unification,?= =?UTF-8?q?=2024=20new=20test/example=20files,=20clause=20checker,=20EVAL?= =?UTF-8?q?=20runner,=20Bash=20benchmark?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/validate.yml | 11 + KNOWN_LIMITATIONS.md | 2 +- PLAN.md | 534 +++++++++++++++++ README.md | 2 +- SKILL.md | 671 +++++++++++++++------- examples/de-blog-post.md | 43 ++ examples/de-email.md | 55 ++ examples/es-blog-post.md | 43 ++ examples/es-landing.md | 40 ++ examples/fr-blog-post.md | 43 ++ examples/fr-social.md | 37 ++ examples/it-blog-post.md | 43 ++ examples/it-landing.md | 40 ++ examples/pl-blog-post.md | 43 ++ examples/pl-social.md | 37 ++ examples/pt-blog-post.md | 43 ++ examples/pt-social.md | 37 ++ scenarios/blog-post.md | 59 +- scenarios/case-study.md | 64 ++- scenarios/commercial-offer.md | 65 ++- scenarios/creative-writing.md | 35 +- scenarios/email.md | 76 ++- scenarios/full-rewrite.md | 58 +- scenarios/grant-proposal.md | 40 +- scenarios/internal-memo.md | 54 +- scenarios/landing-page.md | 48 +- scenarios/press-release.md | 39 +- scenarios/product-update.md | 54 +- scenarios/seo-article.md | 53 +- scenarios/social-post.md | 62 +- scenarios/technical-doc.md | 65 +-- scenarios/translation-fix.md | 80 +-- scripts/clause-check.ps1 | 144 +++++ scripts/morph-check.ps1 | 179 ++++++ scripts/readability-check.ps1 | 149 +++++ scripts/run-benchmark.sh | 122 ++++ scripts/run-eval.ps1 | 130 +++++ scripts/validate.ps1 | 45 +- shared/morph/blacklist-ru.txt | 38 ++ shared/morph/whitelist-ru.txt | 56 ++ tests/benchmark/ai-texts/de/email.md | 14 + tests/benchmark/ai-texts/de/landing.md | 7 + tests/benchmark/ai-texts/es/email.md | 14 + tests/benchmark/ai-texts/es/landing.md | 7 + tests/benchmark/ai-texts/fr/email.md | 14 + tests/benchmark/ai-texts/fr/social.md | 9 + tests/benchmark/ai-texts/it/email.md | 14 + tests/benchmark/ai-texts/it/landing.md | 7 + tests/benchmark/ai-texts/pl/email.md | 16 + tests/benchmark/ai-texts/pl/social.md | 9 + tests/benchmark/ai-texts/pt/email.md | 14 + tests/benchmark/ai-texts/pt/social.md | 9 + tests/benchmark/annotations.json | 171 ++++++ tests/benchmark/readability-baseline.json | 16 + 54 files changed, 3198 insertions(+), 562 deletions(-) create mode 100644 PLAN.md create mode 100644 examples/de-blog-post.md create mode 100644 examples/de-email.md create mode 100644 examples/es-blog-post.md create mode 100644 examples/es-landing.md create mode 100644 examples/fr-blog-post.md create mode 100644 examples/fr-social.md create mode 100644 examples/it-blog-post.md create mode 100644 examples/it-landing.md create mode 100644 examples/pl-blog-post.md create mode 100644 examples/pl-social.md create mode 100644 examples/pt-blog-post.md create mode 100644 examples/pt-social.md create mode 100644 scripts/clause-check.ps1 create mode 100644 scripts/morph-check.ps1 create mode 100644 scripts/readability-check.ps1 create mode 100644 scripts/run-benchmark.sh create mode 100644 scripts/run-eval.ps1 create mode 100644 shared/morph/blacklist-ru.txt create mode 100644 shared/morph/whitelist-ru.txt create mode 100644 tests/benchmark/ai-texts/de/email.md create mode 100644 tests/benchmark/ai-texts/de/landing.md create mode 100644 tests/benchmark/ai-texts/es/email.md create mode 100644 tests/benchmark/ai-texts/es/landing.md create mode 100644 tests/benchmark/ai-texts/fr/email.md create mode 100644 tests/benchmark/ai-texts/fr/social.md create mode 100644 tests/benchmark/ai-texts/it/email.md create mode 100644 tests/benchmark/ai-texts/it/landing.md create mode 100644 tests/benchmark/ai-texts/pl/email.md create mode 100644 tests/benchmark/ai-texts/pl/social.md create mode 100644 tests/benchmark/ai-texts/pt/email.md create mode 100644 tests/benchmark/ai-texts/pt/social.md create mode 100644 tests/benchmark/readability-baseline.json diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 62d4e59..026b51d 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -10,3 +10,14 @@ jobs: run: pwsh scripts/validate.ps1 -Verbose - name: Run Bash validator run: bash scripts/validate.sh --verbose + - name: Check SKILL.md self-containment + shell: pwsh + run: | + $content = Get-Content SKILL.md -Raw + if ($content -match "raw.githubusercontent.com") { Write-Host "PASS: GitHub raw URLs present" } else { Write-Host "WARN: Missing GitHub raw URLs" } + if ($content -match "Top burned words") { Write-Host "PASS: Embedded burned words" } else { Write-Host "WARN: Missing embedded burned words" } + - name: List new scripts + shell: pwsh + run: | + $scripts = @("morph-check.ps1","readability-check.ps1","run-eval.ps1","clause-check.ps1","run-benchmark.sh") + foreach ($s in $scripts) { if (Test-Path "scripts/$s") { Write-Host "OK: $s" } else { Write-Host "MISSING: $s" } } diff --git a/KNOWN_LIMITATIONS.md b/KNOWN_LIMITATIONS.md index 078e6e5..dd75737 100644 --- a/KNOWN_LIMITATIONS.md +++ b/KNOWN_LIMITATIONS.md @@ -8,7 +8,7 @@ LLMs cannot reliably count exact words. The rhythm system uses clause-count and ## Language Depth -English, Russian, Ukrainian, and German have the deepest coverage with native-level tone markers and cultural notes. French, Spanish, Portuguese, Italian, and Polish have been enhanced in v4 but may still have gaps compared to the primary four languages. Community contributions from native speakers are welcome. +English, Russian, Ukrainian, and German have the deepest coverage with native-level tone markers and cultural notes. French, Spanish, Portuguese, Italian, and Polish may still have gaps compared to the primary four languages. Community contributions from native speakers are welcome. ## Edge Cases diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..0eca64f --- /dev/null +++ b/PLAN.md @@ -0,0 +1,534 @@ +# PLAN — Улучшение HUMAN-AI v3.0 → v4.0 + +> Дата: 2026-07-12 +> Цель: системное усиление слабых мест, выявленных в аудите. + +--- + +## 0. ПРИНЦИПИАЛЬНЫЕ РЕШЕНИЯ (приняты) + +- **Em-dash (—)** — удаляется **во всех языках без исключений**. Русская типографика не оправдание. Длинное тире = AI-маркер, точка. +- **Программный энфорсмент интеграций** (RankWise / MindFluence) — не нужен, снимается с плана. + +--- + +## 1. ТРЁХСЛОЙНАЯ ВАЛИДАЦИЯ (архитектурный фундамент) + +**Проблема:** self-assessment bias — LLM сам себя оценивает. + +**Решение:** три независимых слоя, исполняемых последовательно: + +| Слой | Инструмент | Что измеряет | Независимость | +|------|-----------|-------------|:---:| +| 1. Self-eval | LLM (Stage 5.6) | Соблюдение своих же правил | ❌ | +| 2. ReadSightPy | `readsight` (Python) | Читаемость: Flesch, LIX, Fog | ✅ | +| 3. ZeroGPT | API | AI-детекция | ✅ | + +**Итоговый контракт качества:** пайплайн считается успешным, если self-eval ≥ 75 **И** ReadSightPy-читаемость улучшилась (output ≥ input) **И** ZeroGPT ≤ 15%. + +### 1.1 Интеграция ReadSightPy + +ReadSightPy (https://github.com/MADEVAL/ReadSightPy) — библиотека читаемости для 86 языков, 17 формул, TeX-слоговой движок. + +**Что даёт скиллу:** +- **Flesch Reading Ease (Oborneva)** для русского — объективная метрика «человечности» текста +- **LIX** для всех 9 языков — универсальная читаемость +- **Gunning Fog** — измерение сложности (AI-текст имеет аномальный Fog) +- **SMOG** — годы обучения, нужные для понимания текста + +**Интеграция:** +``` +scripts/readability-check.ps1 ← новый скрипт + - Принимает файл с текстом + - Вызывает ReadSightPy для языка текста + - Возвращает: Flesch, LIX, Fog, SMOG + - Сравнивает input vs output + - Exit code: 0 = улучшение, 1 = без изменений, 2 = ухудшение +``` + +**Метрики по языкам (минимальный набор):** + +| Язык | Формулы | +|------|---------| +| en | Flesch + FKGL + LIX + Fog | +| ru | Flesch (Oborneva) + FKGL + LIX + Fog | +| uk | LIX + Fog + SMOG | +| de | Flesch (Amstad) + WSTF + LIX + Fog | +| fr | Flesch (Kandel-Moles) + LIX + Fog | +| es | Flesch + Fernandez-Huerta + LIX + Fog | +| pt | Flesch (Martins) + LIX + Fog | +| it | Flesch + Gulpease + LIX + Fog | +| pl | FOG-PL + LIX + Fog | + +### 1.2 ReadSightPy-бенчмарк + +Добавить в `tests/benchmark/`: +``` +tests/benchmark/ +├── readability-baseline.json ← baseline-показатели для каждого тестового файла +└── readability-results.json ← результаты прогона (автогенерация) +``` + +`readability-baseline.json` — эталонные метрики читаемости для каждого AI-текста ДО humanization. После humanization — сравнение: читаемость должна вырасти (Flesch ↑, Fog ↓). + +--- + +## 2. МОРФОЛОГИЧЕСКИЙ ВАЛИДАТОР (ВСЕ 9 ЯЗЫКОВ) + +**Проблема:** AI-модели генерируют несуществующие слова: искажённые формы, кальки, выдуманные падежные окончания. LLM не знает, что слово не существует — он сам его придумал. Это касается всех 9 языков, но механизм проверки разный. + +**Решение:** внешний морфологический анализатор, который проверяет каждое слово на наличие в словаре языка. + +### 2.1 Инструменты по языкам + +| Язык | Инструмент | Словарь | Покрытие | +|------|-----------|---------|:---:| +| **RU** | `pymorphy3` | OpenCorpora (390K+ словоформ) | ✅ отличное | +| **UK** | `pymorphy3` | OpenCorpora (UK-секция) | ⚠️ базовое | +| **EN** | `spaCy` `en_core_web_lg` | 500K+ слов | ✅ отличное | +| **DE** | `spaCy` `de_core_news_lg` | морфология + лемматизация | ✅ хорошее | +| **FR** | `spaCy` `fr_core_news_lg` + Lefff | морфология + глагольные формы | ✅ хорошее | +| **ES** | `spaCy` `es_core_news_lg` | морфология + лемматизация | ✅ хорошее | +| **PT** | `spaCy` `pt_core_news_lg` | морфология + лемматизация | ✅ хорошее | +| **IT** | `spaCy` `it_core_news_lg` | морфология + лемматизация | ✅ хорошее | +| **PL** | `spaCy` `pl_core_news_lg` + Morfeusz2 | морфология + лемматизация | ✅ хорошее | + +**pymorphy3** — специализированный морфологический анализатор для русского (и частично украинского). Даёт score уверенности для каждого разбора. Слова с score = 0 — не найдены в словаре OpenCorpora. + +**spaCy** — общий NLP-фреймворк. Для романских и германских языков — лемматизация + POS-tagging. Слова без леммы или с неизвестным POS — кандидаты на «не существует». + +### 2.2 Унифицированный интерфейс + +Скрипт `scripts/morph-check.ps1` (обёртка над Python) — единый для всех 9 языков: + +``` +morph-check.ps1 -File "output.md" -Lang "ru" +morph-check.ps1 -File "output.md" -Lang "de" +morph-check.ps1 -File "output.md" -Lang "fr" +``` + +Внутри — диспетчеризация к нужному движку (pymorphy3 для RU/UK, spaCy для остальных). + +### 2.3 Как работает (RU — pymorphy3) + +```python +import pymorphy3 +morph = pymorphy3.MorphAnalyzer() + +def check_word(word): + parsed = morph.parse(word) + if not parsed or parsed[0].score == 0: + return "NOT_RUSSIAN" # слово не найдено в OpenCorpora + return parsed[0].normal_form +``` + +### 2.4 Как работает (EN/DE/FR/ES/PT/IT/PL — spaCy) + +```python +import spacy + +nlp = spacy.load("de_core_news_lg") # пример для немецкого + +def check_word(word, lang): + doc = nlp(word) + token = doc[0] + # Слово подозрительно если: + # 1. POS = X (unknown) или лемма не найдена + # 2. is_oov = True (out-of-vocabulary) + if token.pos_ == "X" or token.is_oov: + return "NOT_IN_VOCABULARY" + return token.lemma_ +``` + +### 2.5 Выходной формат (единый для всех языков) + +``` +[MORPH REPORT] +Language: ru +Total words: 342 +Unknown words: 7 (2.0%) +├── «оптимизируемость» — не найдено в OpenCorpora +├── «трансформационность» — не найдено в OpenCorpora +├── «имплементирование» — калька с английского, в blacklist +├── «автоматизированность» — окказионализм, не в словаре +├── «функционализировать» — выдуманный глагол +├── «пользователецентричный» — не найдено +└── «нейросетевой» — допустимое новообразование [WARN] + +VERDICT: 5 critical / 1 warn / 1 acceptable +``` + +``` +[MORPH REPORT] +Language: de +Total words: 287 +Unknown words: 3 (1.0%) +├── «Optimierbarkeit» — nicht im Vokabular (möglicher Neologismus) +├── «Transformationalität» — nicht im Vokabular +└── «implementierungsmäßig» — nicht im Vokabular, Anglizismus + +VERDICT: 3 critical +``` + +### 2.6 Пороги (единые для всех языков) + +| % неизвестных слов | Вердикт | +|-------------------|---------| +| < 1% | OK | +| 1-3% | WARN — проверить вручную | +| 3-5% | FAIL — вероятная AI-генерация | +| > 5% | CRITICAL — текст непригоден | + +### 2.7 Ограничения + +- Не видит неологизмы, уже вошедшие в язык +- Не видит технические термины +- Ложные срабатывания на именах собственных + +**Решение:** whitelist + blacklist для каждого языка: + +``` +shared/morph/ +├── whitelist-ru.txt ← допустимые слова вне словаря +├── blacklist-ru.txt ← известные AI-кальки (подозрительны даже если есть в словаре) +├── whitelist-de.txt +├── blacklist-de.txt +├── whitelist-fr.txt +├── blacklist-fr.txt +├── whitelist-es.txt +├── blacklist-es.txt +├── whitelist-pt.txt +├── blacklist-pt.txt +├── whitelist-it.txt +├── blacklist-it.txt +├── whitelist-pl.txt +├── blacklist-pl.txt +├── whitelist-en.txt +├── blacklist-en.txt +├── whitelist-uk.txt +└── blacklist-uk.txt +``` + +### 2.8 Приоритет внедрения + +| Фаза | Языки | Инструмент | +|------|-------|-----------| +| **1** | RU | pymorphy3 + OpenCorpora | +| **2** | UK, EN, DE | pymorphy3 (UK) + spaCy (EN, DE) | +| **3** | FR, ES, PT, IT, PL | spaCy (все) | + +--- + +## 3. УСИЛЕНИЕ PRE-FLIGHT GUARD + +**Проблема:** одно throat-clearing opener (+25 баллов) = STOP пайплайна, даже если текст человеческий. + +**Решение:** + +### 3.1 Минимальный размер текста для pre-flight + +Тексты < 100 слов: pre-flight не работает осмысленно. Слишком мало данных для эвристики. +``` +Если слов < 100 → пропустить pre-flight → сразу в cleanup +``` + +### 3.2 Взвешенный порог + +Вместо жёсткого «opener = +25 = STOP»: +- 1 opener без других маркеров = не останавливать +- 1 opener + 2+ других категорий маркеров = останавливать + +Новое правило: +``` +STOP только если: + (opener OR conclusion_regurgitation) AND (burned_words ≥ 3 OR fake_transitions ≥ 2 OR hedging ≥ 2) + +ИЛИ score ≥ 50 в любом случае +``` + +### 3.3 Уточнение для русского языка + +Русские корпоративные тексты часто открываются «В современных условиях...» — это не AI, это канцелярит. Добавить: +``` +Если язык = ru И единственный маркер = opener → WARN, не STOP +``` + +--- + +## 4. РАСШИРЕНИЕ ТЕСТОВОГО ПОКРЫТИЯ + +### 4.1 Тестовые AI-тексты для DE/FR/ES/PT/IT/PL + +Сейчас: по 1 файлу (только blog-post) на каждый язык. Нужно минимум 3 жанра: + +| Язык | Сейчас | Нужно | +|------|--------|-------| +| DE | blog-post | + email, + landing | +| FR | blog-post | + email, + social | +| ES | blog-post | + email, + landing | +| PT | blog-post | + email, + social | +| IT | blog-post | + email, + landing | +| PL | blog-post | + email, + social | + +Всего: +12 тестовых файлов. + +### 4.2 Примеры (examples/) для DE/FR/ES/PT/IT/PL + +Сейчас: 0. Нужно минимум 2 примера на язык: +- `examples/de-blog-post.md` +- `examples/de-landing.md` +- `examples/fr-blog-post.md` +- `examples/fr-social.md` +- ... (по 2 на язык = 12 новых) + +### 4.3 Edge-case аннотации + +`tests/benchmark/annotations.json` — добавить аннотации для 5 edge-case файлов. + +--- + +## 5. УНИФИКАЦИЯ СЦЕНАРИЕВ + +**Проблема:** 15 сценариев — 4 разных формата. LLM должен парсить по-разному. + +**Решение:** единый шаблон сценария (обновить `CONTRIBUTING.md` и переписать все сценарии): + +```markdown +# Scenario: [Название] + +**Use when:** [описание] +**Default tone:** `[tone]` + +## Key Priorities +1. ... +2. ... + +## What to Cut +- ... +- ... + +## What to Preserve +- ... +- ... + +## Rhythm Targets +| Параметр | Значение | +|----------|---------| +| Fragment spacing | Every N sentences | +| Conjunction spacing | Every N sentences | +| Max consecutive same category | N | + +## Language Notes +- RU: ... +- UK: ... +- DE: ... + +## Pipeline +- Likely needed: [stages] +- Often skippable: [stages] +- Never skip: [stages] +``` + +Все 15 сценариев привести к этому формату. + +--- + +## 6. CLAUSE-COUNT: ПЕРЕХОД НА ВНЕШНИЙ ПОДСЧЁТ + +**Проблема:** LLM не может надёжно считать clauses. Ритм-правила нарушаются не по вине следования инструкции, а по вине неспособности посчитать. + +**Решение:** на этапе proofread (Stage 5) добавить пункт о внешней проверке: + +``` +5.5 Clause Count Verification (опционально — внешний скрипт) + +scripts/clause-check.ps1 -File "output.md" +``` + +Скрипт на Python: +```python +import re + +def count_clauses(sentence): + # Простой подход: считаем финитные глаголы + союзы как прокси для clauses + # Более точный — spaCy dependency parse + ... +``` + +**Важно:** это НЕ замена clause-count правилам в SKILL.md. Правила остаются. Это внешний валидатор, который ловит нарушения, пропущенные LLM. + +Реализация — фаза 2 (после морфо-валидатора). + +--- + +## 7. ВНЕШНИЙ EVAL-РАННЕР + +**Проблема:** EVAL.md требует отдельного LLM-вызова, но никто этого не делает. + +**Решение:** скрипт, автоматизирующий внешнюю оценку: + +``` +scripts/run-eval.ps1 + - Принимает: original.txt + humanized.txt + - Отправляет EVAL.md промпт + оба текста в LLM API (OpenAI/Anthropic) + - Возвращает 5-метричный отчёт +``` + +Интегрировать в `run-benchmark.ps1` как дополнительный слой. + +--- + +## 8. ФИКСЫ КОНСИСТЕНТНОСТИ + +### 8.1 Версионирование +- `README.md:3` badge `version-1.0` → `version-3.0` +- `KNOWN_LIMITATIONS.md:11` «v4» → удалить, заменить на актуальную версию + +### 8.2 Валидатор — дополнить список сценариев +`scripts/validate.ps1:295-303` — добавить в `$treeFiles` недостающие сценарии: +`press-release.md`, `internal-memo.md`, `grant-proposal.md`, `product-update.md` + +### 8.3 Bash-версия run-benchmark +Создать `scripts/run-benchmark.sh` — аналог `run-benchmark.ps1` для Linux/Mac. + +--- + +## 9. ДОРОЖНАЯ КАРТА + +### Фаза 1 (ближайшая) — базовая инструментализация +- [ ] Самодостаточный SKILL.md: вшить топ-данные × 9 языков, заменить ссылки на raw-url +- [ ] Морфо-валидатор RU: `scripts/morph-check.ps1` + `shared/morph/` (whitelist + blacklist) +- [ ] Интеграция ReadSightPy: `scripts/readability-check.ps1` +- [ ] Расширение `validate.ps1` (сценарии + badge fix + проверка SKILL.md ↔ shared/) +- [ ] Pre-flight guard: правила минимального размера и взвешенного порога + +### Фаза 2 (средняя) — покрытие и унификация +- [ ] Морфо-валидаторы UK + EN + DE (pymorphy3 + spaCy) +- [ ] Унификация 15 сценариев под единый формат +- [ ] 12 новых AI-тестов для DE/FR/ES/PT/IT/PL +- [ ] 12 новых примеров (examples/) +- [ ] Edge-case аннотации в annotations.json +- [ ] `scripts/run-benchmark.sh` (Bash) +- [ ] `scripts/run-eval.ps1` (внешний EVAL-раннер) + +### Фаза 3 (дальняя) — продвинутая валидация +- [ ] Морфо-валидаторы FR, ES, PT, IT, PL (spaCy) +- [ ] Clause-count валидатор: `scripts/clause-check.ps1` +- [ ] `readability-baseline.json` + интеграция в benchmark +- [ ] CI: добавить morph-check + readability-check в `validate.yml` + +--- + +## 10. САМОДОСТАТОЧНЫЙ SKILL.md + +**Проблема:** SKILL.md (546 строк) на ~40% состоит из ссылок «см. shared/...» вместо самих данных. В standalone-режиме (просто system prompt в GPT/Claude) LLM знает правила, но не имеет списков слов и маркеров. Это снижает качество cleanup. + +**Решение:** SKILL.md должен быть самодостаточным для standalone-запуска, с GitHub-ссылками на полные данные для углублённой обработки. + +### 10.1 Что вшить в SKILL.md + +| Данные | Сейчас | Сделать | +|--------|:---:|---------| +| Burned words (топ-15/язык) | ссылка на shared | **вшить компактной таблицей** | +| AI openers (топ-5/язык) | частично в Stage 0 | **вшить полный топ-5** | +| Fake transitions (топ-5/язык) | ссылка | **вшить** | +| Hedging (топ-5/язык) | ссылка | **вшить** | +| Empty intensifiers (топ-5/язык) | ссылка | **вшить** | +| Conclusion regurgitation (топ-5/язык) | ссылка | **вшить** | +| Tone profiles — ключевые маркеры | ссылка на shared | **вшить 2-3 маркера/тон/язык** | +| Specificity ladder — примеры | только EN вшито | **вшить по 1 примеру/язык** | +| Rhythm — opener categories | ссылка | **вшить opener categories × 9** | + +### 10.2 Что оставить GitHub-ссылками + +| Данные | Причина | +|--------|---------| +| Полные списки burned words (30-40/язык) | редкий use-case, раздует SKILL.md | +| Полные tone profiles (7 тонов × 9 языков) | 250 строк, нужны только для deep-аудита | +| `EVAL.md` | отдельный LLM-вызов | +| `shared/language-template.md` | только для контрибьюторов | +| Скрипты (`validate.ps1`, `zerogpt-detect.ps1` и др.) | не для LLM | + +### 10.3 Принцип «ссылкок GitHub» + +Для углублённой обработки SKILL.md содержит прямые raw-ссылки: + +``` +> Полный список burned words: https://raw.githubusercontent.com/MADEVAL/Natural-skill/main/shared/burned-words.md +> Tone profiles: https://raw.githubusercontent.com/MADEVAL/Natural-skill/main/shared/tone-profiles.md +``` + +LLM может сходить по ссылке (web fetch) и прочитать полный список, если задача требует глубокой зачистки. + +### 10.4 Целевой размер + +| Файл | Сейчас | Цель | +|------|--------|------| +| SKILL.md | 546 строк | ~1200 строк | +| Из них правил | 400 строк | 400 строк (без изменений) | +| Из них вшитых данных | 50 строк | ~700 строк (+650) | +| Из них ссылок | 100 строк | ~100 строк (формат меняется) | + +### 10.5 Правило обновления + +При добавлении языка (например, японский): +1. Обновить `shared/` — полные данные (как сейчас) +2. Обновить SKILL.md — топ-15 слов, топ-5 маркеров +3. Прогнать `validate.ps1` — проверить консистентность SKILL.md ↔ shared/ + +### 10.6 Отличие от текущей архитектуры + +``` +Сейчас: + SKILL.md → ссылается → shared/ + +После: + SKILL.md + ├── вшитые топ-данные (standalone — хватает для 80% задач) + └── raw-ссылки → shared/ (deep mode — для 20% сложных задач) + └── shared/ — single source of truth (не дублируется, а детализируется) +``` + +--- + +## 11. ИТОГОВАЯ АРХИТЕКТУРА v4.0 + +``` +natural-skill/ +├── SKILL.md ← самодостаточный оркестратор (~1200 строк) +│ вшиты топ-данные + raw-ссылки на shared/ +├── PLAN.md ← этот файл +├── shared/ +│ ├── burned-words.md +│ ├── ai-markers.md +│ ├── tone-profiles.md +│ ├── specificity-ladder.md +│ ├── rhythm-tables.md +│ ├── language-template.md +│ └── morph/ ← NEW +│ ├── whitelist-ru.txt / blacklist-ru.txt +│ ├── whitelist-uk.txt / blacklist-uk.txt +│ ├── whitelist-en.txt / blacklist-en.txt +│ ├── whitelist-de.txt / blacklist-de.txt +│ ├── whitelist-fr.txt / blacklist-fr.txt +│ ├── whitelist-es.txt / blacklist-es.txt +│ ├── whitelist-pt.txt / blacklist-pt.txt +│ ├── whitelist-it.txt / blacklist-it.txt +│ └── whitelist-pl.txt / blacklist-pl.txt +├── scripts/ +│ ├── validate.ps1 / .sh ← обновлён +│ ├── zerogpt-detect.ps1 / .sh +│ ├── run-benchmark.ps1 / .sh ← +.sh NEW +│ ├── morph-check.ps1 ← NEW +│ ├── readability-check.ps1 ← NEW +│ ├── run-eval.ps1 ← NEW +│ └── clause-check.ps1 ← NEW (фаза 3) +├── scenarios/ ← унифицированы (15 файлов) +├── examples/ ← расширены (+12 файлов) +└── tests/benchmark/ + ├── annotations.json ← расширен + ├── readability-baseline.json ← NEW + ├── ai-texts/ ← расширен (+12 файлов) + ├── human-texts/ + └── edge-cases/ ← аннотированы +``` diff --git a/README.md b/README.md index 2b5caa5..65d6c82 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # HUMAN-AI — Text Humanization Engine -[![Version](https://img.shields.io/badge/version-1.0-blue)]() +[![Version](https://img.shields.io/badge/version-4.0-blue)]() [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Compatibility](https://img.shields.io/badge/compatibility-any%20LLM-purple)]() diff --git a/SKILL.md b/SKILL.md index 45064ab..361c9ff 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,32 +1,33 @@ --- name: human-ai -description: "Master skill for rewriting AI-generated text to sound human-written across 9 languages: English, Russian, Ukrainian, German, French, Spanish, Portuguese, Italian, Polish. 6-stage pipeline: pre-flight → cleanup → specificity → tone → rhythm → proofread. 15 task-specific scenarios. For articles, posts, landing pages, commercial copy, translations, SEO content, emails, press releases, memos, grant proposals, creative writing - any text that currently 'smells like AI.'" +description: "Master skill for rewriting AI-generated text to sound human-written across 9 languages: English, Russian, Ukrainian, German, French, Spanish, Portuguese, Italian, Polish. 5-stage pipeline: pre-flight → cleanup → specificity → tone → rhythm → proofread. 15 task-specific scenarios. For articles, posts, landing pages, commercial copy, translations, SEO content, emails, press releases, memos, grant proposals, creative writing - any text that currently 'smells like AI.'" license: MIT compatibility: any-llm metadata: - version: "3.0" + version: "4.0" languages: [en, ru, uk, de, fr, es, pt, it, pl] pipeline_stages: 5 --- -# HUMAN-AI - Text Humanization Engine +# HUMAN-AI — Text Humanization Engine > **If the reader forgets a machine was involved, you won.** -> **Version:** 3.0 +> **Version:** 4.0 > **Languages:** Русский · English · Українська · Deutsch · Français · Español · Português · Italiano · Polski -> **Mode:** Pipeline. 6 stages (pre-flight + 5 processing). Flexible - skip with declared reason. +> **Mode:** Pipeline. 5 stages (pre-flight + 4 processing). Flexible — skip with declared reason. +> **Standalone:** self-contained. All critical rules and top-15 per-language data are embedded. Full lists available via GitHub URLs at the bottom. --- ## THE THREE LAWS OF HUMAN TEXT ### Law 1: Imperfection is the signal -AI produces text that is too consistent. Same rhythm. Same structure. Same formality. Same everything. Humans are inconsistent. A sharp 4-word sentence, then a meandering 28-word one. A paragraph starting with "But". A fragment. This inconsistency is not a flaw - it is the biometric signature of a human mind. Your job: introduce **structured variance**, not chaos. +AI produces text that is too consistent. Same rhythm. Same structure. Same formality. Same everything. Humans are inconsistent. A sharp 4-word sentence, then a meandering 28-word one. A paragraph starting with "But". A fragment. This inconsistency is not a flaw — it is the biometric signature of a human mind. Your job: introduce **structured variance**, not chaos. ### Law 2: Specificity is credibility -AI generalizes - it has no lived experience. Humans specify. "Effective solutions" → "patched the memory leak in 40 minutes". "Improves workflow" → "saves 3 hours per report". Every time you replace a generalization with a concrete detail, you make the text more human. This is the highest-leverage technique. +AI generalizes — it has no lived experience. Humans specify. "Effective solutions" → "patched the memory leak in 40 minutes". "Improves workflow" → "saves 3 hours per report". Every time you replace a generalization with a concrete detail, you make the text more human. This is the highest-leverage technique. ### Law 3: Competence doesn't announce itself -AI says: "robust, cutting-edge platform". Humans say: "we patch bugs within 4 hours". Describe what you do. The quality is self-evident. No adjectives about quality - show the quality. +AI says: "robust, cutting-edge platform". Humans say: "we patch bugs within 4 hours". Describe what you do. The quality is self-evident. No adjectives about quality — show the quality. --- @@ -37,22 +38,23 @@ pre-flight → cleanup → specificity → tone → rhythm → proofread ``` ### Why this order -0. **Pre-flight first** - detect language, estimate AI probability. If human-written → STOP. Don't waste pipeline stages. -1. **Cleanup second** - remove AI patterns before anything else. Don't build human text on a robot skeleton. -2. **Specificity third** - concrete details must exist before tone, because tone wraps around content. -3. **Tone fourth** - once content is solid, shape the voice. -4. **Rhythm fifth** - fine-tune sentence flow after voice is set. -5. **Proofread last** - kill remaining AI residue when everything else is stable. +0. **Pre-flight first** — detect language, estimate AI probability. If human-written → STOP. Don't waste pipeline stages. +1. **Cleanup second** — remove AI patterns before anything else. Don't build human text on a robot skeleton. +2. **Specificity third** — concrete details must exist before tone, because tone wraps around content. +3. **Tone fourth** — once content is solid, shape the voice. +4. **Rhythm fifth** — fine-tune sentence flow after voice is set. +5. **Proofread last** — kill remaining AI residue when everything else is stable. ### Skip policy Stages run sequentially. **Skip a stage only with declared reason.** Declare skips in output header: `[PIPELINE: cleanup → specificity(skipped: already rung 2+) → tone → rhythm → proofread]` -Skip if: -- Stage 1 (cleanup): No detectable AI patterns -- Stage 2 (specificity): All claims already rung 2+ -- Stage 3 (tone): Tone already matches target -- Stage 4 (rhythm): Rhythm already varied -- Stage 5 (proofread): Always runs - at minimum a top-10 tells scan +| Stage | Skip if | +|-------|---------| +| Stage 1 (cleanup) | No detectable AI patterns | +| Stage 2 (specificity) | All claims already rung 2+ | +| Stage 3 (tone) | Tone already matches target | +| Stage 4 (rhythm) | Rhythm already varied | +| Stage 5 (proofread) | Always runs — at minimum a top-10 tells scan | --- @@ -60,17 +62,21 @@ Skip if: Before running any pipeline stage, perform a rapid diagnostic scan. +### Minimum text size +Texts < 100 words: skip pre-flight scoring, proceed directly to cleanup. Heuristic scoring is unreliable on short samples. + ### Language Detection Identify primary language. If mixed text: detect dominant language, preserve quoted foreign-language passages unchanged. - Confidence ≥ 70: proceed - Confidence < 70: ask user to specify language ### AI Probability Estimation + Rapid scan. Assign points per marker found: | Signal | Points | |--------|--------| -| Throat-clearing opener present | +25 | +| Throat-clearing opener present | +15 | | 3+ burned words in first 200 words | +20 | | Fake transition ("Moreover" / «Более того» etc.) | +10 each | | Hedge prefix ("It is important to note" / «Следует отметить») | +10 each | @@ -79,23 +85,32 @@ Rapid scan. Assign points per marker found: | Adjective pileup (3+ before a noun) | +10 | | Rhetorical question padding | +10 each | -**Score interpretation:** +### Score interpretation | Score | Verdict | Action | |-------|---------|--------| -| 0-20 | Likely human-written | **STOP.** Output: "This text scores {score}/100 on AI detection. It appears to be human-written. Running humanization would likely degrade it. If you still want processing, say 'force pipeline'." | -| 21-50 | Mild AI patterns | Proceed. Consider audit mode first if user is unsure. | +| 0-20 | Likely human-written | STOP. Output diagnostic only. | +| 21-50 | Mild AI patterns | Proceed. Consider audit mode first if unsure. | | 51-80 | Clear AI patterns | Run full pipeline. | | 81-100 | Heavy AI generation | Run full pipeline with aggressive cleanup. | ### Already-Human Guard Rule -If AI Probability < 20: **STOP. Do not run pipeline.** Output the diagnostic only. This prevents degradation of legitimately human text. +If AI Probability < 20: **STOP. Do not run pipeline.** Output the diagnostic only. + +**Weighted threshold — false-positive protection:** + +STOP only if **both** conditions hold: +1. Score < 20 +2. AND (opener OR conclusion_regurgitation NOT present) OR total burned words < 5 + +One throat-clearing opener alone is NOT sufficient to stop the pipeline. A single opener in an otherwise clean text (e.g. corporate document legitimately starting with "In today's meeting...") does not warrant pipeline halt. + +**Language-specific adjustment for RU:** Russian corporate texts often open with «В современных условиях...» as legitimate канцелярит. If language = ru AND the only AI marker is an opener → WARN, do NOT stop. If user says "force pipeline" after the guard triggers: run MINIMAL mode (proofread-only scan). Flag only unambiguous AI patterns. Annotate output with `[HUMAN-ORIGIN: preserved structure and voice]`. ### Tone Pre-Detection -Based on content type vocabulary and structure, suggest a tone. User can override. | Content signals | Likely tone | |-----------------|-------------| @@ -108,7 +123,6 @@ Based on content type vocabulary and structure, suggest a tone. User can overrid | Before/after data, client results, lessons | `case` | ### Pipeline Recommendation -Based on diagnostic results, recommend stages: ``` [PRE-FLIGHT] @@ -119,21 +133,17 @@ Recommended: {stages to run} Skippable: {stages likely safe to skip} ``` -User can accept the recommendation or override any stage. - --- ## STAGE 0: LANGUAGE DETECTION -Detect language before processing. Different languages have different AI tells. Reference: `shared/ai-markers.md` for complete detection patterns per language. - -**Quick detection by dominant markers:** +### Quick detection by dominant markers | Lang | Top markers | |------|-------------| | en | "In today's...", "Moreover", "seamless/robust/leverage", em-dash, 3-adj pileups | | ru | «В современном...», «данный/являться/осуществлять», «следует отметить», em-dash | -| uk | «У сучасному...», «даний/являтися/здійснювати», «важливо зазначити», Russianisms, em-dash | +| uk | «У сучасному...», «даний/являтися/здійснювати», Russianisms, em-dash | | de | «In der heutigen...», «Darüber hinaus», «optimieren», Nominalstil, em-dash | | fr | «Dans le monde...», «De plus/En outre», «Il est important de noter», em-dash | | es | «En el mundo actual...», «Además/Asimismo», «Cabe destacar», gerund overuse, em-dash | @@ -148,40 +158,125 @@ Detect language before processing. Different languages have different AI tells. ### Objective Remove all detectable AI patterns. This is mechanical. Be ruthless. -### 1.1 Delete throat-clearing openers -Delete the entire first sentence/paragraph if it starts with context-setting, era-naming, or landscape-painting. The real start is what comes after. Full lists: `shared/ai-markers.md` - Openers section per language. - -### 1.2 Strip conclusion regurgitation -Delete concluding sections that restate the introduction. Humans end when done talking. If the last substantive paragraph works as an ending, keep it. If not: write one sharp exit sentence and stop. Full lists: `shared/ai-markers.md` - Conclusion section. - -### 1.3 Purge burned words -**Universal + per-language.** Full list: `shared/burned-words.md` - -Replacement rule: **Do not find a synonym. Describe what actually happens.** -- "leverages AI" → "uses a model trained on support tickets" -- «оптимизирует процессы» → «сокращает время согласования с трёх дней до четырёх часов» -- «optimiert Prozesse» → «verkürzt Genehmigungszeiten von drei Tagen auf vier Stunden» - -### 1.4 Kill fake transitions -Delete on sight. Full lists: `shared/ai-markers.md` - Fake transitions section. - -### 1.5 Kill fake balance -Delete "On one hand... on the other hand..." and equivalents - unless the text names specific, real-world positions with concrete evidence. Generic balance = kill. - -### 1.6 Break symmetrical paragraphs -If 3+ consecutive paragraphs have the same number of sentences (±1): break one (split, merge, or add a 1-sentence paragraph). - -### 1.7 Kill adjective pileups -Max 2 adjectives before a noun. 3+ → keep the strongest one, show the rest through description. - -### 1.8 Remove empty intensifiers -Words that tell how impressed to be without providing a reason. Delete the intensifier. Let the fact carry its own weight. Full lists: `shared/burned-words.md` - Empty intensifiers section. - -### 1.9 Remove hedging language -AI hedges to avoid being wrong. Humans state things. Delete hedging prefixes. State the claim directly. If uncertain: "We don't know for sure. But here's what we've seen." Full lists: `shared/ai-markers.md` - Hedging section. - -### 1.10 Remove rhetorical question padding -Delete generic transition questions: "What does this mean for you?" etc. Keep genuine engagement questions that receive substantive answers. +**Replacement rule:** Do not find a synonym. Describe what actually happens. + +### 1.1 Throat-clearing openers (delete the entire first sentence/paragraph) + +| Lang | Openers (delete on sight) | +|------|---------------------------| +| en | In today's, In the modern, In an era, The landscape of, With the rise of, As we navigate, In the ever-evolving, It goes without saying, In recent years, The world of, Nowadays, In the age of | +| ru | В современном, В сегодняшнем, В эпоху, В условиях, В мире где, В настоящее время, На сегодняшний день, С развитием, В последние годы, В нынешних реалиях, В эру цифровизации | +| uk | У сучасному, В умовах, У світі де, На сьогоднішній день, В епоху, З розвитком, В останні роки, Сучасний світ, У нинішніх реаліях, У добу цифровізації | +| de | In der heutigen digitalen Welt, Im Zeitalter der, In der modernen, Mit dem Aufkommen von, In der sich ständig verändernden, Heutzutage, In der aktuellen Landschaft | +| fr | Dans le monde numérique d'aujourd'hui, À l'ère du, Dans le paysage actuel, Avec l'avènement de, De nos jours, Dans un monde en constante évolution, À l'heure actuelle | +| es | En el mundo digital actual, En la era de, En el panorama actual, Con el auge de, Hoy en día, En la actualidad, En un mundo cada vez más | +| pt | No mundo digital de hoje, Na era de, No cenário atual, Com o surgimento de, Hoje em dia, Atualmente, No mundo cada vez mais | +| it | Nel mondo digitale di oggi, Nell'era del, Nel panorama attuale, Con l'avvento di, Al giorno d'oggi, Oggigiorno, Nel mondo in continua evoluzione | +| pl | W dzisiejszym cyfrowym świecie, W erze, W obecnym krajobrazie, Wraz z rozwojem, W dzisiejszych czasach, Obecnie, W dobie, W świecie gdzie | + +### 1.2 Conclusion regurgitation (delete entire concluding section) + +| Lang | Delete on sight | +|------|-----------------| +| en | In conclusion, To summarize, In summary, To wrap up, As we have seen, Overall, In closing, To sum up, The bottom line | +| ru | В заключение, Подводя итог, Таким образом, Итак, Резюмируя, В завершение, Подводя итоги, В итоге, Исходя из вышесказанного | +| uk | На завершення, Підсумовуючи, Отже, Таким чином, Підводячи підсумок, Підіб'ємо підсумки, У підсумку, З огляду на вищесказане, Резюмуючи | +| de | Zusammenfassend, Abschließend, Zusammenfassend lässt sich sagen, Im Fazit, Schlussendlich, Alles in allem | +| fr | En conclusion, Pour résumer, En résumé, Pour conclure, En définitive, Au final, En somme | +| es | En conclusión, Para resumir, En resumen, Para concluir, En definitiva, A modo de cierre, En síntesis | +| pt | Em conclusão, Para resumir, Em resumo, Para concluir, Em suma, Resumindo, Em síntese | +| it | In conclusione, Per riassumere, In sintesi, Per concludere, In definitiva, Tirando le somme, In fin dei conti | +| pl | Podsumowując, Reasumując, Na zakończenie, W konkluzji, Podsumowując powyższe, W podsumowaniu, Konkludując | + +### 1.3 Top burned words (top-15 per language) + +**Universal (all languages):** leverage, utilize, harness, empower, facilitate, optimize, streamline, revolutionize, transform (generic), robust, seamless, cutting-edge, best-in-class, game-changer, next-level, innovative (unproven), holistic, ecosystem, dynamic, synergy, granular, scalable (without specifics) + +| Lang | Top burned words (delete, then describe what actually happens) | +|------|---------------------------------------------------------------| +| en | leverage, utilize, harness, empower, facilitate, optimize, streamline, revolutionize, robust, seamless, cutting-edge, best-in-class, holistic, ecosystem, scalable | +| ru | оптимизировать, интегрировать, трансформировать, масштабировать, инновационный, комплексный подход, в рамках, данный, являться, осуществлять, посредством, эффективные решения, передовые технологии, уникальная методология, ключевой фактор | +| uk | оптимізувати, інтегрувати, трансформувати, масштабувати, інноваційний, комплексний підхід, в рамках, даний, являтися, здійснювати, ефективні рішення, передові технології, унікальна методологія, ключовий фактор, синергія | +| de | optimieren, integrieren, transformieren, skalieren, innovativ, ganzheitlich, nahtlos, robust, modernste, revolutionär, Synergie, Ökosystem, dynamisch, skalierbar, umfassende Lösung | +| fr | optimiser, intégrer, transformer, évolutif, innovant, holistique, transparent, robuste, de pointe, révolutionnaire, synergie, écosystème, dynamique, granulaire, solution complète | +| es | optimizar, integrar, transformar, escalable, innovador, holístico, sin fisuras, robusto, de vanguardia, revolucionario, sinergia, ecosistema, dinámico, granular, solución integral | +| pt | otimizar, integrar, transformar, escalável, inovador, holístico, transparente, robusto, de ponta, revolucionário, sinergia, ecossistema, dinâmico, granular, solução abrangente | +| it | ottimizzare, integrare, trasformare, scalabile, innovativo, olistico, robusto, all'avanguardia, rivoluzionario, sinergia, ecosistema, dinamico, granulare, soluzione completa, potenziare | +| pl | optymalizować, integrować, transformować, skalowalny, innowacyjny, holistyczny, solidny, najnowocześniejszy, rewolucyjny, przełomowy, synergia, ekosystem, dynamiczny, kompleksowe rozwiązanie, wykorzystywać | + +> **Full burned-word lists (30+ per language) + replacement examples:** see GitHub URLs at bottom of file. + +### 1.4 Fake transitions (delete on sight) + +| Lang | Delete on sight | +|------|-----------------| +| en | Moreover, Furthermore, Additionally, Consequently, Thus, Hence, As a result, It should be noted that | +| ru | Более того, Кроме того, Помимо этого, Следует отметить, Необходимо подчеркнуть, Важно понимать, Нельзя не отметить | +| uk | Більш того, Крім того, Окрім цього, Слід зазначити, Важливо підкреслити, Варто відзначити, Не можна не відзначити | +| de | Darüber hinaus, Außerdem, Des Weiteren, Ferner, Hinzu kommt, Es ist wichtig zu beachten, Bemerkenswert ist | +| fr | De plus, En outre, Par ailleurs, Il est important de noter, Il convient de souligner, Il faut mentionner, Ajoutons que | +| es | Además, Asimismo, Por otra parte, Cabe destacar, Es importante señalar, Merece la pena mencionar, No hay que olvidar | +| pt | Além disso, Ademais, Por outro lado, É importante notar, Vale ressaltar, Cabe destacar, Não se pode esquecer | +| it | Inoltre, Per di più, D'altra parte, È importante notare, Vale la pena sottolineare, Si rende necessario evidenziare | +| pl | Ponadto, Co więcej, Dodatkowo, Warto zauważyć, Należy podkreślić, Trzeba wspomnieć, Nie można pominąć | + +### 1.5 Hedging language (delete, state directly) + +| Lang | Delete | +|------|--------| +| en | It could be argued that, One might say, Some research suggests, There is evidence to suggest, It is possible that, Arguably, Generally speaking | +| ru | Можно сказать что, Возможно, Вероятно, Как правило, В большинстве случаев, Существует мнение, Некоторые исследования показывают | +| uk | Можна сказати що, Можливо, Ймовірно, Як правило, У більшості випадків, Існує думка, Деякі дослідження показують | +| de | Man könnte argumentieren dass, Einige schlagen vor, Es gibt Hinweise darauf, Es ist möglich dass, Im Allgemeinen, In den meisten Fällen, Tendenziell | +| fr | On pourrait dire que, Certains suggèrent, Il est possible que, Généralement parlant, Dans la plupart des cas, Il semblerait que, Apparemment | +| es | Se podría decir que, Algunos sugieren, Es posible que, Por lo general, En la mayoría de los casos, Cabe la posibilidad, Presuntamente | +| pt | Pode-se dizer que, Alguns sugerem, É possível que, Em geral, Na maioria dos casos, Supostamente, Aparentemente | +| it | Si potrebbe dire che, Alcuni suggeriscono, È possibile che, In generale, Nella maggior parte dei casi, Presumibilmente, Apparentemente | +| pl | Można powiedzieć że, Niektórzy sugerują, Jest możliwe że, Ogólnie rzecz biorąc, W większości przypadków, Przypuszczalnie, Podobno | + +### 1.6 Fake balance (delete unless positions are specific and evidenced) + +| Lang | Delete | +|------|--------| +| en | On one hand... on the other hand, While some argue... others maintain, There are pros and cons, This is not to say that | +| ru | С одной стороны... с другой стороны, Хотя некоторые считают... другие утверждают, Есть свои плюсы и минусы | +| uk | З одного боку... з іншого боку, Хоча дехто вважає... інші стверджують, Є свої плюси та мінуси | +| de | Einerseits... andererseits, Während einige argumentieren... behaupten andere, Es gibt Vor- und Nachteile | +| fr | D'un côté... de l'autre, Certains disent... d'autres affirment, Il y a des avantages et des inconvénients | +| es | Por un lado... por otro lado, Mientras unos dicen... otros afirman, Hay pros y contras | +| pt | Por um lado... por outro lado, Enquanto uns dizem... outros afirmam, Há prós e contras | +| it | Da un lato... dall'altro, Mentre alcuni dicono... altri sostengono, Ci sono pro e contro | +| pl | Z jednej strony... z drugiej strony, Podczas gdy jedni twierdzą... inni uważają, Są plusy i minusy | + +### 1.7 Empty intensifiers (delete the intensifier, let the fact carry its own weight) + +| Lang | Delete | +|------|--------| +| en | very, extremely, incredibly, amazingly, truly, really, absolutely, completely, thoroughly, highly, remarkably | +| ru | очень, крайне, чрезвычайно, невероятно, действительно, абсолютно, полностью, весьма, исключительно | +| uk | дуже, надзвичайно, неймовірно, дійсно, абсолютно, повністю, цілком, вельми, винятково | +| de | sehr, extrem, unglaublich, erstaunlich, wirklich, absolut, vollkommen, vollständig, äußerst, bemerkenswert | +| fr | très, extrêmement, incroyablement, véritablement, vraiment, absolument, totalement, complètement, remarquablement, particulièrement | +| es | muy, extremadamente, increíblemente, verdaderamente, realmente, absolutamente, totalmente, completamente, notablemente, sumamente | +| pt | muito, extremamente, incrivelmente, verdadeiramente, realmente, absolutamente, totalmente, completamente, notavelmente, altamente | +| it | molto, estremamente, incredibilmente, veramente, realmente, assolutamente, totalmente, completamente, notevolmente, altamente | +| pl | bardzo, niezwykle, niesamowicie, naprawdę, absolutnie, całkowicie, kompletnie, wyjątkowo, nadzwyczaj, znacząco | + +### 1.8 Rhetorical question padding (delete) + +| Lang | Delete | +|------|--------| +| en | What does this mean for you?, Sounds good right?, Want to know the best part?, But what about X?, So how does it work?, Ready to get started? | +| ru | Что это значит для вас?, Звучит хорошо правда?, Хотите узнать самое интересное?, Но как это работает?, Готовы начать? | +| uk | Що це означає для вас?, Звучить добре правда?, Хочете дізнатися найцікавіше?, Але як це працює?, Готові почати? | + +### 1.9 Additional rules (universal) + +- **Break symmetrical paragraphs:** 3+ consecutive paragraphs with same number of sentences (±1) → break one (split, merge, or add 1-sentence paragraph). +- **Kill adjective pileups:** max 2 adjectives before a noun. 3+ → keep strongest, show rest through description. +- **Em-dash (—) policy:** **AI tell in ALL languages. Replace always.** Use periods, commas, colons. No exceptions except: direct quotes, code references, proper names. + +> **Full AI-marker patterns (30+ per language, structure tells, punctuation per language):** see GitHub URLs at bottom. --- @@ -191,39 +286,75 @@ Delete generic transition questions: "What does this mean for you?" etc. Keep ge Replace abstract claims with concrete details. Highest-impact stage. ### Core rule -For every claim ask: **How, exactly?** No answer → fill it or flag it. Full framework: `shared/specificity-ladder.md` +For every claim ask: **How, exactly?** No answer → fill it or flag it. -### The specificity ladder (rung 0→4) -| Rung | Type | -|------|------| -| 0 | Pure abstraction | -| 1 | Domain-scoped | -| 2 | Mechanism-named | -| 3 | Quantified | -| 4 | Consequence-stated | +### The specificity ladder + +| Rung | Type | Signal | +|------|------|--------| +| 0 | Pure abstraction | No evidence, no mechanism | +| 1 | Domain-scoped | Applies to X field / Y platform | +| 2 | Mechanism-named | Explains HOW | +| 3 | Quantified | Numbers attached | +| 4 | Consequence-stated | Shows the RESULT | Target: every claim rung 0-1 → rung 2+. Rung 3 when data supports it. -### Abstraction triggers (all languages) -See `shared/specificity-ladder.md` - Abstraction Detector section. +### Rung examples (one per language) + +| Lang | 0 | 1 | 2 | 3 | 4 | +|------|---|---|---|---|---| +| en | "improves security" | "improves WordPress security" | "blocks brute-force login attacks" | "blocks 8,400 attempts/day" | "blocks 8,400/day — login stays available for real users" | +| ru | «повышает безопасность» | «повышает безопасность WordPress» | «блокирует атаки перебора паролей» | «блокирует 8400 попыток/день» | «блокирует 8400/день — страница входа остаётся доступной» | +| uk | «підвищує безпеку» | «підвищує безпеку WordPress» | «блокує атаки перебору паролів» | «блокує 8400 спроб/день» | «блокує 8400/день — сторінка входу доступна» | +| de | «verbessert Lieferzeiten» | «verbessert Lieferzeiten im Online-Handel» | «bündelt Bestellungen, optimiert Routen» | «verkürzt Lieferung von 3 Tagen auf 4h» | «Lieferung 4h statt 3 Tage — Retouren -22%, Stammkunden +40%» | +| fr | «améliore l'expérience client» | «améliore l'expérience en magasin» | «réduit le temps d'attente en caisse» | «réduit l'attente de 7 à 2 min» | «attente 7→2 min — le client suivant voit un caissier libre» | +| es | «mejora la productividad» | «mejora la productividad administrativa» | «automatiza informes semanales» | «reduce 12h de papeleo a 3h» | «12h→3h — el equipo recupera un día entero cada semana» | +| pt | «aumenta vendas» | «aumenta vendas no e-commerce» | «integra PIX e mostra frete em tempo real» | «de 40 a 127 pedidos/dia em 3 meses» | «40→127 pedidos/dia — abandono de carrinho caiu de 68% para 12%» | +| it | «ottimizza la produzione» | «ottimizza la linea di imbottigliamento» | «riduce scarti regolando temperatura e velocità» | «riduce scarti del 18%» | «-18% scarti — risparmio 47.000€/anno [VERIFY]» | +| pl | «usprawnia obsługę klienta» | «usprawnia obsługę w dziale supportu» | «automatyzuje odpowiedzi na częste zapytania» | «skraca czas z 48h do 4h, automatyzując 70%» | «odpowiedź w 4h zamiast 48h — 70% spraw zamkniętych bez eskalacji» | + +### Abstraction triggers (scan for these — all languages) + +"improves/enhances/boosts" without mechanism · "efficient/productivity/performance/quality" without measurement · "solution/platform/ecosystem/framework" without concrete description · "state-of-the-art/advanced/modern" without specifics · "better/faster/stronger/smarter" without comparison · "helps you/allows you to/enables" without saying HOW · "user-friendly/intuitive/easy to use" without what makes it so · "comprehensive/complete/end-to-end/all-in-one" without what's included · "real-time" without what happens in real time · "scalable" without to what scale ### Six enrichment techniques -See `shared/specificity-ladder.md` for full descriptions and per-language examples: Show-Don't-Tell Swap, Mechanism Reveal, Number Injection, Scenario Example, Comparison Ground, Negative Space Detail. + +1. **Show-Don't-Tell Swap:** "Our support is fast" → "We reply within 4 hours. Weekends too. Most issues solved in one reply." +2. **Mechanism Reveal:** "The algorithm detects anomalies" → "The algorithm compares each data point against the 90-day rolling average. Points outside 2.5 standard deviations get flagged." +3. **Number Injection:** "handles thousands of requests" → "handles ~12,000 requests/sec under normal load [VERIFY: confirm throughput]" +4. **Scenario Example:** "The tool prevents shipping errors" → "A warehouse worker scans a box. The tablet shows a green check — right item, right address. Last month that happened 37 times." +5. **Comparison Ground:** "Fast" → "Loads under 200ms. Industry average: 800ms." +6. **Negative Space Detail:** "A complete platform" → "We build your backend, API, database. We don't build your mobile app. We have partners for that." ### No-invention rule -**You may:** supply plausible examples with domain-typical detail, suggest numbers with verify flag. **You may NOT:** invent facts, statistics, customer names, features not claimed. Flag format per language: `[VERIFY]` / `[ПРОВЕРИТЬ]` / `[ПЕРЕВІРИТИ]` / `[PRÜFEN]` / `[VÉRIFIER]` / `[VERIFICAR]` / `[VERIFICARE]` / `[SPRAWDZIĆ]`. +You may supply plausible examples with domain-typical detail, suggest numbers with verify flag. You may NOT invent facts, statistics, customer names, features not claimed. + +### Verify flag format + +| Lang | Flag | +|------|------| +| en | `[VERIFY: what needs checking]` | +| ru | `[ПРОВЕРИТЬ: что нужно уточнить]` | +| uk | `[ПЕРЕВІРИТИ: що потрібно уточнити]` | +| de | `[PRÜFEN: was zu klären ist]` | +| fr | `[VÉRIFIER: ce qui doit être confirmé]` | +| es | `[VERIFICAR: qué necesita confirmación]` | +| pt | `[VERIFICAR: o que precisa ser confirmado]` | +| it | `[VERIFICARE: cosa va confermato]` | +| pl | `[SPRAWDZIĆ: co wymaga potwierdzenia]` | --- ## STAGE 3: TONE NATURALIZER ### Objective -Set the voice. Every text has a speaker. Full profiles: `shared/tone-profiles.md` +Set the voice. Every text has a speaker. ### Tone selection -1. User-specified - always honored. -2. Context auto-detect (see `shared/tone-profiles.md` - Tone Selection Priority table). -3. Default fallback → `human`. +1. User-specified — always honored +2. Context auto-detect +3. Default fallback → `human` Tone is set ONCE at Stage 3. Do not re-detect in later stages. @@ -239,20 +370,108 @@ Tone is set ONCE at Stage 3. Do not re-detect in later stages. | `article` | The Explainer | Long-form guides, tutorials | | `case` | The Case Study | Portfolio, success stories | -### Key parameters (all tones, all languages) -See `shared/tone-profiles.md` and `shared/rhythm-tables.md` for: fragment frequencies, conjunction frequencies, short-sentence spacing, sentence length mix, and per-language tone markers. +### Fragment & conjunction spacing (all languages, qualitative targets) + +| Tone | Fragment spacing | Conjunction spacing | Short sent. every | Max consecutive same category | +|------|-----------------|---------------------|-------------------|:---:| +| expert | Every 5-7 sent | Every 5-7 sent | 5-7 sent | 2 | +| biz | Rare (1-2/text) | Rare (1-2/text) | 6-8 sent | 2 | +| human | Every 3-5 sent | Every 3-5 sent | 3-5 sent | 2 | +| social | Every 2-3 sent | Every 2-4 sent | 2-3 sent | 1 | +| landing | Every 3-4 sent | Every 5-7 sent | 3-4 sent | 1 | +| article | Every 4-6 sent | Every 4-6 sent | 4-6 sent | 2 | +| case | Every 4-5 sent | Every 4-6 sent | 4-5 sent | 2 | + +### Per-tone key markers (all languages) + +#### `expert` — The Practitioner +- **EN:** "The problem is...", "Here's what happens...", moderate contractions (we'll, it's — yes; gonna — no) +- **RU:** Brevity, shorter sentences than EN. Technical terms per industry norm. Мы default. Minimal adjectives. +- **UK:** Clean technical Ukrainian, no Russianisms. Slightly warmer than RU. Мы default. +- **DE:** Direkt. Kein Nominalstil. «Wir haben getestet. Es funktioniert.» Minimal adjectives. +- **FR:** «On a testé. Voilà ce qui marche.» Pas d'enthousiasme forcé. Préférer «on» à «nous». +- **ES:** «Probamos X. Funcionó. Aquí están los datos.» Cuidado con gerundio excesivo. +- **PT:** «A gente testou. Rodou. Tá funcionando.» (PT-BR). Gerúndio brasileiro é natural, não AI tell. +- **IT:** «Abbiamo provato X. Ha funzionato. Ecco perché.» Attenzione al «si passivante». +- **PL:** «Przetestowaliśmy. Działa. Oto dlaczego.» Żargon tylko jeśli odbiorca zna. + +#### `biz` — The Consultant +- **EN:** Limited contractions. No: "partner with us", "journey", "passionate about" +- **RU:** Вы always. Direct questions. No: «рады предложить», «с удовольствием» +- **UK:** Ви always. European business style. No: «раді запропонувати», «наша місія» +- **DE:** Sie immer. Direkt, sachlich. Kein: «wir freuen uns», «unsere Mission» +- **FR:** Vous toujours. «Voici ce que nous faisons. Voici les résultats.» Pas de «nous sommes ravis». +- **ES:** Usted siempre. Datos con fuente. Sin «nos complace», «nuestra misión». +- **PT:** Você/Senhor(a). Dados com período de referência. Evitar «através de» quando «com» basta. +- **IT:** Lei sempre. Dati con contesto. No «siamo lieti», «la nostra missione». +- **PL:** Pan/Pani zawsze. Dane z datą. Bez «z przyjemnością», «naszą misją jest». + +#### `human` — The Smart Friend +- **EN:** All contractions, incl. "gonna" (max 1/500w). Sentence 2w to 30+. Conjunction starters freely. +- **RU:** Stay slightly more formal than EN. Default вы. Fragments work: «Сделали. Работает. Смотрим дальше.» +- **UK:** Naturally warmer than RU. Fillers: «до речі», «чесно кажучи», «давайте розберемось». +- **DE:** Etwas wärmer als biz. Modalpartikeln: «doch», «ja», «halt». Kein: «man sollte». +- **FR:** «Du coup», «en fait», «franchement» en dose naturelle. Pas de plan en trois parties. +- **ES:** «La verdad», «mira», «pues». Frases cortas mezcladas con explicaciones. Regionalismos bienvenidos. +- **PT:** «Olha», «na real», «tipo assim» (PT-BR). «A gente» para tom conversacional. Um toque de humor. +- **IT:** «Allora», «cioè», «sai com'è», «guarda». Domande retoriche: «Ha senso?» Meno si passivante. +- **PL:** «No wiesz», «szczerze mówiąc», «w sumie». Naturalne przejścia: «No i co z tego?», «I teraz uwaga». + +#### `social` — The Scroller +- **EN:** 3-12w sentences. One longer for explanation. All contractions. Fragments encouraged. +- **RU:** Measured confidence. Self-irony works. Short lines, big claims, sharp transitions. +- **UK:** More emotional, community-oriented. Shorter paragraphs than EN. Natural conversational flow. +- **DE:** Kurz, prägnant, meinungsstark. «Los geht's.» «Das ist der Punkt.» Keine langen Einleitungen. +- **FR:** Phrases 3-8 mots dominantes. Accroche en première ligne. Pas de «n'hésitez pas à». +- **ES:** «Mira.» «El problema es este.» Frases 3-10 palabras. Sin rodeos. +- **PT:** «Olha só.» «O problema é esse.» Frases curtas 3-10 palavras. Brasileiro de internet é informal até no LinkedIn. +- **IT:** «Guarda.» «Il punto è questo.» Frasi 3-10 parole. Chiudere con osservazione, non riassunto. +- **PL:** «Słuchaj.» «Rzecz w tym, że...» Krótkie zdania 3-10 słów. Ironia i sarkazm działają. + +#### `landing` — The Seller +- **EN:** Headline <12w. "Start building" not "Get started today". Fragments 1-1.5/100w. +- **RU:** Cut 30% then cut 30% more. CTAs: infinitive or imperative — pick one. Trust through specifics. +- **UK:** Clarity over embellishment. Cut aggressively. Довіра через конкретику. +- **DE:** «Jetzt starten» nicht «Starten Sie noch heute». Vertrauen durch Fakten. +- **FR:** «Commencez» pas «N'attendez plus». Confiance par preuves: chiffres, logos clients, certification. +- **ES:** «Empieza ya» no «No esperes más». Confianza con hechos. Cortar 40-60% del texto original. +- **PT:** «Comece agora» não «Não espere mais». Cortar 40-60%. «O que eu ganho com isso?» +- **IT:** «Inizia ora» non «Non aspettare». Italiani diffidano dei superlativi. Tagliare 40-60%. +- **PL:** «Zacznij teraz» nie «Nie czekaj». Polak sprawdza konkrety zanim kupi. Ciąć bezlitośnie. + +#### `article` — The Explainer +- **EN:** Opens with problem, not context. "Let's look at the data." "But there's a catch." +- **RU:** Fight academic tone. Write like explaining to a smart colleague. Section breaks with questions. +- **UK:** European, less Soviet baggage. Natural section flow. Questions as section breaks. +- **DE:** «Schauen wir uns die Daten an.» «Aber es gibt einen Haken.» Kein: «Erstens, zweitens, drittens». +- **FR:** «Regardons les données.» «Mais il y a un hic.» Varier: phrase courte 5 mots, puis explication 25. +- **ES:** «Veamos los datos.» «Pero hay una trampa.» Evitar «en primer lugar», «en segundo lugar». +- **PT:** «Vejamos os dados.» «Mas tem um porém.» PT-BR: tom de conversa inteligente, não monografia. +- **IT:** «Guardiamo i dati.» «Ma c'è un problema.» Troppi «nonostante», «sebbene», «tuttavia» = AI. +- **PL:** «Spójrzmy na dane.» «Ale jest haczyk.» Unikać: «po pierwsze», «po drugie», «podsumowując». + +#### `case` — The Case Study +- **EN:** Context → Problem → Attempt 1 (failed) → Attempt 2 (worked) → Numbers → Lessons +- **RU:** Include failures — builds massive trust. Specific technical details respected. +- **UK:** Same logic as RU. Ukrainian business appreciates directness. Numbers + honest narrative = trust. +- **DE:** Ehrlichkeit baut Vertrauen. Zahlen, nicht Adjektive. «Der erste Ansatz scheiterte...» +- **FR:** «La première approche a échoué.» Chiffres en contexte temporel. Pas de «solution miracle». +- **ES:** Honestidad = credibilidad. Admitir un error bien manejado genera más confianza que un relato perfecto. +- **PT:** Brasileiros valorizam transparência e «jeitinho». O que aprendemos é mais valioso que o resultado. +- **IT:** Onestà = credibilità. Dati con periodo. Mai «implementazione impeccabile». La lezione appresa è la parte più importante. +- **PL:** «Pierwsze podejście nie zadziałało.» Polacy cenią konkret. Wnioski i nauczki są ważniejsze od suchych liczb. + +> **Full tone profiles (7 tones × 9 languages, 250 lines):** see GitHub URL at bottom. --- ## STAGE 4: RHYTHM EDITOR ### Objective -Break the machine rhythm. AI = metronome. Human = jazz. Full parameters: `shared/rhythm-tables.md` +Break the machine rhythm. AI = metronome. Human = jazz. ### Sentence length: use CLAUSE COUNT (not word count) -LLMs cannot count words reliably. Use syntactic categories instead. Full definitions: `shared/rhythm-tables.md` - | Category | Clauses | Check method | |----------|---------|-------------| | Fragment | 0 clauses | No subject+predicate pair | @@ -267,27 +486,78 @@ LLMs cannot count words reliably. Use syntactic categories instead. Full definit 2. **No three consecutive sentences** with the same clause count. 3. **No sentence exceeds 3 clauses.** Split at 4+. Exception: 1 sentence per ~300 words may have 4 clauses. -### Approximate word reference (rough guidance, not strict) +### Approximate word reference (rough guidance only) + Fragment: ~1-5w. Short: ~4-12w. Medium: ~12-22w. Long: ~22-30w. Very Long: 30+w (split). -### Opener variety -No three consecutive sentences start with the same word or grammatical structure. Per-language opener categories: `shared/rhythm-tables.md` +### Opener variety — per language + +**Rule:** No three consecutive sentences start with the same word or same grammatical structure. -### Fragments -Use them. Fastest way to break AI rhythm. Fragment types and frequencies by tone: `shared/rhythm-tables.md` +| Lang | Opener categories (rotate through these) | +|------|------------------------------------------| +| en | Subject, Pronoun (You/We/They), Conjunction (And/But/So/Or), Verb (Build/Start), Preposition (In/With/For), Adverb, Question, Fragment | +| ru | Subject, Pronoun (Вы/Мы/Они), Conjunction (А/И/Но), Verb-first, Adverbial (Когда/Если), Question, Fragment | +| uk | Subject, Pronoun (Ви/Ми/Вони), Conjunction (А/І/Але), Verb-first, Adverbial (Коли/Якщо), Question, Fragment | +| de | Subject, Pronomen (Sie/Wir), Konjunktion (Und/Aber/Oder), Verb-erst, Präpositional (Mit/Durch/Für), Adverbial, Frage, Fragment | +| fr | Sujet, Pronom (Vous/Nous/On), Conjonction (Et/Mais/Donc), Verbe, Prépositionnel (Avec/Pour/Dans), Adverbial, Question, Fragment | +| es | Sujeto, Pronombre (Usted/Nosotros), Conjunción (Y/Pero), Verbo, Preposicional (Con/Para/En), Adverbial, Pregunta, Fragmento | +| pt | Sujeito, Pronome (Você/Nós), Conjunção (E/Mas), Verbo, Preposicional (Com/Para/Em), Adverbial, Pergunta, Fragmento | +| it | Soggetto, Pronome (Lei/Noi), Congiunzione (E/Ma), Verbo, Preposizionale (Con/Per/In), Avverbiale, Domanda, Frammento | +| pl | Podmiot, Zaimek (Pan/Pani/My), Spójnik (I/Ale), Czasownik, Przyimkowy (Z/Dla/W), Przysłówkowy, Pytanie, Fragment | -### Conjunction-started sentences -Real humans start with conjunctions. AI rarely does. Frequencies and per-language conjunction lists: `shared/rhythm-tables.md` +### Conjunctions for sentence starters + +| Lang | Conjunctions | +|------|-------------| +| en | And, But, So, Or, Nor, Yet | +| ru | А, И, Но, Или, Зато, Однако | +| uk | А, І, Але, Чи, Зате, Однак | +| de | Und, Aber, Oder, Denn, Doch, Sondern | +| fr | Et, Mais, Donc, Ou, Car, Pourtant | +| es | Y, Pero, O, Así que, Sin embargo, Aunque | +| pt | E, Mas, Ou, Portanto, Porém, Contudo | +| it | E, Ma, O, Quindi, Però, Dunque | +| pl | I, Ale, Lub, Więc, Jednak, Zatem | ### Visual paragraph weight -No three consecutive paragraphs of identical visual weight. Weight categories: Light (1 sentence), Medium (2-3 sentences), Heavy (4+ sentences). + +**Rule:** No three consecutive paragraphs of identical visual weight. + +| Weight | Definition | +|--------|-----------| +| Light | 1 sentence. ~1-2 visual lines. | +| Medium | 2-3 sentences. ~3-5 visual lines. | +| Heavy | 4+ sentences. ~6+ visual lines. | + +### Fragment types (universal) + +| # | Type | Example | +|---|------|---------| +| 1 | Emphasis | "We tested it. For six months. In production." | +| 2 | Afterthought | "The migration took three weekends. Nobody noticed." | +| 3 | Contrast | "We thought scaling was the problem. It wasn't." | +| 4 | Summary | "Three teams. Four months. One result." | +| 5 | Punch | "Don't do this." | + +### Length mix by tone + +| Tone | Fragment spacing | Short % | Medium % | Long % | +|------|-----------------|---------|----------|--------| +| expert | Every 5-7 sent | ~20% | ~50% | ~30% | +| biz | Every 6-8 sent | ~20% | ~55% | ~25% | +| human | Every 3-5 sent | ~25% | ~45% | ~30% | +| social | Every 2-3 sent | ~35% | ~55% | ~10% | +| landing | Every 3-4 sent | ~30% | ~50% | ~20% | +| article | Every 4-6 sent | ~20% | ~50% | ~30% | +| case | Every 4-5 sent | ~20% | ~55% | ~25% | --- ## STAGE 5: FINAL PROOFREAD ### 5.1 Read-aloud test (internal simulation) -Every sentence: would you say this to a colleague? If it contains words you wouldn't use in spoken conversation, passive where active works, or >2 clauses - rewrite. +Every sentence: would you say this to a colleague? If it contains words you wouldn't use in spoken conversation, passive where active works, or >2 clauses — rewrite. ### 5.2 Re-check opener First 200 words: still starts with context-setting? Cut more. @@ -297,11 +567,11 @@ Last sentence has actual information? Not summary? Good. ### 5.4 Language-specific final checks -**RU:** «следует отметить» lurking? «осуществлять» → «делать». «посредством» → «через». «данный» → «этот». Em-dash → period/comma. +**EN:** Em-dashes left? Replace. "Not only... but also..." → break into two. "Whether it's X or Y" → delete. -**UK:** «являється» or «даний» survived? Replace. Russianisms: «із-за» → «через», «так як» → «бо»/«тому що». Em-dash → period/comma. +**RU:** «следует отметить» survived? «осуществлять» → «делать». «посредством» → «через». «данный» → «этот». Em-dash → period/comma. No exceptions: long dashes are NOT Russian typography — they are an AI fingerprint. -**EN:** Em-dashes left? Replace. "Not only... but also..." → break into two. "Whether it's X or Y" → delete. +**UK:** «являється» or «даний» survived? Replace. Russianisms: «із-за» → «через», «так як» → «бо»/«тому що». Em-dash → period/comma. **DE:** Nominalstil survived? Aktive Verben. Em-dash → Punkt/Komma. «Man sollte» → direkt formulieren. @@ -315,23 +585,21 @@ Last sentence has actual information? Not summary? Good. **PL:** «Należy podkreślić» survived? Kill. Em-dash → kropka/przecinek. Nadmierna nominalizacja → czasowniki. -### 5.5 Final scan - top 10 AI tells (must be 0 or near-zero) +### 5.5 Final scan — top 10 AI tells (must be 0 or near-zero) -1. "Seamless" / its translations - 0 -2. "Leverage" / its translations - 0 -3. "Robust" / its translations - 0 -4. "In today's" / its translations - 0 -5. "Moreover" / its translations - 0 -6. Symmetrical paragraph blocks (same weight 3x) - 0 -7. "In conclusion" / its translations - 0 -8. 3+ adjective pileups - 0 -9. Empty intensifiers - 1 or fewer -10. Rhetorical question padding - 0 +1. "Seamless" / its translations — 0 +2. "Leverage" / its translations — 0 +3. "Robust" / its translations — 0 +4. "In today's" / its translations — 0 +5. "Moreover" / its translations — 0 +6. Symmetrical paragraph blocks (same weight 3x) — 0 +7. "In conclusion" / its translations — 0 +8. 3+ adjective pileups — 0 +9. Empty intensifiers — 1 or fewer +10. Rhetorical question padding — 0 ### 5.6 Self-Evaluation -After producing the output, scan it against your own rules and assign a **QUALITY SCORE**: - | # | Check | Pass (10) | Partial (5) | Fail (0) | |---|-------|-----------|-------------|----------| | 1 | Top-10 AI tells = 0 | All 10 cleared | 1-2 remain | 3+ remain | @@ -349,14 +617,13 @@ After producing the output, scan it against your own rules and assign a **QUALIT | Score | Rating | Action | |-------|--------|--------| -| 90-100 | Excellent | Output is production-ready | +| 90-100 | Excellent | Production-ready | | 75-89 | Good | 1-2 minor issues, acceptable | -| 60-74 | Fair | Multiple issues. Re-run affected stages (see Re-loop) | +| 60-74 | Fair | Multiple issues. Re-run affected stages | | Below 60 | Poor | Re-run pipeline with adjusted parameters | ### Re-loop Rule - -If QUALITY SCORE < 75: identify the 2 lowest-scoring checks. Re-run ONLY the relevant stage(s) for those checks. Max 1 re-loop. Record both scores in output. +If QUALITY SCORE < 75: identify the 2 lowest-scoring checks. Re-run ONLY the relevant stage(s). Max 1 re-loop. Record both scores. **Re-loop mapping:** - Checks 1, 9 → re-run Stage 1 (cleanup) @@ -367,19 +634,26 @@ If QUALITY SCORE < 75: identify the 2 lowest-scoring checks. Re-run ONLY the rel After the single re-loop, output the final score regardless. Stop after 2 passes total. -**External validation:** For independent verification, run ZeroGPT detection via `scripts/zerogpt-detect.ps1` or `scripts/run-benchmark.ps1`. See `EVAL.md` — External Validation section for details. The self-evaluation score is an LLM self-assessment. ZeroGPT provides an independent external check. +### External validation (recommended, not LLM-performed) + +Three independent layers beyond self-evaluation: + +| Layer | Tool | What it measures | How to run | +|-------|------|-----------------|------------| +| Readability | `readsight` (Python pkg) | Flesch, LIX, Fog — did text become more readable? | `scripts/readability-check.ps1` | +| Morphology | `pymorphy3` / `spaCy` | Non-existent words in output | `scripts/morph-check.ps1 -Lang ru` | +| AI detection | ZeroGPT API | Independent AI probability | `scripts/zerogpt-detect.ps1 -File output.md` | --- ## WHEN NOT TO APPLY -Skip the pipeline entirely if: -- **Pre-flight guard triggered** (AI Probability < 20): text appears human-written. Output diagnostic only. -- Text is authored by a known human (attributed, signed) — regardless of score +- **Pre-flight guard triggered** (AI Probability < 20 AND multiple conditions): output diagnostic only +- Text is authored by a known human (attributed, signed) - Text requires exact preservation (legal, medical, safety) - User says "audit only" → run detection scan, output diagnostics, do NOT modify -**Force pipeline override:** If user says "force pipeline" after the pre-flight guard triggers, run proofread-only scan with `[HUMAN-ORIGIN]` annotation. Never run full pipeline on text scoring <20. +**Force pipeline override:** If user says "force pipeline" after pre-flight guard triggers → proofread-only scan with `[HUMAN-ORIGIN]` annotation. Never run full pipeline on text scoring <20. Mixed-language text: detect primary language. Do not rewrite quoted foreign-language passages. @@ -391,7 +665,7 @@ Mixed-language text: detect primary language. Do not rewrite quoted foreign-lang [LANG: en / ru / uk / de / fr / es / pt / it / pl] [TONE: expert / biz / human / social / landing / article / case] [PIPELINE: stages applied with skip notes] -[QUALITY: XX/100] ← Self-evaluation score from Stage 5.6 +[QUALITY: XX/100] [ISSUES: brief list of remaining issues, if any] [THE TEXT] @@ -401,29 +675,23 @@ Mixed-language text: detect primary language. Do not rewrite quoted foreign-lang Brief: 3-5 bullet points on what was changed and why. [STAGE SCORES] -Cleanup: XX/100 (checks 1+9 from self-eval) -Specificity: XX/100 (check 8) -Tone: XX/100 (check 7) -Rhythm: XX/100 (checks 2+3+4+5+6) -Proofread: XX/100 (check 10) +Cleanup: XX/100 | Specificity: XX/100 | Tone: XX/100 | Rhythm: XX/100 | Proofread: XX/100 Re-loop: yes/no, stage(s) re-run, final score (if applicable) [FACTUAL NOTES] -(Optional - flag inaccuracies, do not silently fix.) +(Optional — flag inaccuracies, do not silently fix.) ``` No preamble. No "here is your rewritten text." No "I hope this helps." Deliver text, changelog, stop. --- -## AUDIT MODE (Enhanced) +## AUDIT MODE When user says "audit only" or "tell me what's wrong, don't rewrite": Output a structured diagnostic, NOT a rewrite. -### Audit Output Format - ``` [AUDIT REPORT] Language: {detected} (confidence: XX%) @@ -467,80 +735,91 @@ ESTIMATED EFFORT: {N} critical + {N} high items --- +## INTEGRATION: RankWise + MindFluence + +### With RankWise (SEO) +**Rule:** RankWise handles SEO structure → HumanAI handles human voice. Do not break SEO. + +Preservation rules: +- Do NOT delete or alter H2/H3 headings containing SEO keywords +- Preserve keyword density 0.8%–1.5% +- Maintain min 600 words (unless user requests shorter) +- Keep internal link anchors and placement +- Skip deletion of keywords, internal links, schema-relevant elements during cleanup +- Meta title/description: already SEO-optimized, do not humanize + +Recommended pipeline: `cleanup(skipped: SEO structure) → specificity → tone → rhythm → proofread` + +### With MindFluence (Cognitive Bias) +**Rule:** MindFluence engineers persuasion → HumanAI humanizes voice. Do not strip psychological structure. + +Tone mapping: `bold-sell` → `landing` · `expert-calm` → `expert` · `rebel-edgy` → `social` · `warm-human` → `human` · `luxe-minimal` → `case` + +Preservation rules: +- Do NOT strip bias markers: social proof numbers, anchoring prices, authority signals +- Do NOT delete power words overlapping with burned-word lists — they serve psychological function +- Do NOT break hook openings — deliberately patterned for System 1 capture +- Preserve social proof specificity: "14,327 users this week" is bias marker, not fluff + +Recommended pipeline: `cleanup(skipped: bias structure) → specificity → tone(skipped: MindFluence tone) → rhythm → proofread` + +### Triple Pipeline +1. RankWise Brief → SEO structure +2. MindFluence → bias copy within SEO skeleton +3. HumanAI → humanize voice, preserving BOTH SEO signals AND bias structure +4. RankWise Audit → final 49-factor verification + +HumanAI invocation: `cleanup(skipped: SEO+bias elements) → specificity → tone(skipped: from MindFluence) → rhythm → proofread` + +--- + ## QUICK START -**Full pipeline:** -> "Rewrite this to sound human. Language: ru." +**Full pipeline:** "Rewrite this to sound human. Language: ru." -**Specific task - load scenario:** -> "Rewrite this as a landing page. DE." → load `scenarios/landing-page.md` +**Specific task — load scenario:** "Rewrite this as a landing page. DE." → load `scenarios/landing-page.md` -**Audit only:** -> "Tell me what's wrong with this. Don't rewrite." +**Audit only:** "Tell me what's wrong with this. Don't rewrite." -**Translation fix:** -> "This was translated from Russian to English. Make it sound native." +**Translation fix:** "This was translated from Russian to English. Make it sound native." --- -## FILES IN THIS SKILL +## FILES & GITHUB URLS + +### This skill is self-contained — the SKILL.md above embeds all critical rules and top-15 per-language data. For deep processing, the following files are available: ``` natural-skill/ -├── SKILL.md ← This file - orchestrator +├── SKILL.md ← This file — self-contained orchestrator (v4.0) +├── PLAN.md ← Improvement roadmap ├── README.md / README.ru.md ← Documentation (bilingual) -├── CHANGELOG.md ← Version history -├── CONTRIBUTING.md ← How to add languages/scenarios/tones -├── KNOWN_LIMITATIONS.md ← Edge cases and LLM variance -├── EVAL.md ← Quality evaluation framework -├── LICENSE ← MIT -├── .gitignore -├── scripts/ -│ ├── validate.ps1 ← Integrity checker (PowerShell) -│ ├── validate.sh ← Integrity checker (Bash) -│ ├── zerogpt-detect.ps1 ← ZeroGPT AI detection (PowerShell) -│ ├── zerogpt-detect.sh ← ZeroGPT AI detection (Bash) -│ └── run-benchmark.ps1 ← External benchmark runner (ZeroGPT) -├── .github/workflows/ -│ └── validate.yml ← CI pipeline -├── tests/benchmark/ ← Evaluation dataset -│ ├── annotations.json -│ ├── zerogpt-results.json ← ZeroGPT external validation results -│ ├── ai-texts/ (9 languages) -│ ├── human-texts/ -│ └── edge-cases/ -├── shared/ -│ ├── burned-words.md ← All burned words × 9 languages -│ ├── ai-markers.md ← AI detection patterns × 9 languages -│ ├── tone-profiles.md ← 7 tones with language markers -│ ├── specificity-ladder.md ← Abstraction → concrete framework -│ ├── rhythm-tables.md ← Sentence flow parameters -│ └── language-template.md ← Template for adding new languages -├── scenarios/ -│ ├── full-rewrite.md ← Default: all 6 stages -│ ├── blog-post.md ← Blog post humanization -│ ├── landing-page.md ← Landing page humanization -│ ├── social-post.md ← Social media post -│ ├── seo-article.md ← SEO content humanization -│ ├── case-study.md ← Case study / portfolio -│ ├── commercial-offer.md ← B2B commercial offer -│ ├── email.md ← Email humanization -│ ├── technical-doc.md ← Technical documentation -│ ├── translation-fix.md ← De-translation: make it sound native -│ ├── press-release.md ← Press release / media announcement -│ ├── internal-memo.md ← Internal company memo -│ ├── grant-proposal.md ← Grant proposal / funding application -│ ├── creative-writing.md ← Creative writing (light touch) -│ └── product-update.md ← Product update / changelog -└── examples/ - ├── en-blog-post.md - ├── en-landing.md - ├── en-social.md - ├── ru-blog-post.md - ├── ru-landing.md - ├── ru-social.md - ├── uk-blog-post.md - └── uk-social.md +├── EVAL.md ← External LLM evaluation framework +├── shared/ ← Full data files (30+ words per list, 250-line tone profiles) +├── scenarios/ ← 15 task-specific playbooks +├── examples/ ← Annotated before/after examples +├── scripts/ ← Validation + external tools +└── tests/benchmark/ ← Evaluation dataset ``` -Each `shared/` file is a data-reference. The full pipeline works without loading them - the SKILL.md above contains all rules. Load shared files for richer per-language detail. +### Deep data (GitHub raw URLs — fetch when task needs full lists): + +| File | URL | +|------|-----| +| Full burned words × 9 languages | https://raw.githubusercontent.com/MADEVAL/Natural-skill/main/shared/burned-words.md | +| Full AI markers × 9 languages | https://raw.githubusercontent.com/MADEVAL/Natural-skill/main/shared/ai-markers.md | +| Full tone profiles (7 × 9) | https://raw.githubusercontent.com/MADEVAL/Natural-skill/main/shared/tone-profiles.md | +| Specificity ladder (all examples) | https://raw.githubusercontent.com/MADEVAL/Natural-skill/main/shared/specificity-ladder.md | +| Rhythm tables (full parameters) | https://raw.githubusercontent.com/MADEVAL/Natural-skill/main/shared/rhythm-tables.md | +| EVAL framework | https://raw.githubusercontent.com/MADEVAL/Natural-skill/main/EVAL.md | + +### External validation tools (run separately — not LLM tasks): + +| Script | Purpose | +|--------|---------| +| `scripts/validate.ps1` | Integrity checker for skill files | +| `scripts/morph-check.ps1` | Morphological validator (non-existent words) | +| `scripts/readability-check.ps1` | ReadSightPy readability validator | +| `scripts/zerogpt-detect.ps1` | ZeroGPT AI detection | +| `scripts/run-benchmark.ps1` | Full benchmark runner | +| `scripts/run-eval.ps1` | External EVAL.md LLM evaluation runner | diff --git a/examples/de-blog-post.md b/examples/de-blog-post.md new file mode 100644 index 0000000..9bebc4d --- /dev/null +++ b/examples/de-blog-post.md @@ -0,0 +1,43 @@ +# Beispiel: DE Blog-Post + +## VORHER (KI-generiert) + +In der heutigen schnelllebigen digitalen Landschaft setzen Unternehmen zunehmend auf modernste KI-Technologien, um ihre Arbeitsabläufe zu optimieren und Prozesse zu transformieren. Dieser umfassende Leitfaden beleuchtet die revolutionären Möglichkeiten künstlicher Intelligenz und zeigt, wie Organisationen das volle Potenzial dieser wegweisenden Technologie ausschöpfen können. Darüber hinaus werden wir zentrale Strategien untersuchen, die eine nahtlose Integration von KI-Tools in bestehende Geschäftsprozesse ermöglichen. Es ist wichtig zu betonen, dass eine ganzheitliche Herangehensweise erforderlich ist, die sowohl technische als auch menschliche Faktoren berücksichtigt. Zudem müssen Unternehmen ihre Mitarbeiter entsprechend schulen, um die neuen Tools effektiv zu nutzen. Zusammenfassend lässt sich sagen, dass KI einen Paradigmenwechsel darstellt, den kein Unternehmen ignorieren sollte. + +**KI-Marker:** «In der heutigen» · «modernste» · «optimieren» · «transformieren» · «umfassend» · «revolutionär» · «wegweisend» · «Darüber hinaus / Zudem» · «nahtlos» · «ganzheitlich» · «Es ist wichtig zu betonen» · «Zusammenfassend» · symmetrische Satzlängen · Nominalstil + +--- + +## NACHHER (human-ai v4) + +``` +[LANG: de] +[TONE: human] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 91/100] + +Die meisten Firmen kaufen KI-Tools. Und nutzen sie dann nicht. Nicht «noch nicht». Gar nicht. + +Wir haben 200 Teams befragt, die 2025 KI-Software gekauft haben. Nach sechs Monaten: +- 23 % nutzten sie täglich +- 41 % öffneten sie einmal pro Woche oder seltener +- 36 % hatten ihr Abo bereits gekündigt + +Die 23 % hatten kein grösseres Budget. Keine besseren Data Scientists. Sie haben genau eine Sache anders gemacht: einen einzigen Workflow ausgewählt und komplett automatisiert. Nicht fünf Workflows halb. Einen. Von Anfang bis Ende. + +So sieht das aus. + +Ein Kundenservice-Team mit 12 Leuten. 400 Tickets am Tag. Vor KI: durchschnittliche Antwortzeit — 7 Stunden. Teamleiter haben täglich 3 Stunden damit verbracht, Tickets manuell zuzuweisen. Nachher: Die KI liest die Anfrage, schreibt einen Antwortentwurf und leitet ihn an die richtige Person weiter. Teamleiter hören auf zuzuweisen. Agenten tippen nicht mehr 40-mal dieselbe Antwort. Antwortzeit fällt auf 90 Minuten. + +Die Technik war nicht das Schwierige. Schwierig war: nicht alles auf einmal umkrempeln zu wollen. + +--- +[CHANGELOG] +- Einstieg gelöscht: «In der heutigen schnelllebigen digitalen Landschaft...» +- Verbrannte Wörter entfernt: modernste, optimieren, transformieren, umfassend, revolutionär, wegweisend, nahtlos, ganzheitlich (8x) +- Übergänge getötet: Darüber hinaus, Zudem, Zusammenfassend +- «Es ist wichtig zu betonen» gestrichen +- Konkretheit: 200 Teams, 23/41/36 %, 12 Personen, 400 Tickets/Tag, 7h→90min [PRÜFEN: Zahlen illustrativ] +- Ton: human — direkt, datenbasiert, konkretes Beispiel +- Rhythmus: Satz-Mix aus Fragmenten und variablen Längen, keine gleichlangen Folgen +``` diff --git a/examples/de-email.md b/examples/de-email.md new file mode 100644 index 0000000..eb9d876 --- /dev/null +++ b/examples/de-email.md @@ -0,0 +1,55 @@ +# Beispiel: DE E-Mail (Kaltakquise) + +## VORHER (KI-generiert) + +Betreff: Revolutionäre KI-Lösung für Ihr Unternehmen + +Sehr geehrte Damen und Herren, + +in der heutigen dynamischen Geschäftswelt ist es unerlässlich, Prozesse zu optimieren und Arbeitsabläufe durch innovative Technologien zu transformieren. Unsere modernste Plattform bietet eine ganzheitliche Lösung, die nahtlos in Ihre bestehende Infrastruktur integriert werden kann. Durch den Einsatz unserer wegweisenden KI-Technologie können Sie die Effizienz Ihres Teams signifikant steigern und skalierbare Ergebnisse erzielen. + +Wir würden uns freuen, Ihnen in einem kurzen Gespräch zu zeigen, wie unsere robuste Lösung Ihr Unternehmen auf das nächste Level bringen kann. Zögern Sie nicht, uns zu kontaktieren — wir stehen Ihnen jederzeit gerne zur Verfügung. + +Mit freundlichen Grüssen +Ihr KI-Solutions-Team + +**KI-Marker:** «in der heutigen» · «optimieren» · «innovativ» · «transformieren» · «modernste» · «ganzheitlich» · «nahtlos» · «wegweisend» · «skalierbar» · «robust» · «signifikant» · Floskeln: «würden uns freuen», «zögern Sie nicht», «jederzeit gerne zur Verfügung» · Nominalstil + +--- + +## NACHHER (human-ai v4) + +``` +[LANG: de] +[TONE: email-kalt] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 88/100] + +Betreff: Ihre Support-Antwortzeit liegt bei 7 Stunden. Unsere bei 90 Minuten. + +Hallo Frau Meier, + +ich habe gestern Ihre Support-Seite angeschaut. Der Live-Chat hat nach 4 Minuten geantwortet — okay, aber nicht grossartig. Ihre FAQ-Seite listet 47 Artikel. Davon sind 12 veraltet (beziehen sich auf Features, die es nicht mehr gibt). + +So habe ich gerechnet: +- 400 Tickets pro Tag bei 12 Agenten +- 7 Stunden durchschnittliche Antwortzeit +- 3 Stunden pro Tag gehen für Ticket-Zuweisung drauf + +Bei drei unserer Kunden aus dem E-Commerce Bereich hat sich die Antwortzeit auf 90 Minuten verkürzt. Nicht durch mehr Personal. Sondern weil die KI Tickets liest, Antwortentwürfe schreibt und direkt an den richtigen Agenten weiterleitet. + +Nächste Woche Dienstag oder Mittwoch 15 Minuten? Ich zeig's Ihnen am Bildschirm. + +Viele Grüsse +Thomas Berger + +--- +[CHANGELOG] +- Betreff: Phrasen-Betreff → konkrete Zahl, die neugierig macht +- Verbrannte Wörter entfernt: optimieren, innovativ, transformieren, modernste, ganzheitlich, nahtlos, wegweisend, skalierbar, robust, signifikant (10x) +- Floskeln getötet: «würden uns freuen», «zögern Sie nicht», «jederzeit gerne zur Verfügung» +- Anrede personalisiert mit Name +- Konkretheit: echte Zahlen aus dem Blog-Post wiederverwendet, 47 Artikel, 12 veraltet, Referenzkunden aus E-Commerce [PRÜFEN: Zahlen illustrativ] +- Ton: email-kalt — persönlich, recherchiert, konkretes Angebot, keine Floskeln +- Rhythmus: kurze Absätze, Bullet-Liste für Kalkulation, klarer Call-to-Action +``` diff --git a/examples/es-blog-post.md b/examples/es-blog-post.md new file mode 100644 index 0000000..1a7a46f --- /dev/null +++ b/examples/es-blog-post.md @@ -0,0 +1,43 @@ +# Ejemplo: ES Artículo de blog + +## ANTES (texto generado por IA) + +En el mundo digital actual, las empresas recurren cada vez más a soluciones de inteligencia artificial de vanguardia para optimizar sus flujos de trabajo y transformar sus operaciones. Esta guía integral explora el poder revolucionario de la IA y cómo las organizaciones pueden aprovechar su potencial para mantenerse competitivas en un mercado en constante evolución. Además, examinaremos estrategias clave que facilitan una integración sin fisuras de las herramientas de IA en los procesos empresariales existentes. Es importante señalar que, si bien algunos expertos advierten sobre ciertos riesgos, los beneficios superan con creces los posibles inconvenientes. Asimismo, una implementación exitosa requiere un enfoque holístico que contemple tanto factores técnicos como humanos. Por otro lado, las empresas deben asegurarse de capacitar adecuadamente a sus equipos para utilizar estas poderosas herramientas. En conclusión, la IA representa un cambio de paradigma que ninguna empresa puede permitirse ignorar. + +**Marcadores IA:** «En el mundo digital actual» · «de vanguardia» · «optimizar» · «transformar» · «integral» · «revolucionario» · «Además / Asimismo / Por otro lado» · «Es importante señalar» · «sin fisuras» · «holístico» · «En conclusión» · oraciones simétricas · gerundios excesivos + +--- + +## DESPUÉS (human-ai v4) + +``` +[LANG: es] +[TONE: human] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 90/100] + +La mayoría de las empresas compran herramientas de IA. Y no las usan. No es que «todavía no». No las usan. + +Encuestamos a 200 equipos que compraron software de IA en 2025. Seis meses después: +- El 23 % lo usaba a diario +- El 41 % lo abría una vez por semana o menos +- El 36 % ya había cancelado la suscripción + +El 23 % no tenía más presupuesto. Ni mejores científicos de datos. Hicieron una cosa distinta: eligieron un solo flujo de trabajo y lo automatizaron por completo. No cinco flujos a medias. Uno. De principio a fin. + +Así se ve en la práctica. + +Un equipo de soporte de 12 personas. 400 tickets al día. Antes de la IA: tiempo medio de respuesta — 7 horas. Los jefes pasaban 3 horas al día asignando tickets. Después: la IA lee la consulta, redacta un borrador de respuesta y lo envía a la persona adecuada. Los jefes dejan de asignar. Los agentes dejan de escribir lo mismo 40 veces al día. El tiempo de respuesta baja a 90 minutos. + +La tecnología no fue lo más difícil. Lo difícil fue resistirse a querer «transformarlo todo» la primera semana. + +--- +[CHANGELOG] +- Apertura eliminada: «En el mundo digital actual...» +- Palabras quemadas: de vanguardia, optimizar, transformar, integral, revolucionario, sin fisuras, holístico, aprovechar (8x) +- Transiciones eliminadas: Además, Asimismo, Por otro lado, Es importante señalar +- «En conclusión» eliminado +- Especificidad: 200 equipos, 23/41/36 %, 12 personas, 400 tickets/día, 7h→90min [VERIFICAR: cifras ilustrativas] +- Tono: human — directo, con datos, ejemplo concreto +- Ritmo: mezcla de fragmentos y oraciones variables, sin secuencias monótonas +``` diff --git a/examples/es-landing.md b/examples/es-landing.md new file mode 100644 index 0000000..1198720 --- /dev/null +++ b/examples/es-landing.md @@ -0,0 +1,40 @@ +# Ejemplo: ES Landing Page + +## ANTES (texto generado por IA) + +Bienvenido a TaskFlow — la plataforma revolucionaria de gestión de proyectos para equipos modernos. Nuestra solución robusta y de vanguardia aprovecha la inteligencia artificial para optimizar los flujos de trabajo y facilitar una colaboración sin fisuras en toda su organización. Con funciones de primer nivel y una interfaz intuitiva y fácil de usar, TaskFlow empodera a los equipos para alcanzar niveles de productividad sin precedentes. Tanto si eres una startup pequeña como una gran empresa, nuestra plataforma integral te ofrece todo lo necesario para optimizar las operaciones e impulsar el crecimiento. Comienza hoy y descubre el futuro del trabajo. Nuestra misión es transformar la forma en que los equipos colaboran en la era digital. Descubre más sobre nuestro enfoque innovador y únete a los miles de clientes satisfechos que ya han dado el paso. + +**Marcadores IA:** «Bienvenido a» · «revolucionario» · «robusta y de vanguardia» (adj pileup) · «aprovechar» · «optimizar» · «sin fisuras» · «de primer nivel» · «intuitiva y fácil de usar» (adj pileup) · «empoderar» · «sin precedentes» · «integral» · «Comienza hoy» · «Nuestra misión» · «Descubre más» · «miles de clientes satisfechos» + +--- + +## DESPUÉS (human-ai v4) + +``` +[LANG: es] +[TONE: landing] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 92/100] + +Las tareas, plazos y archivos de tu equipo. En un solo lugar. No en seis. + +TaskFlow reemplaza los hilos de Slack, los trackers en hojas de cálculo y los correos de «¿dónde está ese documento?». La mayoría de los equipos lo configuran en una tarde. El lunes por la mañana, todos saben qué hacer. + +Los equipos que usan TaskFlow entregan proyectos un 30 % más rápido. No porque trabajen más. Sino porque nadie pasa el martes averiguando qué cambió durante el fin de semana. + +Planes desde $12 por persona al mes. Sin cuota de instalación. Cancela cuando quieras. Tus datos se exportan en un clic — no los retenemos como rehenes. + +[Empieza ahora →] + +--- +[CHANGELOG] +- Apertura: «Bienvenido a TaskFlow» → gancho: «Las tareas. En un solo lugar.» +- Palabras quemadas: revolucionario, robusto, de vanguardia, aprovechar, optimizar, sin fisuras, de primer nivel, intuitiva, fácil de usar, empoderar, sin precedentes, integral, innovador (13x) +- Prueba social: «miles de clientes satisfechos» → «30 % más rápido» con mecanismo +- CTA: «Comienza hoy» → «Empieza ahora →» +- «Nuestra misión» → eliminado +- «Descubre más» → eliminado +- Falso balance «tanto si... como...» → eliminado +- Tono: landing — ajustado, centrado en beneficios, seguro +- Ritmo: mezcla de cláusulas, peso visual variado +``` diff --git a/examples/fr-blog-post.md b/examples/fr-blog-post.md new file mode 100644 index 0000000..2015ac5 --- /dev/null +++ b/examples/fr-blog-post.md @@ -0,0 +1,43 @@ +# Exemple: FR Article de blog + +## AVANT (texte généré par IA) + +Dans le paysage numérique actuel en constante évolution, les entreprises s'appuient de plus en plus sur des solutions d'intelligence artificielle de pointe pour optimiser leurs flux de travail et transformer leurs opérations. Ce guide complet explore la puissance révolutionnaire de l'IA et la manière dont les organisations peuvent exploiter son potentiel pour rester compétitives. En outre, nous examinerons les stratégies clés qui facilitent une intégration transparente des outils d'IA dans les processus existants. Il convient de noter que, bien que certains experts soulèvent des préoccupations, les avantages dépassent largement les risques. Par ailleurs, une mise en œuvre réussie nécessite une approche holistique prenant en compte les facteurs techniques et humains. De plus, les entreprises doivent veiller à former leurs équipes pour utiliser ces nouveaux outils de manière efficace. En conclusion, l'IA représente un changement de paradigme incontournable. + +**Marqueurs IA:** «Dans le paysage numérique actuel» · «de pointe» · «optimiser» · «transformer» · «complet» · «révolutionnaire» · «En outre / Par ailleurs / De plus» · «Il convient de noter» · «holistique» · «transparente» · «En conclusion» · phrases symétriques · nominalisations excessives + +--- + +## APRÈS (human-ai v4) + +``` +[LANG: fr] +[TONE: human] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 89/100] + +La plupart des boîtes achètent des outils d'IA. Et ne s'en servent pas. Pas «pas encore». Pas du tout. + +On a interrogé 200 équipes qui ont acheté un logiciel d'IA en 2025. Six mois plus tard: +- 23 % l'utilisaient tous les jours +- 41 % l'ouvraient une fois par semaine ou moins +- 36 % avaient déjà résilié leur abonnement + +Les 23 % n'avaient pas un plus gros budget. Ni de meilleurs data scientists. Ils ont fait un truc différemment: ils ont choisi un seul workflow et l'ont automatisé à fond. Pas cinq workflows à moitié. Un seul. Du début à la fin. + +Voilà ce que ça donne. + +Une équipe support de 12 personnes. 400 tickets par jour. Avant l'IA: temps de réponse moyen — 7 heures. Les managers passaient 3 heures par jour à attribuer les tickets. Après: l'IA lit la demande, rédige un brouillon de réponse et l'envoie à la bonne personne. Les managers arrêtent d'attribuer. Les agents arrêtent de taper 40 fois la même réponse. Le temps de réponse tombe à 90 minutes. + +La technologie n'était pas le plus dur. Le plus dur, c'était de ne pas vouloir tout changer d'un coup. + +--- +[CHANGELOG] +- Accroche supprimée: «Dans le paysage numérique actuel...» +- Mots brûlés retirés: de pointe, optimiser, transformer, complet, révolutionnaire, holistique, transparente, exploitent (8x) +- Transitions tuées: En outre, Par ailleurs, De plus, Il convient de noter +- «En conclusion» supprimé +- Concret ajouté: 200 équipes, 23/41/36 %, 12 personnes, 400 tickets/jour, 7h→90min [VÉRIFIER: chiffres illustratifs] +- Ton: human — direct, chiffré, exemple concret +- Rythme: fragments + phrases variables, ruptures de rythme volontaires +``` diff --git a/examples/fr-social.md b/examples/fr-social.md new file mode 100644 index 0000000..98a698f --- /dev/null +++ b/examples/fr-social.md @@ -0,0 +1,37 @@ +# Exemple: FR Post LinkedIn + +## AVANT (texte généré par IA) + +Dans le contexte professionnel actuel, une communication efficace est plus cruciale que jamais. Il convient de noter que les équipes qui communiquent bien sont 25 % plus productives. En outre, une communication claire facilite la prise de décision et permet aux collaborateurs de s'approprier leurs missions. Par ailleurs, les organisations devraient investir dans des outils et des formations pour optimiser la collaboration. En définitive, la communication est la clé du succès. + +**Marqueurs IA:** «Dans le contexte professionnel actuel» · «Il convient de noter» · «En outre / Par ailleurs» · «facilite / optimiser» · «En définitive» · 13mots-15mots-12mots — longueurs quasi identiques · paragraphe parfaitement équilibré + +--- + +## APRÈS (human-ai v4) + +``` +[LANG: fr] +[TONE: social] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 93/100] + +Votre équipe n'a pas un problème de communication. Elle a un problème de «où est-ce qu'on a foutu ce fichier». + +J'ai regardé une équipe de 8 personnes chercher un contrat pendant 4 heures. Quatre heures. Il était dans Slack. Quelqu'un l'avait envoyé. Dans un fil de discussion. Il y a trois mois. + +Après cette réunion, on a tout mis sur un drive unique. Une règle: si c'est pas là, ça existe pas. Le temps en réunion a été divisé par deux. Pas parce que les gens parlaient moins. Parce qu'ils ont arrêté de dire «quelqu'un peut retrouver ce doc?» + +L'outil n'avait aucune importance. La règle, si. + +--- +[CHANGELOG] +- Accroche tuée: «Dans le contexte professionnel actuel» +- Mots brûlés: facilite, optimiser (2x) +- Transitions: En outre, Par ailleurs → supprimées +- Hedging: «Il convient de noter» → supprimé +- Conclusion: «En définitive» → remplacée par une punchline +- Concret: 8 personnes, 4 heures, scénario réel [VÉRIFIER: illustratif] +- Ton: social — accroche, micro-histoire, chute qui frappe +- Rythme: fragments, variation des longueurs, fin percutante +``` diff --git a/examples/it-blog-post.md b/examples/it-blog-post.md new file mode 100644 index 0000000..133739b --- /dev/null +++ b/examples/it-blog-post.md @@ -0,0 +1,43 @@ +# Esempio: IT Articolo di blog + +## PRIMA (testo generato da IA) + +Nel panorama digitale odierno in rapida evoluzione, le aziende adottano sempre più soluzioni di intelligenza artificiale all'avanguardia per ottimizzare i flussi di lavoro e trasformare le proprie operazioni. Questa guida completa esplora il potere rivoluzionario dell'IA e come le organizzazioni possano sfruttare il suo potenziale per rimanere competitive. Inoltre, esamineremo le strategie chiave che facilitano un'integrazione senza soluzione di continuità degli strumenti di IA nei processi aziendali esistenti. È importante sottolineare che, sebbene alcuni esperti evidenzino dei rischi, i benefici superano di gran lunga i potenziali svantaggi. Peraltro, un'implementazione di successo richiede un approccio olistico che consideri sia i fattori tecnici che quelli umani. D'altro canto, le aziende devono garantire una formazione adeguata dei team per utilizzare questi potenti strumenti. In conclusione, l'IA rappresenta un cambiamento di paradigma che nessuna azienda può permettersi di ignorare. + +**Marcatori IA:** «Nel panorama digitale odierno» · «all'avanguardia» · «ottimizzare» · «trasformare» · «completa» · «rivoluzionario» · «sfruttare» · «Inoltre / Peraltro / D'altro canto» · «È importante sottolineare» · «senza soluzione di continuità» · «olistico» · «In conclusione» · frasi simmetriche · formale eccessivo + +--- + +## DOPO (human-ai v4) + +``` +[LANG: it] +[TONE: human] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 87/100] + +La maggior parte delle aziende compra strumenti di IA. E non li usa. Non «non ancora». Proprio non li usa. + +Abbiamo intervistato 200 team che hanno comprato software IA nel 2025. Dopo sei mesi: +- Il 23 % lo usava ogni giorno +- Il 41 % lo apriva una volta a settimana o meno +- Il 36 % aveva già cancellato l'abbonamento + +Quel 23 % non aveva più budget. Né data scientist migliori. Hanno fatto una cosa diversa: hanno scelto un solo flusso di lavoro e l'hanno automatizzato del tutto. Non cinque flussi a metà. Uno. Dall'inizio alla fine. + +Ecco come funziona. + +Un team di assistenza da 12 persone. 400 ticket al giorno. Prima dell'IA: tempo medio di risposta — 7 ore. I responsabili passavano 3 ore al giorno ad assegnare i ticket. Dopo: l'IA legge la richiesta, scrive una bozza di risposta e la gira alla persona giusta. I responsabili smettono di assegnare. Gli agenti smettono di scrivere la stessa risposta 40 volte. Il tempo di risposta scende a 90 minuti. + +La tecnologia non è stata la parte difficile. La parte difficile è stata resistere alla tentazione di «cambiare tutto» nella prima settimana. + +--- +[CHANGELOG] +- Apertura rimossa: «Nel panorama digitale odierno...» +- Parole bruciate: all'avanguardia, ottimizzare, trasformare, completa, rivoluzionario, sfruttare, senza soluzione di continuità, olistico (8x) +- Transizioni eliminate: Inoltre, Peraltro, D'altro canto, È importante sottolineare +- «In conclusione» rimosso +- Specificità: 200 team, 23/41/36 %, 12 persone, 400 ticket/giorno, 7h→90min [VERIFICARE: numeri illustrativi] +- Tono: human — diretto, basato su dati, esempio concreto +- Ritmo: frammenti + frasi di lunghezza variabile, rotture di ritmo intenzionali +``` diff --git a/examples/it-landing.md b/examples/it-landing.md new file mode 100644 index 0000000..0bba58f --- /dev/null +++ b/examples/it-landing.md @@ -0,0 +1,40 @@ +# Esempio: IT Landing Page + +## PRIMA (testo generato da IA) + +Benvenuto in TaskFlow — la piattaforma rivoluzionaria di gestione progetti per team moderni. La nostra soluzione robusta e all'avanguardia sfrutta l'intelligenza artificiale per ottimizzare i flussi di lavoro e facilitare una collaborazione senza soluzione di continuità in tutta l'organizzazione. Con funzionalità best-in-class e un'interfaccia intuitiva e facile da usare, TaskFlow potenzia i team per raggiungere livelli di produttività senza precedenti. Che tu sia una piccola startup o una grande impresa, la nostra piattaforma completa offre tutto il necessario per ottimizzare le operazioni e favorire la crescita. Inizia oggi e scopri il futuro del lavoro. La nostra missione è trasformare il modo in cui i team collaborano nell'era digitale. Scopri di più sul nostro approccio innovativo e unisciti alle migliaia di clienti soddisfatti che hanno già fatto il passo. + +**Marcatori IA:** «Benvenuto in» · «rivoluzionario» · «robusta e all'avanguardia» (adj pileup) · «sfruttare» · «ottimizzare» · «senza soluzione di continuità» · «best-in-class» · «intuitiva e facile da usare» (adj pileup) · «potenziare» · «senza precedenti» · «completa» · «Inizia oggi» · «La nostra missione» · «Scopri di più» · «migliaia di clienti soddisfatti» + +--- + +## DOPO (human-ai v4) + +``` +[LANG: it] +[TONE: landing] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 91/100] + +Compiti, scadenze e file del tuo team. In un unico posto. Non sei. + +TaskFlow sostituisce i thread di Slack, i tracker nei fogli di calcolo e le email con scritto «dov'è quel documento?». La maggior parte dei team lo configura in un pomeriggio. Lunedì mattina, tutti sanno cosa fare. + +I team su TaskFlow consegnano i progetti il 30 % più velocemente. Non perché lavorino di più. Ma perché nessuno passa il martedì a capire cos'è cambiato nel fine settimana. + +Piani da 12 € a persona al mese. Nessun costo di attivazione. Disdici quando vuoi. I tuoi dati si esportano in un clic — non li teniamo in ostaggio. + +[Inizia ora →] + +--- +[CHANGELOG] +- Apertura: «Benvenuto in TaskFlow» → gancio: «Compiti. In un unico posto.» +- Parole bruciate: rivoluzionario, robusto, all'avanguardia, sfruttare, ottimizzare, senza soluzione di continuità, best-in-class, intuitiva, facile da usare, potenziare, senza precedenti, completa, innovativo (13x) +- Prova sociale: «migliaia di clienti soddisfatti» → «30 % più veloce» con meccanismo +- CTA: «Inizia oggi» → «Inizia ora →» +- «La nostra missione» → rimosso +- «Scopri di più» → rimosso +- Falso bilanciamento «che tu sia... o...» → rimosso +- Tono: landing — stringato, focalizzato sui benefici, sicuro +- Ritmo: mix di clausole, peso visivo variabile +``` diff --git a/examples/pl-blog-post.md b/examples/pl-blog-post.md new file mode 100644 index 0000000..cbb0d44 --- /dev/null +++ b/examples/pl-blog-post.md @@ -0,0 +1,43 @@ +# Przykład: PL Artykuł blogowy + +## PRZED (tekst wygenerowany przez AI) + +W dzisiejszym szybko zmieniającym się krajobrazie cyfrowym firmy coraz częściej wykorzystują najnowocześniejsze rozwiązania sztucznej inteligencji, aby optymalizować przepływy pracy i transformować swoje operacje. Ten kompleksowy przewodnik bada rewolucyjną moc AI i pokazuje, w jaki sposób organizacje mogą wykorzystywać jej potencjał, by pozostać konkurencyjnymi. Ponadto przeanalizujemy kluczowe strategie, które umożliwiają bezproblemową integrację narzędzi AI z istniejącymi procesami biznesowymi. Należy zauważyć, że choć niektórzy eksperci wskazują na zagrożenia, korzyści znacząco przewyższają potencjalne ryzyko. Co więcej, skuteczne wdrożenie wymaga holistycznego podejścia uwzględniającego zarówno czynniki techniczne, jak i ludzkie. Dodatkowo firmy muszą zapewnić odpowiednie przeszkolenie zespołów, aby efektywnie korzystać z tych potężnych narzędzi. Podsumowując, sztuczna inteligencja stanowi zmianę paradygmatu, której żaden biznes nie może sobie pozwolić zignorować. + +**Markery AI:** «W dzisiejszym cyfrowym świecie» · «najnowocześniejszy» · «optymalizować» · «transformować» · «kompleksowy» · «rewolucyjny» · «wykorzystywać / umożliwiać» · «Ponadto / Co więcej / Dodatkowo» · «Należy zauważyć» · «holistyczny» · «Podsumowując» · symetryczne długości zdań · nadmierna formalność + +--- + +## PO (human-ai v4) + +``` +[LANG: pl] +[TONE: human] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 86/100] + +Większość firm kupuje narzędzia AI. I ich nie używa. Nie «jeszcze nie». Po prostu nie używa. + +Przepytaliśmy 200 zespołów, które kupiły oprogramowanie AI w 2025 roku. Po sześciu miesiącach: +- 23 % używało go codziennie +- 41 % otwierało raz w tygodniu lub rzadziej +- 36 % już anulowało subskrypcję + +Te 23 % nie miały większego budżetu. Ani lepszych data scientistów. Zrobiły jedną rzecz inaczej: wybrały jeden konkretny przepływ pracy i zautomatyzowały go całkowicie. Nie pięć przepływów na pół gwizdka. Jeden. Od początku do końca. + +Tak to wygląda w praktyce. + +Zespół wsparcia, 12 osób. 400 zgłoszeń dziennie. Przed AI: średni czas odpowiedzi — 7 godzin. Kierownicy spędzali 3 godziny dziennie na ręcznym przydzielaniu zgłoszeń. Po wdrożeniu: AI czyta zgłoszenie, pisze szkic odpowiedzi i przekazuje je właściwej osobie. Kierownicy przestają przydzielać. Agenci przestają pisać to samo 40 razy. Czas odpowiedzi spada do 90 minut. + +Najtrudniejsza nie była technologia. Najtrudniejsze było powstrzymanie się od chęci «zrewolucjonizowania wszystkiego» w pierwszym tygodniu. + +--- +[CHANGELOG] +- Wstęp usunięty: «W dzisiejszym szybko zmieniającym się krajobrazie...» +- Spalone słowa: najnowocześniejszy, optymalizować, transformować, kompleksowy, rewolucyjny, wykorzystywać, umożliwiać, holistyczny (8x) +- Przejścia wycięte: Ponadto, Co więcej, Dodatkowo, Należy zauważyć +- «Podsumowując» usunięte +- Konkrety: 200 zespołów, 23/41/36 %, 12 osób, 400 zgłoszeń/dzień, 7h→90min [SPRAWDZIĆ: liczby ilustracyjne] +- Ton: human — bezpośredni, oparty na danych, konkretny przykład +- Rytm: fragmenty + zdania o zmiennej długości, celowe łamanie rytmu +``` diff --git a/examples/pl-social.md b/examples/pl-social.md new file mode 100644 index 0000000..ebf13b4 --- /dev/null +++ b/examples/pl-social.md @@ -0,0 +1,37 @@ +# Przykład: PL Post na LinkedIn + +## PRZED (tekst wygenerowany przez AI) + +W dzisiejszym konkurencyjnym środowisku biznesowym skuteczna komunikacja jest ważniejsza niż kiedykolwiek. Należy zauważyć, że zespoły, które dobrze się komunikują, są o 25 % bardziej produktywne. Ponadto jasna komunikacja usprawnia podejmowanie decyzji i umożliwia pracownikom przejmowanie odpowiedzialności za swoją pracę. Dodatkowo organizacje powinny inwestować w narzędzia i szkolenia, aby optymalizować współpracę w zespole. Konkluzja jest jasna: komunikacja to klucz do sukcesu. + +**Markery AI:** «W dzisiejszym konkurencyjnym środowisku» · «Należy zauważyć» · «Ponadto / Dodatkowo» · «usprawnia / umożliwia / optymalizować» · «Konkluzja jest jasna» · 12słów-13słów-12słów — prawie identyczne długości · idealnie zbalansowany akapit + +--- + +## PO (human-ai v4) + +``` +[LANG: pl] +[TONE: social] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 93/100] + +Twój zespół nie ma problemu z komunikacją. Ma problem z «gdzie do cholery jest ten plik». + +Patrzyłem, jak 8-osobowy zespół szuka umowy przez 4 godziny. Cztery godziny. Była na Slacku. Ktoś ją wysłał. W wątku. Trzy miesiące temu. + +Po tym spotkaniu wrzuciliśmy wszystko na jeden wspólny dysk. Jedna zasada: jeśli czegoś tam nie ma, to nie istnieje. Czas spotkań spadł o połowę. Nie dlatego, że ludzie mniej mówili. Tylko dlatego, że przestali pytać «ktoś znajdzie ten dokument?» + +Nie narzędzie miało znaczenie. Zasada. + +--- +[CHANGELOG] +- Wstęp zabity: «W dzisiejszym konkurencyjnym środowisku biznesowym» +- Spalone słowa: usprawnia, umożliwia, optymalizować (3x) +- Przejścia: Ponadto, Dodatkowo → wyeliminowane +- Hedging: «Należy zauważyć» → usunięte +- Konkluzja: «Konkluzja jest jasna» → zastąpiona pointą +- Konkrety: 8 osób, 4 godziny, prawdziwy scenariusz [SPRAWDZIĆ: ilustracyjny] +- Ton: social — haczyk, mikro-historia, mocne zakończenie +- Rytm: fragmenty, zmienna długość zdań, suche zakończenie +``` diff --git a/examples/pt-blog-post.md b/examples/pt-blog-post.md new file mode 100644 index 0000000..6a54fe9 --- /dev/null +++ b/examples/pt-blog-post.md @@ -0,0 +1,43 @@ +# Exemplo: PT Artigo de blog + +## ANTES (texto gerado por IA) + +No cenário digital atual em rápida evolução, as empresas estão cada vez mais a adotar soluções de inteligência artificial de ponta para otimizar os seus fluxos de trabalho e transformar as suas operações. Este guia abrangente explora o poder revolucionário da IA e a forma como as organizações podem alavancar o seu potencial para se manterem competitivas. Além disso, examinaremos estratégias-chave que facilitam uma integração transparente das ferramentas de IA nos processos empresariais existentes. É importante notar que, embora alguns especialistas apontem riscos, os benefícios superam largamente os potenciais inconvenientes. Ademais, uma implementação bem-sucedida requer uma abordagem holística que considere tanto fatores técnicos quanto humanos. Por conseguinte, as empresas devem garantir a formação adequada das equipas para utilizar estas poderosas ferramentas. Em conclusão, a IA representa uma mudança de paradigma que nenhuma empresa se pode dar ao luxo de ignorar. + +**Marcadores IA:** «No cenário digital atual» · «de ponta» · «otimizar» · «transformar» · «abrangente» · «revolucionário» · «alavancar» · «Além disso / Ademais / Por conseguinte» · «É importante notar» · «transparente» · «holística» · «Em conclusão» · frases simétricas · gerundismo excessivo + +--- + +## DEPOIS (human-ai v4) + +``` +[LANG: pt] +[TONE: human] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 88/100] + +A maioria das empresas compra ferramentas de IA. E não as usa. Não é «ainda não». É não usa mesmo. + +Entrevistámos 200 equipas que compraram software de IA em 2025. Seis meses depois: +- 23 % usavam-no todos os dias +- 41 % abriam-no uma vez por semana ou menos +- 36 % já tinham cancelado a subscrição + +Os 23 % não tinham mais orçamento. Nem melhores cientistas de dados. Fizeram uma coisa diferente: escolheram um único fluxo de trabalho e automatizaram-no por completo. Não cinco fluxos pela metade. Um. Do início ao fim. + +É assim que funciona na prática. + +Uma equipa de suporte com 12 pessoas. 400 tickets por dia. Antes da IA: tempo médio de resposta — 7 horas. Os gestores passavam 3 horas por dia a atribuir tickets. Depois: a IA lê o pedido, redige um rascunho de resposta e encaminha-o para a pessoa certa. Os gestores deixam de atribuir. Os agentes deixam de escrever a mesma resposta 40 vezes. O tempo de resposta cai para 90 minutos. + +A tecnologia não foi a parte mais difícil. O mais difícil foi resistir à vontade de «transformar tudo» na primeira semana. + +--- +[CHANGELOG] +- Abertura removida: «No cenário digital atual...» +- Palavras queimadas: de ponta, otimizar, transformar, abrangente, revolucionário, alavancar, transparente, holística (8x) +- Transições eliminadas: Além disso, Ademais, Por conseguinte, É importante notar +- «Em conclusão» removido +- Especificidade: 200 equipas, 23/41/36 %, 12 pessoas, 400 tickets/dia, 7h→90min [VERIFICAR: números ilustrativos] +- Tom: human — direto, com dados, exemplo concreto +- Ritmo: fragmentos + frases variáveis, quebras de ritmo intencionais +``` diff --git a/examples/pt-social.md b/examples/pt-social.md new file mode 100644 index 0000000..efd3dc9 --- /dev/null +++ b/examples/pt-social.md @@ -0,0 +1,37 @@ +# Exemplo: PT Post no LinkedIn + +## ANTES (texto gerado por IA) + +No mundo competitivo dos negócios de hoje, uma comunicação eficaz é mais importante do que nunca. É importante notar que as equipas que comunicam bem são 25 % mais produtivas. Além disso, uma comunicação clara facilita a tomada de decisões e empodera os colaboradores a assumirem as suas responsabilidades. Ademais, as organizações devem investir em ferramentas e formação para otimizar a colaboração entre equipas. A conclusão é clara: a comunicação é a chave para o sucesso. + +**Marcadores IA:** «No mundo competitivo» · «É importante notar» · «Além disso / Ademais» · «facilita / empodera / otimizar» · «A conclusão é clara» · 13palavras-14palavras-13palavras — comprimentos quase iguais · parágrafo perfeitamente equilibrado + +--- + +## DEPOIS (human-ai v4) + +``` +[LANG: pt] +[TONE: social] +[PIPELINE: cleanup → specificity → tone → rhythm → proofread] +[QUALITY: 94/100] + +A tua equipa não tem um problema de comunicação. Tem um problema de «onde é que se meteu aquele ficheiro». + +Assisti a uma equipa de 8 pessoas a procurar um contrato durante 4 horas. Quatro horas. Estava no Slack. Alguém o tinha enviado. Numa thread. Há três meses. + +Depois dessa reunião, metemos tudo numa drive partilhada. Uma regra: se não está lá, não existe. O tempo de reuniões caiu para metade. Não porque as pessoas falassem menos. Porque deixaram de dizer «alguém encontra esse documento?» + +A ferramenta não importava. A regra sim. + +--- +[CHANGELOG] +- Abertura morta: «No mundo competitivo dos negócios de hoje» +- Palavras queimadas: facilita, empodera, otimizar (3x) +- Transições: Além disso, Ademais → eliminadas +- Hedging: «É importante notar» → removido +- Conclusão: «A conclusão é clara» → substituída por punchline +- Especificidade: 8 pessoas, 4 horas, cenário real [VERIFICAR: ilustrativo] +- Tom: social — gancho, micro-história, fecho impactante +- Ritmo: fragmentos, variação de comprimento, final seco +``` diff --git a/scenarios/blog-post.md b/scenarios/blog-post.md index 5a49990..8ed78ba 100644 --- a/scenarios/blog-post.md +++ b/scenarios/blog-post.md @@ -1,42 +1,45 @@ # Scenario: Blog Post **Use when:** Humanizing a blog post, article, essay, or long-form opinion piece. +**Default tone:** `human` -**Default tone:** `human` (override available: `article`, `expert`) - -## Key priorities (ordered) - -1. **Kill the template structure.** No "Introduction → Body → Conclusion" skeleton. Open with a specific observation, problem, or story - not context. -2. **Opinion required.** Blog posts without an opinion are AI. State the writer's actual position. No fake balance. -3. **Specificity over everything.** Every abstract claim gets a concrete example, number, or micro-story. -4. **Natural flow.** Section transitions by topic logic - not "Firstly, Secondly, Thirdly." -5. **End on substance.** No "In conclusion" restating what was just said. Last paragraph: a clear takeaway, a question, or a next step. - -## Rhythm targets - -- Short sentences every 3-5 sentences -- Fragments: 1-2 per 100 words (qualitative target - use feel, not counting) -- Conjunction openers: 2-4 per 100 words (qualitative target) -- Sentence length: high variance (fragment to 3-clause) -- Paragraphs: varied visual weight (light/medium/heavy mix) - -## What to cut aggressively +## Key Priorities +1. Kill the template structure — no "Introduction → Body → Conclusion" skeleton. Open with a specific observation, problem, or story - not context +2. Opinion required — blog posts without an opinion are AI. State the writer's actual position. No fake balance +3. Specificity over everything — every abstract claim gets a concrete example, number, or micro-story +4. Natural flow — section transitions by topic logic, not "Firstly, Secondly, Thirdly" +5. End on substance — no "In conclusion" restating what was just said. Last paragraph: a clear takeaway, a question, or a next step +## What to Cut - "In today's world..." openers - "This article will explore..." meta-text - "In conclusion / To summarize..." endings - Generalized examples ("many companies...", "a lot of people...") - Adjective strings before nouns -## Language-specific notes - -**RU:** Fight academic tone. Russian blog = smart colleague explaining over coffee. Slightly more formal than EN human tone. -**UK:** Warmer than RU baseline. Emotional connection works without losing credibility. -**DE:** Kein Nominalstil. Aktiv statt Passiv. Natürliche Modalpartikeln. -**FR:** «On» over «nous». Éviter le plan en trois parties. Style conversationnel mais précis. -**ES/PT/IT/PL:** Active voice, natural connectors, no academic residue. - -## Pipeline Recommendations +## What to Preserve +- Author's unique voice and opinion +- Concrete examples, data, and specific references +- Section structure driven by topic logic (not templates) +- Quotes and attributed material + +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | 1-2 per 100 words (qualitative — use feel, not counting) | +| Conjunction spacing | 2-4 per 100 words (qualitative target) | +| Max consecutive same category | 2 | + +Additional targets: short sentences every 3-5 sentences. Sentence length: high variance (fragment to 3-clause). Paragraphs: varied visual weight (light/medium/heavy mix). + +## Language Notes +- RU: Fight academic tone. Russian blog = smart colleague explaining over coffee. Slightly more formal than EN human tone +- UK: Warmer than RU baseline. Emotional connection works without losing credibility +- DE: Kein Nominalstil. Aktiv statt Passiv. Natürliche Modalpartikeln +- FR: «On» over «nous». Éviter le plan en trois parties. Style conversationnel mais précis +- ES/PT/IT/PL: Active voice, natural connectors, no academic residue + +## Pipeline - Likely needed: cleanup (AI openers and structure), specificity (blog needs concrete examples), tone (human voice) - Often skippable: none for full pipeline - Never skip: proofread diff --git a/scenarios/case-study.md b/scenarios/case-study.md index ee4844c..9ec1492 100644 --- a/scenarios/case-study.md +++ b/scenarios/case-study.md @@ -1,37 +1,49 @@ # Scenario: Case Study / Portfolio **Use when:** Humanizing a case study, success story, portfolio piece, client result page. - **Default tone:** `case` -## Required structure +## Key Priorities +1. Numbers are non-negotiable — before/after specifics. "Cut deployment time by 60%" not "significantly improved" +2. The failed attempt is mandatory — even if minor. "We tried X first. It didn't work because..." +3. Client voice where real — if source has actual quotes, use them. Never fabricate +4. Lessons, not boasts — end with what was learned, not how great the result was +5. Kill all case-study clichés — no: "seamless implementation", "exceeded expectations", "delighted the client", "a pleasure to work with" +## Required structure Context → Problem → Attempt 1 (failed) → Attempt 2 (worked) → Numbers → Lessons -**Honesty is the differentiator.** Include what went wrong. Readers trust a case study that admits a failed attempt more than one claiming everything went perfectly. - -## Key priorities - -1. **Numbers are non-negotiable.** Before/after. Specifics. "Cut deployment time by 60%" - not "significantly improved." -2. **The failed attempt is mandatory.** Even if minor. "We tried X first. It didn't work because..." -3. **Client voice where real.** If source has actual quotes, use them. Never fabricate. -4. **Lessons, not boasts.** End with what was learned, not how great the result was. -5. **Kill all case-study clichés.** No: "seamless implementation", "exceeded expectations", "delighted the client", "a pleasure to work with." - -## Rhythm targets - -- Short sentences every 4-5 sentences -- Fragments: every 5-7 sentences -- Conjunction openers: every 5-7 sentences -- Max consecutive same category: 2 - -## Language-specific notes - -**RU:** Russian case studies tend to skip failures - include them. Builds massive trust. Specific technical details are respected. Keep client quotes real. -**UK:** Ukrainian business culture appreciates directness. Include failures. Numbers + honest narrative = trust. -**All languages:** A flawless case study reads as fake. Authenticity > polish. - -## Pipeline Recommendations +Honesty is the differentiator. Include what went wrong. Readers trust a case study that admits a failed attempt more than one claiming everything went perfectly. + +## What to Cut +- "Seamless implementation" +- "Exceeded expectations" +- "Delighted the client" +- "A pleasure to work with" +- Any claim without specific numbers or evidence + +## What to Preserve +- Real client quotes (verbatim) +- Before/after numbers and metrics +- The failed attempt narrative (even if minor) +- Specific technical details +- Lessons learned + +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Every 5-7 sentences | +| Conjunction spacing | Every 5-7 sentences | +| Max consecutive same category | 2 | + +Additional targets: short sentences every 4-5 sentences. + +## Language Notes +- RU: Russian case studies tend to skip failures — include them. Builds massive trust. Specific technical details are respected. Keep client quotes real +- UK: Ukrainian business culture appreciates directness. Include failures. Numbers + honest narrative = trust +- All languages: A flawless case study reads as fake. Authenticity > polish + +## Pipeline - Likely needed: cleanup (case-study cliches), specificity (numbers non-negotiable), tone (case voice with honesty) - Often skippable: rhythm (case study structure creates natural variance) - Never skip: proofread diff --git a/scenarios/commercial-offer.md b/scenarios/commercial-offer.md index 6e6896f..5631346 100644 --- a/scenarios/commercial-offer.md +++ b/scenarios/commercial-offer.md @@ -1,46 +1,49 @@ # Scenario: Commercial Offer (B2B) **Use when:** Humanizing a B2B commercial proposal, service page, sales deck text, or partnership pitch. - **Default tone:** `biz` -## Key priorities - -1. **No small talk. No warm-up.** Start with what you do. "We build X for companies that need Y." -2. **Claims with evidence.** Every claim backed by a number, example, or mechanism. No "best-in-class" without specifics. -3. **Politeness through clarity**, not pleasantries. "Here's what we do. Here's the timeline. Here's the cost." -4. **Direct questions are fine:** "What do you want to see in 6 months?" / "What's the current bottleneck?" -5. **Respect the reader's time.** Every paragraph should answer a real question they have. - -## Rhythm targets - -- Short sentences every 6-8 sentences -- Fragments: rare (1-2 per entire document) -- Conjunction openers: rare (1-2 per entire document) -- Max consecutive same category: 2 - -## What to cut +## Key Priorities +1. No small talk, no warm-up — start with what you do. "We build X for companies that need Y" +2. Claims with evidence — every claim backed by a number, example, or mechanism. No "best-in-class" without specifics +3. Politeness through clarity, not pleasantries — "Here's what we do. Here's the timeline. Here's the cost" +4. Direct questions are fine: "What do you want to see in 6 months?" / "What's the current bottleneck?" +5. Respect the reader's time — every paragraph should answer a real question they have +## What to Cut - "We are thrilled to..." - "Our mission is..." - "Partner with us on a journey..." - "Leveraging synergies..." - Any claim without evidence or example -## Language-specific notes - -**RU:** «Вы» always. Minimal emotional language. Results, not feelings. No: «рады предложить», «наша миссия». -**UK:** «Ви» always. European business style - cleaner than post-Soviet. No: «раді запропонувати». -**DE:** «Sie» immer. Direkt, sachlich. Kein: «wir freuen uns». -**FR:** «Vous» toujours. Direct, factuel. Pas de: «nous sommes ravis». -**ES:** «Usted» siempre. Datos, no entusiasmo. -**PT/IT/PL:** Formal address always. Facts over enthusiasm. - -## Output format notes - -Preserve proposal structure if present (sections, bullet points) but humanize the language within. Do not flatten a structured proposal into narrative prose. - -## Pipeline Recommendations +## What to Preserve +- Proposal structure (sections, bullet points) — humanize the language within, do not flatten into narrative prose +- Specific numbers, timelines, and deliverables +- Pricing and terms +- Client-specific details and requirements + +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | 1-2 per entire document (rare) | +| Conjunction spacing | 1-2 per entire document (rare) | +| Max consecutive same category | 2 | + +Additional targets: short sentences every 6-8 sentences. + +## Language Notes +- RU: «Вы» always. Minimal emotional language. Results, not feelings. No: «рады предложить», «наша миссия» +- UK: «Ви» always. European business style - cleaner than post-Soviet. No: «раді запропонувати» +- DE: «Sie» immer. Direkt, sachlich. Kein: «wir freuen uns» +- FR: «Vous» toujours. Direct, factuel. Pas de: «nous sommes ravis» +- ES: «Usted» siempre. Datos, no entusiasmo +- PT/IT/PL: Formal address always. Facts over enthusiasm + +## Pipeline - Likely needed: cleanup (enthusiasm removal), specificity (every claim needs evidence), tone (biz directness) - Often skippable: rhythm (commercial text is intentionally measured) - Never skip: proofread + +## Output format notes +Preserve proposal structure if present (sections, bullet points) but humanize the language within. Do not flatten a structured proposal into narrative prose. diff --git a/scenarios/creative-writing.md b/scenarios/creative-writing.md index 600e480..5fc66d6 100644 --- a/scenarios/creative-writing.md +++ b/scenarios/creative-writing.md @@ -3,34 +3,37 @@ **Use when:** Humanizing short stories, creative essays, personal narratives, or literary text. **Default tone:** `human` -## Key priorities +## Key Priorities +1. Lightest possible touch — creative writing's value is in the author's voice. You are removing AI residue, not rewriting the piece +2. Preserve stylistic choices — unusual word order, sentence fragments, dialect, repetition for effect: these are features, not bugs +3. Only fix what's clearly AI — burned words, fake transitions, template structures. Leave everything else +4. No tone override — if the piece is melancholic, don't make it warm. If it's angry, don't make it professional +5. If unsure, don't touch — false positive damage is worse than missing an AI tell in creative text -1. **Lightest possible touch.** Creative writing's value is in the author's voice. You are removing AI residue, not rewriting the piece. -2. **Preserve stylistic choices.** Unusual word order, sentence fragments, dialect, repetition for effect: these are features, not bugs. -3. **Only fix what's clearly AI.** Burned words, fake transitions, template structures. Leave everything else. -4. **No tone override.** If the piece is melancholic, don't make it warm. If it's angry, don't make it professional. -5. **If unsure, don't touch.** False positive damage is worse than missing an AI tell in creative text. - -## Rhythm targets -- DO NOT enforce rhythm rules on creative text -- Author's rhythm is intentional -- Only flag: metronome-like identical sentence lengths (clear AI pattern) -- Fragment and conjunction rules: skip - -## What to cut +## What to Cut - Burned words that slipped in - "In today's world" openers (never belong in creative text) - "In conclusion" endings - Adjective pileups: keep the strongest, show the rest -## What to preserve (always) +## What to Preserve (always) - Dialogue (even if it's "poorly written") - Metaphors, imagery, sensory details - Regional dialect and code-switching - Unusual punctuation used for effect - First-person voice and quirks -## Pipeline Recommendations +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Do NOT enforce rhythm rules on creative text | +| Conjunction spacing | Author's rhythm is intentional — skip rules | +| Max consecutive same category | Only flag metronome-like identical sentence lengths (clear AI pattern) | + +## Language Notes +- All languages: Preserve the author's original voice and stylistic choices. Do not normalize dialect or regional variations + +## Pipeline - Likely needed: cleanup (burned words only) - Often skippable: specificity, tone, rhythm - Never skip: proofread (light scan only) diff --git a/scenarios/email.md b/scenarios/email.md index a2fdac8..692c7b3 100644 --- a/scenarios/email.md +++ b/scenarios/email.md @@ -3,40 +3,14 @@ **Use when:** Humanizing an email - newsletter, welcome sequence, cold outreach, nurture, or transactional. **Default tone:** `human` -## Email-specific rules - -1. **Subject line = the hook.** Under 40 chars. Not "Your weekly update" - "The feature you asked for ships tomorrow." -2. **One idea per email.** If there are 3 topics, send 3 emails. -3. **First sentence = why you're writing.** Not "I hope this email finds you well." -4. **Personal where possible.** "You signed up for X" not "Our valued subscribers." -5. **CTA is one action.** Not 3 links, 2 buttons, and a PS. One thing. - -## By email type - -**Welcome:** Deliver the thing you promised. No 5-paragraph intro. "Here's the guide. Next email: how to set it up." - -**Newsletter:** Lead with the most interesting thing. Not "Welcome to issue #47." Short intro, content, one takeaway. - -**Cold outreach:** 5 lines max. No trust = no social proof. "Hi [name]. I saw [specific observation about their work]. We built [tool] that [one clear outcome]. Worth 15 minutes?" - -**Nurture:** 3-5 emails. Each adds value independent of purchase. No "As we discussed in the previous email..." - -**Cart abandonment:** 1-2 emails. Remind what they left, not why they should buy. "You left [product] in your cart. Questions? Reply to this email." - -## Email Sequences - -**Onboarding (3-5 emails):** Each email = one user action + one result. Day 1: get them to do the core action. Day 3: show them the result of that action. Day 7: advanced feature they've now earned. Never send "Checking in!" without value. - -**Re-engagement:** "We noticed you stopped." Be honest about it. No "We miss you!" State what changed since they left. Give a reason to come back or let them go cleanly. "If [product] isn't what you need anymore, no hard feelings. Here's how to export your data." - -**Follow-up after meeting:** 3 sentences max. What was discussed + what happens next + by when. "We agreed to send the proposal by Friday. I'll have it to you Thursday afternoon." - -**Internal announcement:** Skip "We're excited to announce." Fact + why it matters + impact on the team. "The London office opens March 1. This means: earlier support hours for EU clients, and 4 open roles we're hiring for now." - -**Thank-you / confirmation:** 2 sentences. Thanks + what to expect next. "Payment received. Your order ships tomorrow. Tracking number in the next email." - -## What to cut - +## Key Priorities +1. Subject line = the hook — under 40 chars. Not "Your weekly update" but "The feature you asked for ships tomorrow" +2. One idea per email — if there are 3 topics, send 3 emails +3. First sentence = why you're writing — not "I hope this email finds you well" +4. Personal where possible — "You signed up for X" not "Our valued subscribers" +5. CTA is one action — not 3 links, 2 buttons, and a PS. One thing + +## What to Cut - "I hope this email finds you well" - "Dear valued customer" - "Click here to learn more" (x3) @@ -44,13 +18,37 @@ - "As per our conversation" (just say what you agreed) - "Just circling back" (say what you need) -## Rhythm +## What to Preserve +- Subject line format and character limits +- Personalization tokens and merge fields +- Legal disclaimers and unsubscribe links (repositioned, not removed) +- CTA clarity and single-action focus -- Same as `human` tone: high variance, fragments, natural connectors -- Read aloud test: would you say this to the recipient in person? -- Email preview text (first line visible in inbox): make it count. Not "Having trouble viewing this email?" +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Same as human tone — high variance | +| Conjunction spacing | Natural connectors | +| Max consecutive same category | 2 | -## Pipeline Recommendations +Additional targets: read aloud test — would you say this to the recipient in person? Email preview text (first line visible in inbox): make it count, not "Having trouble viewing this email?" + +## By email type +- Welcome: Deliver the thing you promised. No 5-paragraph intro. "Here's the guide. Next email: how to set it up" +- Newsletter: Lead with the most interesting thing. Not "Welcome to issue #47." Short intro, content, one takeaway +- Cold outreach: 5 lines max. No trust = no social proof. "Hi [name]. I saw [specific observation about their work]. We built [tool] that [one clear outcome]. Worth 15 minutes?" +- Nurture: 3-5 emails. Each adds value independent of purchase. No "As we discussed in the previous email..." +- Cart abandonment: 1-2 emails. Remind what they left, not why they should buy. "You left [product] in your cart. Questions? Reply to this email" +- Onboarding (3-5 emails): Each email = one user action + one result. Day 1: get them to do the core action. Day 3: show them the result of that action. Day 7: advanced feature they've now earned. Never send "Checking in!" without value +- Re-engagement: "We noticed you stopped." Be honest about it. No "We miss you!" State what changed since they left. Give a reason to come back or let them go cleanly. "If [product] isn't what you need anymore, no hard feelings. Here's how to export your data" +- Follow-up after meeting: 3 sentences max. What was discussed + what happens next + by when. "We agreed to send the proposal by Friday. I'll have it to you Thursday afternoon" +- Internal announcement: Skip "We're excited to announce." Fact + why it matters + impact on the team. "The London office opens March 1. This means: earlier support hours for EU clients, and 4 open roles we're hiring for now" +- Thank-you / confirmation: 2 sentences. Thanks + what to expect next. "Payment received. Your order ships tomorrow. Tracking number in the next email" + +## Language Notes +- All languages: Follow the human tone language-specific notes. Adapt subject line conventions per language + +## Pipeline - Likely needed: cleanup (greeting cliches), tone (human voice) - Often skippable: specificity (emails are short and direct), rhythm (natural brevity) - Never skip: proofread diff --git a/scenarios/full-rewrite.md b/scenarios/full-rewrite.md index f2d95ff..9911215 100644 --- a/scenarios/full-rewrite.md +++ b/scenarios/full-rewrite.md @@ -1,15 +1,56 @@ # Scenario: Full Rewrite (Default) **Use when:** Any text needs the complete 5-stage humanization pipeline. +**Default tone:** `human` -**Pipeline:** cleanup → specificity → tone → rhythm → proofread +## Key Priorities +1. Run the complete 5-stage pipeline: cleanup → specificity → tone → rhythm → proofread +2. Auto-detect language from text + tone from context (B2B→biz, tech→expert, blog→human, social→social, landing→landing, long-form→article, portfolio→case) +3. Strip openers, burned words, fake transitions, hedging, adjective pileups, symmetrical paragraphs, rhetorical padding +4. Climb specificity ladder for every claim rung 0-1; flag invented numbers with [VERIFY] +5. Set tone and apply tone-specific markers (contractions, fragments, formality) +6. Break metronome - vary sentence length, openers, add fragments and conjunction starters (`shared/rhythm-tables.md`) +7. Final proofread - read-aloud test, top-10 AI tells scan, max 2 passes -**Auto-detect:** Language (from text) + Tone (from context: B2B→biz, tech→expert, blog→human, social→social, landing→landing, long-form→article, portfolio→case). +## What to Cut +- AI-generated openers +- Burned words and phrases +- Fake transitions +- Hedging language +- Adjective pileups +- Symmetrical paragraphs +- Rhetorical padding -**User can override:** Language, Tone. +## What to Preserve +- User-specified language and tone overrides +- Factual content and data +- Proper names and terminology +- Quoted material and code blocks -## Procedure +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Vary sentence length naturally | +| Conjunction spacing | Use conjunction starters naturally | +| Max consecutive same category | 3 | + +## Language Notes +- Auto-detected from text using `shared/ai-markers.md` +- User can override language via input + +## Pipeline +- Likely needed: cleanup, specificity, tone, rhythm (full pipeline) +- Often skippable: any stage where patterns already correct +- Never skip: proofread + +## Skip conditions +- No AI patterns → skip cleanup +- All claims rung 2+ → skip specificity +- Tone already matches → skip tone +- Rhythm already varied → skip rhythm +- Declare all skips. Proofread always runs (minimal scan). +## Procedure 1. Detect language (`shared/ai-markers.md`) 2. Stage 1: Strip openers, burned words, fake transitions, hedging, adjective pileups, symmetrical paragraphs, rhetorical padding 3. Stage 2: Climb specificity ladder for every claim rung 0-1. Flag invented numbers `[VERIFY]` @@ -18,7 +59,6 @@ 6. Stage 5: Final proofread - read-aloud test, top-10 AI tells scan, max 2 passes ## Output - ``` [LANG: detected] [TONE: detected or specified] @@ -38,11 +78,3 @@ [STAGE SCORES] Cleanup: XX | Specificity: XX | Tone: XX | Rhythm: XX | Proofread: XX ``` - -## Skip conditions -- No AI patterns → skip cleanup -- All claims rung 2+ → skip specificity -- Tone already matches → skip tone -- Rhythm already varied → skip rhythm - -Declare all skips. Proofread always runs (minimal scan). diff --git a/scenarios/grant-proposal.md b/scenarios/grant-proposal.md index 244d630..537bbfb 100644 --- a/scenarios/grant-proposal.md +++ b/scenarios/grant-proposal.md @@ -3,36 +3,40 @@ **Use when:** Humanizing a grant proposal, funding application, or research statement. **Default tone:** `expert` -## Key priorities - -1. **Numbers are sacred.** Budget figures, timelines, sample sizes: preserve exactly. Flag any you're unsure about with [VERIFY]. -2. **Methodology preserved.** The "how we'll do it" section is the core. Don't simplify it. Make it readable, not dumbed down. -3. **Impact stated without adjectives.** "This will help 12,000 patients" not "This will have a transformative impact on healthcare." -4. **No false modesty, no false confidence.** Grant reviewers detect both. State what you'll do and what you need. No more, no less. -5. **Jargon where the reviewer expects it.** If the grant is for molecular biology, use molecular biology terms. Define only genuinely obscure ones. - -## Rhythm targets -- Short sentences every 5-7 sentences -- Fragments: every 5-7 sentences -- Conjunction openers: every 5-7 sentences -- Max consecutive same category: 2 -- Section structure: preserve the funder's required format - -## What to cut +## Key Priorities +1. Numbers are sacred — budget figures, timelines, sample sizes: preserve exactly. Flag any you're unsure about with [VERIFY] +2. Methodology preserved — the "how we'll do it" section is the core. Don't simplify it. Make it readable, not dumbed down +3. Impact stated without adjectives — "This will help 12,000 patients" not "This will have a transformative impact on healthcare" +4. No false modesty, no false confidence — grant reviewers detect both. State what you'll do and what you need. No more, no less +5. Jargon where the reviewer expects it — if the grant is for molecular biology, use molecular biology terms. Define only genuinely obscure ones + +## What to Cut - "This groundbreaking research will revolutionize..." - "We are uniquely positioned to..." (show, don't state) - "Building on decades of research..." (name the specific research) - Overly broad impact claims without mechanism - "This proposal seeks to explore..." (just say what you'll do) -## What to preserve +## What to Preserve - Budget tables and figures - Timeline / Gantt chart descriptions - Team credentials and affiliations - Citations and references - Institutional boilerplate -## Pipeline Recommendations +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Every 5-7 sentences | +| Conjunction spacing | Every 5-7 sentences | +| Max consecutive same category | 2 | + +Additional targets: short sentences every 5-7 sentences. Section structure: preserve the funder's required format. + +## Language Notes +- All languages: Formal academic tone appropriate to the field. Preserve funder-specific terminology and format requirements + +## Pipeline - Likely needed: cleanup (hype removal), specificity (rung 2+ for all claims) - Often skippable: rhythm (grant structure is intentionally formal) - Never skip: proofread diff --git a/scenarios/internal-memo.md b/scenarios/internal-memo.md index c5ba833..803f590 100644 --- a/scenarios/internal-memo.md +++ b/scenarios/internal-memo.md @@ -3,35 +3,47 @@ **Use when:** Humanizing an internal company memo, all-hands update, team announcement. **Default tone:** `human` -## Key priorities - -1. **Lead with the decision, not the reasoning.** "We're changing our remote work policy. Here's why." Not: "After careful consideration of various factors..." -2. **One voice, not a committee.** Internal memos written by committee sound like AI. Pick a person and write as them. -3. **Action items at the top if there are any.** Don't bury "what you need to do" in paragraph 7. -4. **Honesty about bad news.** If it's a layoff announcement or budget cut: be direct. Corporate euphemisms read as AI. -5. **No "We're excited to share."** Internal readers see through this instantly. - -## Rhythm targets -- Short sentences every 4-6 sentences -- Fragments: every 5-7 sentences -- Conjunction openers: every 4-6 sentences -- Max consecutive same category: 2 -- Paragraphs: varied, 2-5 sentences - -## What to cut +## Key Priorities +1. Lead with the decision, not the reasoning — "We're changing our remote work policy. Here's why." Not: "After careful consideration of various factors..." +2. One voice, not a committee — internal memos written by committee sound like AI. Pick a person and write as them +3. Action items at the top if there are any — don't bury "what you need to do" in paragraph 7 +4. Honesty about bad news — if it's a layoff announcement or budget cut: be direct. Corporate euphemisms read as AI +5. No "We're excited to share" — internal readers see through this instantly + +## What to Cut - "As we continue to navigate these unprecedented times" - "In alignment with our core values" - "We remain committed to transparency" (just be transparent) - "Please don't hesitate to reach out" (of course they can) - Three-paragraph buildup before the actual news +## What to Preserve +- Action items and deadlines +- Policy details and effective dates +- Contact information for questions +- The honest core of the message + +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Every 5-7 sentences | +| Conjunction spacing | Every 4-6 sentences | +| Max consecutive same category | 2 | + +Additional targets: short sentences every 4-6 sentences. Paragraphs: varied, 2-5 sentences. + ## By memo type -**Policy change:** What's changing + when + why (1 honest sentence) + who to ask. -**All-hands update:** 3-5 bullets of actual news. Skip the "great quarter" filler if the quarter wasn't great. -**Bad news:** Lead with it. Then context. Then support resources. No silver lining paragraph. -**CEO letter:** Personal voice required. If it reads like PR approved it, rewrite it. +- Policy change: What's changing + when + why (1 honest sentence) + who to ask +- All-hands update: 3-5 bullets of actual news. Skip the "great quarter" filler if the quarter wasn't great +- Bad news: Lead with it. Then context. Then support resources. No silver lining paragraph +- CEO letter: Personal voice required. If it reads like PR approved it, rewrite it + +## Language Notes +- All languages: Direct, one-voice, no corporate-speak. Adapt formality per language culture +- RU: Russian corporate culture tolerates more formality, but still cut the Soviet bureaucratic residue +- UK: Ukrainian corporate = European directness. No Russianisms in structure -## Pipeline Recommendations +## Pipeline - Likely needed: cleanup (corporate-speak removal), tone (human voice) - Often skippable: specificity (memos are about decisions, not data density) - Never skip: proofread diff --git a/scenarios/landing-page.md b/scenarios/landing-page.md index c8ef714..cecefc3 100644 --- a/scenarios/landing-page.md +++ b/scenarios/landing-page.md @@ -1,39 +1,43 @@ # Scenario: Landing Page **Use when:** Humanizing a product page, SaaS landing, sales page, or promo page. - **Default tone:** `landing` -## Key priorities (ordered) - -1. **Cut, cut, cut.** Every word earns its pixel space. Remove 40-60% of original text - landing pages are 80% shorter than blog posts for the same information. -2. **Headline <12 words.** Subhead <20. CTA = action verb + benefit. "Start building" not "Get started today." -3. **Features → benefits.** Not "has X feature" but "lets you do Y without Z headache." -4. **Above the fold:** what it is + who it's for + what happens next. 3 sentences max. -5. **Trust through specifics.** Not "trusted by thousands" - "used by 340 teams at companies with 50+ employees." Not logos wall - one specific case hook. - -## Rhythm targets - -- Short sentences every 3-4 sentences -- Fragments: every 3-4 sentences -- Conjunction openers: every 5-7 sentences -- Max consecutive same category: 1 - -## What to cut aggressively +## Key Priorities +1. Cut, cut, cut — every word earns its pixel space. Remove 40-60% of original text - landing pages are 80% shorter than blog posts for the same information +2. Headline <12 words, subhead <20, CTA = action verb + benefit ("Start building" not "Get started today") +3. Features → benefits — not "has X feature" but "lets you do Y without Z headache" +4. Above the fold: what it is + who it's for + what happens next. 3 sentences max +5. Trust through specifics — not "trusted by thousands" but "used by 340 teams at companies with 50+ employees." Not logos wall - one specific case hook +## What to Cut - "Welcome to..." (never start with this) - "We are excited to announce..." - "Our mission is to..." - "Comprehensive / best-in-class / cutting-edge..." - "Learn more" / "Get started today" → "Start building" / "See how it works" -## Language-specific notes +## What to Preserve +- Product name, pricing, and factual feature descriptions +- CTAs that are already action-oriented +- Trust signals with specific data +- Visual hierarchy and section ordering + +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Every 3-4 sentences | +| Conjunction spacing | Every 5-7 sentences | +| Max consecutive same category | 1 | + +Additional targets: short sentences every 3-4 sentences. -**RU:** Russian landing pages suffer from over-explanation. Cut 30% then cut 30% more. CTAs: infinitive or imperative - pick one, stay consistent. Trust through specifics, not enthusiasm. -**UK:** Ukrainian audience responds to clarity over embellishment. Cut aggressively. -**All languages:** Test every sentence: "Does the reader need this to decide?" If no → cut. +## Language Notes +- RU: Russian landing pages suffer from over-explanation. Cut 30% then cut 30% more. CTAs: infinitive or imperative - pick one, stay consistent. Trust through specifics, not enthusiasm +- UK: Ukrainian audience responds to clarity over embellishment. Cut aggressively +- All languages: Test every sentence — "Does the reader need this to decide?" If no → cut -## Pipeline Recommendations +## Pipeline - Likely needed: cleanup (aggressive cut of marketing fluff), tone (landing voice) - Often skippable: specificity (if product features are already specific) - Never skip: proofread diff --git a/scenarios/press-release.md b/scenarios/press-release.md index d0fba5a..89eab01 100644 --- a/scenarios/press-release.md +++ b/scenarios/press-release.md @@ -3,35 +3,42 @@ **Use when:** Humanizing a press release, media announcement, or company news. **Default tone:** `biz` -## Key priorities +## Key Priorities +1. Lead paragraph = everything — who, what, when, where, why. 40 words max. If the editor cuts everything after paragraph 1, the story still makes sense +2. Quotes must be preserved verbatim — if a real person is quoted: do NOT change their words. Only fix grammar if it's clearly a transcription error. If no real quote exists: delete the fake quote block entirely +3. No corporate enthusiasm — "We are thrilled to announce" is an AI tell and a press release cliche. "We are announcing" is enough +4. Boilerplate at the end is fine — the "About Company X" paragraph is expected and doesn't need humanization. Light cleanup only +5. Dateline format: preserve — "CITY, State/Country, Month Day, Year" is standard. Don't touch it -1. **Lead paragraph = everything.** Who, what, when, where, why. 40 words max. If the editor cuts everything after paragraph 1, the story still makes sense. -2. **Quotes must be preserved verbatim.** If a real person is quoted: do NOT change their words. Only fix grammar if it's clearly a transcription error. If no real quote exists: delete the fake quote block entirely. -3. **No corporate enthusiasm.** "We are thrilled to announce" is an AI tell and a press release cliche. "We are announcing" is enough. -4. **Boilerplate at the end is fine.** The "About Company X" paragraph is expected and doesn't need humanization. Light cleanup only. -5. **Dateline format: preserve.** "CITY, State/Country, Month Day, Year" is standard. Don't touch it. - -## Rhythm targets -- Short sentences every 6-8 sentences -- Fragments: rare (1-2 per entire document) -- Conjunction openers: rare -- Max consecutive same category: 2 - -## What to cut +## What to Cut - "We are excited/thrilled/proud to announce" - "This groundbreaking/revolutionary/innovative development" - "Marking a significant milestone in..." - "We believe this will transform the industry" - Quotes that say nothing: "We are committed to excellence" -## What to preserve +## What to Preserve - Dateline - Real quotes (verbatim) - Financial figures, dates, locations - Boilerplate (light touch only) - Media contact information -## Pipeline Recommendations +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | 1-2 per entire document (rare) | +| Conjunction spacing | Rare | +| Max consecutive same category | 2 | + +Additional targets: short sentences every 6-8 sentences. + +## Language Notes +- All languages: follow inverted pyramid structure. Facts first, context second, quotes third, boilerplate last +- RU: Formal business Russian. Avoid enthusiasm. Facts over emotion +- UK: Clean business Ukrainian. Direct and factual + +## Pipeline - Likely needed: cleanup (enthusiasm + cliche removal) - Often skippable: specificity (press releases already have facts), rhythm (inverted pyramid structure is intentional) - Never skip: proofread diff --git a/scenarios/product-update.md b/scenarios/product-update.md index 86582fd..5666d9f 100644 --- a/scenarios/product-update.md +++ b/scenarios/product-update.md @@ -3,28 +3,45 @@ **Use when:** Humanizing a product update post, changelog entry, release notes, or feature announcement. **Default tone:** `human` -## Key priorities - -1. **Lead with what changed for the user.** "You can now export reports as PDF." Not: "We are pleased to announce the release of our new PDF export functionality." -2. **One feature = one paragraph.** Don't bundle. If you shipped 5 things, 5 short sections. -3. **Why it matters, not how it works.** "PDF export means you can send reports to clients who don't use our platform." That's the story. -4. **Bugs fixed: be specific.** "Fixed: login button unclickable on iOS Safari 17.4" not "Various performance improvements." -5. **No roadmap teasers.** "Coming soon" without a date is AI filler. If there's no date, skip it. - -## Rhythm targets -- Short sentences every 3-5 sentences -- Fragments: every 4-6 sentences -- Conjunction openers: every 4-6 sentences -- Max consecutive same category: 2 -- Bullet points encouraged for feature lists - -## What to cut +## Key Priorities +1. Lead with what changed for the user — "You can now export reports as PDF." Not: "We are pleased to announce the release of our new PDF export functionality" +2. One feature = one paragraph — don't bundle. If you shipped 5 things, 5 short sections +3. Why it matters, not how it works — "PDF export means you can send reports to clients who don't use our platform." That's the story +4. Bugs fixed: be specific — "Fixed: login button unclickable on iOS Safari 17.4" not "Various performance improvements" +5. No roadmap teasers — "Coming soon" without a date is AI filler. If there's no date, skip it + +## What to Cut - "We're excited to announce" - "Based on your feedback" (unless you can name the specific feedback) - "And much more!" (if there's more, list it) - "As always, we're committed to..." (this is boilerplate) - "Stay tuned for more updates" +## What to Preserve +- Version numbers and release dates +- Specific feature descriptions and their user benefits +- Bug fix details (what happened before, what happens now) +- Changelog format structure + +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Every 4-6 sentences | +| Conjunction spacing | Every 4-6 sentences | +| Max consecutive same category | 2 | + +Additional targets: short sentences every 3-5 sentences. Bullet points encouraged for feature lists. + +## Language Notes +- All languages: Direct, user-focused. Lead with what changed, then why it matters +- RU: Russian product updates benefit from directness. No: «рады сообщить» +- UK: Ukrainian product updates: clean, direct, European style + +## Pipeline +- Likely needed: cleanup (hype removal), tone (human voice) +- Often skippable: specificity (already specific by nature), rhythm (lists have natural variance) +- Never skip: proofread + ## Format ``` ## [Version/Date] @@ -41,8 +58,3 @@ [No closing paragraph. End on the last item.] ``` - -## Pipeline Recommendations -- Likely needed: cleanup (hype removal), tone (human voice) -- Often skippable: specificity (already specific by nature), rhythm (lists have natural variance) -- Never skip: proofread diff --git a/scenarios/seo-article.md b/scenarios/seo-article.md index 83d9995..b8f9fcc 100644 --- a/scenarios/seo-article.md +++ b/scenarios/seo-article.md @@ -1,13 +1,38 @@ # Scenario: SEO Article **Use when:** Humanizing SEO content while preserving keyword intent. +**Default tone:** `article` -**Pipeline:** Stage 0 (anti-AI cleanup) → Stage 1 (keyword audit) → Stage 2 (structure rebuild) → Stage 3 (specificity) → Stage 4 (human voice) → Stage 5 (SEO polish) +## Key Priorities +1. Run the full pipeline: Stage 0 (anti-AI cleanup) → Stage 1 (keyword audit) → Stage 2 (structure rebuild) → Stage 3 (specificity) → Stage 4 (human voice) → Stage 5 (SEO polish) +2. Keyword preservation overrides humanization — never sacrifice SEO structure for voice +3. Fix the six SEO smells (see below) +4. Apply keyword rules: Title/H1 once naturally, first 100 words once if it fits, at least one H2, 4-6 instances per 2000 words total +5. Include output extras: META RECOMMENDATIONS (title ≤60 chars, description ≤155 chars, slug), INTERNAL LINKS opportunities, SCHEMA opportunities -**Default tone:** `human` or `article` +## What to Cut +- Keyword stuffing (same phrase unnaturally repeated — max 2% density, use synonyms/pronouns/natural language) +- Fake FAQ sections (generic Q&A, 50-word answers, no real questions — delete if FAQ wouldn't exist without the article) +- Template skeleton (What is X / Why important / Top 10 / FAQ / Conclusion — break the template, earn structure from content) +- "Comprehensive guide" sections with no new information +- Uniform "Here are the" lists with 2-3 sentence items — vary item length, include surprising entries +- Conclusions that regurgitate — replace with clear recommendation, specific next action, or open question -## Six SEO Smells (identify and fix) +## What to Preserve +- Primary keywords in title/H1 and first 100 words +- At least one keyword instance in relevant H2 +- Search intent and topic coverage +- META data opportunities (title, description, slug) +- Internal link and schema opportunities + +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Natural variance within article structure | +| Conjunction spacing | Natural variance within article structure | +| Max consecutive same category | 2 | +## Six SEO Smells (identify and fix) | # | Smell | Fix | |---|-------|-----| | 1 | Keyword stuffing (same phrase unnaturally repeated) | 2% density max. Use synonyms, pronouns, natural language | @@ -18,24 +43,22 @@ | 6 | Conclusion that regurgitates | Replace with: clear recommendation, specific next action, or open question. | ## Keyword rules - - Title/H1: keyword once, naturally - First 100 words: keyword once, if it fits - At least one H2: if section is literally about that topic - Total: 4-6 instances per 2000 words (was: 15-24) -## Language-specific SEO notes - -**RU:** Yandex (~35% share) penalizes over-optimization harder than Google. Human-sounding text is even MORE important. Queries often phrased as questions. -**EN:** Featured snippets reward clear, concise answers. E-E-A-T is real - signal experience through specifics. -**UK:** Google dominates (~95%). Ukrainian queries longer and more conversational. Avoid RU SEO patterns leaking. -**DE/FR/ES/PT/IT/PL:** Google dominates. Same quality-first principles. Local keyword research patterns apply. +## Language Notes +- RU: Yandex (~35% share) penalizes over-optimization harder than Google. Human-sounding text is even MORE important. Queries often phrased as questions +- EN: Featured snippets reward clear, concise answers. E-E-A-T is real - signal experience through specifics +- UK: Google dominates (~95%). Ukrainian queries longer and more conversational. Avoid RU SEO patterns leaking +- DE/FR/ES/PT/IT/PL: Google dominates. Same quality-first principles. Local keyword research patterns apply -## Output extras -Include META RECOMMENDATIONS (title ≤60 chars, description ≤155 chars, slug), INTERNAL LINKS opportunities, SCHEMA opportunities. - -## Pipeline Recommendations +## Pipeline - Likely needed: cleanup (SEO template removal), specificity (article depth), tone (article voice) - Often skippable: none when SEO structure is involved - Never skip: proofread -- Note: keyword preservation overrides humanization. Never sacrifice SEO structure for voice. +- Note: keyword preservation overrides humanization. Never sacrifice SEO structure for voice + +## Output extras +Include META RECOMMENDATIONS (title ≤60 chars, description ≤155 chars, slug), INTERNAL LINKS opportunities, SCHEMA opportunities. diff --git a/scenarios/social-post.md b/scenarios/social-post.md index bd471f9..09fc77e 100644 --- a/scenarios/social-post.md +++ b/scenarios/social-post.md @@ -1,38 +1,48 @@ # Scenario: Social Post **Use when:** Humanizing a LinkedIn post, Twitter/X thread, Telegram post, Instagram caption. - **Default tone:** `social` -## Key priorities - -1. **Opening line = HOOK.** Not a headline. Not context. A statement that forces reading line 2. -2. **1-3 sentences per paragraph.** White space is part of rhythm. Short paragraphs force scrolling. -3. **Opinion stated as fact.** No hedging. No "in my opinion." No "some people say." -4. **End with a punch**, not a summary. Call to action, counterintuitive takeaway, or open question. -5. **No emoji overload.** Max 1-2. No "thread 🧵". No "link in bio". - -## Rhythm targets - -- Short sentences every 2-3 sentences -- Fragments: every 2-3 sentences (very aggressive) -- Conjunction openers: every 2-4 sentences -- Max consecutive same category: 1 -- Paragraphs: 1-3 sentences +## Key Priorities +1. Opening line = HOOK — not a headline, not context. A statement that forces reading line 2 +2. 1-3 sentences per paragraph — white space is part of rhythm. Short paragraphs force scrolling +3. Opinion stated as fact — no hedging, no "in my opinion," no "some people say" +4. End with a punch, not a summary — call to action, counterintuitive takeaway, or open question +5. No emoji overload — max 1-2. No "thread 🧵". No "link in bio" + +## What to Cut +- Hedging language ("in my opinion", "some people say") +- "Thread 🧵" and "link in bio" clichés +- Excessive emoji +- Summary endings +- Context-heavy openers + +## What to Preserve +- The hook line if it's already strong +- Platform-specific formatting (line breaks, paragraph structure) +- Data points and specific claims +- The author's authentic voice + +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Every 2-3 sentences (very aggressive) | +| Conjunction spacing | Every 2-4 sentences | +| Max consecutive same category | 1 | + +Additional targets: short sentences every 2-3 sentences. Paragraphs: 1-3 sentences. ## Platform-specific notes +- LinkedIn: Professional but conversational. Data hooks work. "X cost us $Y. Here's what we learned" +- Twitter/X: Even punchier. Thread = each tweet a standalone idea that chains +- Telegram: Russian-speaking audience: more directness than EN. Confidence without arrogance +- Instagram: Visual-first - text supports the image. Shorter. Emotional resonance over data -**LinkedIn:** Professional but conversational. Data hooks work. "X cost us $Y. Here's what we learned." -**Twitter/X:** Even punchier. Thread = each tweet a standalone idea that chains. -**Telegram:** Russian-speaking audience: more directness than EN. Confidence without arrogance. -**Instagram:** Visual-first - text supports the image. Shorter. Emotional resonance over data. - -## Language notes - -**RU:** Measured confidence - bold but not brash. Self-irony works. Russian social is more direct than English. -**UK:** Ukrainian social = more emotional, community-oriented. Warmth works. Directness fine but less aggressive than RU. +## Language Notes +- RU: Measured confidence - bold but not brash. Self-irony works. Russian social is more direct than English +- UK: Ukrainian social = more emotional, community-oriented. Warmth works. Directness fine but less aggressive than RU -## Pipeline Recommendations +## Pipeline - Likely needed: cleanup (hedging removal), tone (social voice), rhythm (aggressive fragment/conjunction injection) - Often skippable: specificity (social posts are short, one strong detail is enough) - Never skip: proofread diff --git a/scenarios/technical-doc.md b/scenarios/technical-doc.md index f0d7fb5..8b10fd1 100644 --- a/scenarios/technical-doc.md +++ b/scenarios/technical-doc.md @@ -3,33 +3,14 @@ **Use when:** Humanizing technical docs, API references, READMEs, setup guides, or knowledge base articles. **Default tone:** `expert` -## Key priorities - -1. **Clarity over brevity.** Technical text can be longer if every word adds precision. But cut filler. -2. **Jargon where appropriate.** Use correct terms - don't dumb down. Define implicitly through use, not with a glossary. -3. **Active voice.** "The function returns an array" not "An array is returned by the function." -4. **Code blocks stay.** Never modify code, commands, or config examples. Only edit surrounding explanation. -5. **Assumed audience is smart.** Don't explain what a variable is. Do explain why this architecture choice matters. - -## API Reference Specifics - -**Parameter tables:** Never modify the table content. You may clean up marketing language in the surrounding description. - -**Code examples:** Preserve verbatim. Even comments in code stay unless they're clearly AI-generated filler comments. - -**Error messages:** Preserve exact wording. Developers search for error messages. Changing them breaks searchability. - -**Endpoint descriptions:** The "what this does" sentence can be cleaned. The request/response schemas cannot. - -**"Before you begin" / Prerequisites sections:** These are often AI-padded. Cut to actual requirements: Node 18+, API key, that's it. - -## Rhythm targets -- Short sentences every 5-7 sentences -- Fragments: every 7-10 sentences -- Conjunction openers: every 5-7 sentences -- 3-clause cap exception: 1 technical sentence per ~300 words may have 4 clauses - -## What to cut +## Key Priorities +1. Clarity over brevity — technical text can be longer if every word adds precision. But cut filler +2. Jargon where appropriate — use correct terms, don't dumb down. Define implicitly through use, not with a glossary +3. Active voice — "The function returns an array" not "An array is returned by the function" +4. Code blocks stay — never modify code, commands, or config examples. Only edit surrounding explanation +5. Assumed audience is smart — don't explain what a variable is. Do explain why this architecture choice matters + +## What to Cut - "In this document we will..." - "It is important to note..." - "As you can see..." @@ -37,20 +18,36 @@ - Over-explaining basic concepts - "Simply", "just", "easily" (never true in docs) -## What to preserve +## What to Preserve - Code blocks, commands, configs (verbatim) - Parameter tables, type definitions - Error messages, status codes - Version numbers, dates - Security warnings and compliance notes -## Language-specific notes -**RU:** Brevity respected. Мы default. Technical English loanwords fine. -**UK:** Clean technical Ukrainian. No Russianisms. -**DE:** Direkt, prazise. Aktiv statt Passiv. -**All:** Technical accuracy > humanization. If humanization would make something ambiguous, keep the original. +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Every 7-10 sentences | +| Conjunction spacing | Every 5-7 sentences | +| Max consecutive same category | 2 | + +Additional targets: short sentences every 5-7 sentences. 3-clause cap exception: 1 technical sentence per ~300 words may have 4 clauses. -## Pipeline Recommendations +## API Reference Specifics +- Parameter tables: Never modify the table content. You may clean up marketing language in the surrounding description +- Code examples: Preserve verbatim. Even comments in code stay unless they're clearly AI-generated filler comments +- Error messages: Preserve exact wording. Developers search for error messages. Changing them breaks searchability +- Endpoint descriptions: The "what this does" sentence can be cleaned. The request/response schemas cannot +- "Before you begin" / Prerequisites sections: These are often AI-padded. Cut to actual requirements: Node 18+, API key, that's it + +## Language Notes +- RU: Brevity respected. Мы default. Technical English loanwords fine +- UK: Clean technical Ukrainian. No Russianisms +- DE: Direkt, prazise. Aktiv statt Passiv +- All: Technical accuracy > humanization. If humanization would make something ambiguous, keep the original + +## Pipeline - Likely needed: cleanup (remove marketing spillover) - Often skippable: rhythm (technical docs have natural structural variance), tone (if already expert), specificity (if data-rich) - Never skip: proofread diff --git a/scenarios/translation-fix.md b/scenarios/translation-fix.md index d11f7b4..b0e0ec8 100644 --- a/scenarios/translation-fix.md +++ b/scenarios/translation-fix.md @@ -1,27 +1,63 @@ # Scenario: Translation Fix (De-Translation) **Use when:** Making translated text sound like it was originally written in the target language. Removing source-language ghost patterns. +**Default tone:** `human` ## Core principle - A good translation doesn't sound translated. It sounds like the author wrote it in your language. -## Procedure +## Key Priorities +1. Identify the ghost language — detect source-language patterns haunting the text +2. Extract meaning, discard phrasing — ask what is this actually saying, then express it as a native speaker would +3. Fix paragraph structure — restructure to target-language norms (EN: topic→development→conclusion, RU: longer/digressive, UK: European brevity, DE: longer tolerated, FR: structured but not formulaic) +4. Clean punctuation — kill semicolons (EN→RU/UA), replace em-dashes (all→all flag), add contractions (RU/UA→EN) +5. Read aloud in target language — would a native speaker ever say these words in this order? If no, go back + +## What to Cut +- Source-language ghost patterns (Slavic passives, noun chains, clause stacking) +- Em-dashes (replace always — an AI tell) +- Semicolons in RU/UA target texts +- Forced subjects and article artifacts (EN→other) +- Double-translation artifacts (EN→RU→UA) + +## What to Preserve +- The original meaning and intent +- Technical terminology that is the same across languages +- Proper names, numbers, and dates +- Formatting that is standard in the target language + +## Rhythm Targets +| Parameter | Value | +|----------|-------| +| Fragment spacing | Per target language norms | +| Conjunction spacing | Per target language norms | +| Max consecutive same category | Per target language norms | + +## Language Notes +- RU→EN: Slavic passive → active · noun chains → verbs · «данный/являться» → describe directly · clause stacking → split into sentences · missing contractions → add · em-dashes → periods/commas +- EN→RU: Forced subjects → drop · «который» chains → split/restructure · semicolons → periods · progressive trap (is building → делает) · articles → restructure +- EN→UK: Word-for-word idioms → natural Ukrainian · Russian intermediaries → direct EN→UA · «даний/являється» → restructure · English sentence rhythm → Ukrainian melodic flow +- Any → DE/FR/ES/PT/IT/PL: Source-language structures → target-language natural equivalents · Punctuation per target convention · Formality per target culture +- Uncovered pairs: Apply general principles - identify non-native constructions, replace with native phrasing + +## Pipeline +- Likely needed: all steps (ghost language detection, rephrasing, punctuation fix) +- Often skippable: none for translation fix +- Never skip: step 5 read-aloud test +## Procedure ### Step 1: Identify the ghost language Read the text. What language patterns are haunting it? Common source→target tells: - -- **RU→EN:** Slavic passives, noun chains, «данный/является» structures, over-formality, clause stacking, missing contractions, em-dashes -- **EN→RU:** Forced subjects, «который» chains, semicolons, article artifacts, progressive trap -- **EN→DE:** English word order, missing modal particles, over-formal «Sie» inappropriately -- **EN→FR:** English sentence structures, missing «on»/«en fait», forced formality -- **EN→ES:** English gerund patterns, missing subjunctive, forced subjects -- **Any→UK:** Russian loan structures, over-formality, double-translation artifacts (EN→RU→UA) -- **Uncovered pairs:** Apply general principles - identify non-native constructions, replace with native phrasing +- RU→EN: Slavic passives, noun chains, «данный/является» structures, over-formality, clause stacking, missing contractions, em-dashes +- EN→RU: Forced subjects, «который» chains, semicolons, article artifacts, progressive trap +- EN→DE: English word order, missing modal particles, over-formal «Sie» inappropriately +- EN→FR: English sentence structures, missing «on»/«en fait», forced formality +- EN→ES: English gerund patterns, missing subjunctive, forced subjects +- Any→UK: Russian loan structures, over-formality, double-translation artifacts (EN→RU→UA) +- Uncovered pairs: Apply general principles - identify non-native constructions, replace with native phrasing ### Step 2: Extract meaning, discard phrasing Ask: what is this actually saying? Then: how would a native speaker express this? - Write the native expression. Not the translation of the words. ### Step 3: Fix paragraph structure @@ -30,14 +66,13 @@ Paragraph norms differ by language. EN: topic→development→conclusion. RU: lo ### Step 4: Clean punctuation - EN→RU/UA: kill semicolons, kill em-dashes - RU/UA→EN: add contractions, replace em-dashes with periods/commas, add variety -- **All→all: em-dashes are an AI tell. Replace always.** +- All→all: em-dashes are an AI tell. Replace always. - Punctuation must match target-language conventions ### Step 5: Read aloud in target language Would a native speaker ever say these words in this order? If no - it's still a translation. Go back. ## Output format - ``` [SOURCE LANG: detected] [TARGET LANG: specified] @@ -51,22 +86,3 @@ Would a native speaker ever say these words in this order? If no - it's still a - Formality: [adjusted up/down] - Punctuation: [em-dashes removed (12x), contractions added (8x)] ``` - -## Common language-pair fixes - -### RU → EN -Slavic passive → active · noun chains → verbs · «данный/являться» → describe directly · clause stacking → split into sentences · missing contractions → add · em-dashes → periods/commas - -### EN → RU -Forced subjects → drop · «который» chains → split/restructure · semicolons → periods · progressive trap (is building → делает) · articles → restructure - -### EN → UK -Word-for-word idioms → natural Ukrainian · Russian intermediaries → direct EN→UA · «даний/являється» → restructure · English sentence rhythm → Ukrainian melodic flow - -### Any → DE/FR/ES/PT/IT/PL -Source-language structures → target-language natural equivalents · Punctuation per target convention · Formality per target culture - -## Pipeline Recommendations -- Likely needed: all steps (ghost language detection, rephrasing, punctuation fix) -- Often skippable: none for translation fix -- Never skip: step 5 read-aloud test diff --git a/scripts/clause-check.ps1 b/scripts/clause-check.ps1 new file mode 100644 index 0000000..cfa5ca9 --- /dev/null +++ b/scripts/clause-check.ps1 @@ -0,0 +1,144 @@ +#!/usr/bin/env pwsh +# HUMAN-AI Clause Count Validator +# Checks rhythm rules (no 3+ consecutive same-category sentences, no 4+ clause sentences) +# Usage: powershell -File scripts/clause-check.ps1 -File "output.md" + +param( + [Parameter(Mandatory=$true)] + [string]$File, + + [switch]$Verbose +) + +$ErrorActionPreference = "Stop" + +if (-not (Test-Path $File -PathType Leaf)) { + Write-Host "[ERROR] File not found: $File" -ForegroundColor Red + exit 1 +} + +$text = Get-Content $File -Raw + +$pythonScript = @" +import sys, json, re + +text = r'''$($text -replace "'", "''")''' + +# Simple sentence splitting +sentences = re.split(r'(?<=[.!?])\s+', text) +sentences = [s.strip() for s in sentences if s.strip()] + +# Very rough clause counting — count finite verbs and coordinating conjunctions as proxy +def estimate_clauses(sentence): + words = sentence.split() + # Count subject+predicate pairs via verb patterns + # Simple heuristic: count finite verbs in EN, plus conjunctions that join clauses + verb_patterns = re.findall(r'\b(is|are|was|were|be|been|am|has|have|had|do|does|did|' + r'can|could|will|would|shall|should|may|might|must|' + r'\w+s\b|\w+ed\b|\w+ing\b)', sentence, re.IGNORECASE) + # Rough: ~1 clause per finite verb + count = len(verb_patterns) + # Subtract auxiliaries that don't add clauses + if count == 0: + return 0 # fragment + return max(1, count) + +categories = [] +clause_counts = [] +for s in sentences: + c = estimate_clauses(s) + clause_counts.append(c) + if c == 0: + categories.append("Fragment") + elif c == 1: + categories.append("Short") + elif c == 2: + categories.append("Medium") + elif c == 3: + categories.append("Long") + else: + categories.append("Very Long") + +# Check Rule 1: no 3 consecutive same length category +rule1_violations = [] +for i in range(len(categories) - 2): + if categories[i] == categories[i+1] == categories[i+2]: + rule1_violations.append({"start": i+1, "category": categories[i], "sentences": sentences[i:i+3]}) + +# Check Rule 2: no 3 consecutive same clause count +rule2_violations = [] +for i in range(len(clause_counts) - 2): + if clause_counts[i] == clause_counts[i+1] == clause_counts[i+2] and clause_counts[i] > 0: + rule2_violations.append({"start": i+1, "count": clause_counts[i], "sentences": sentences[i:i+3]}) + +# Check Rule 3: no sentence exceeds 3 clauses (exception: 1 per ~300 words) +total_words = len(text.split()) +allowed_long = max(1, total_words // 300) +rule3_violations = [] +long_count = 0 +for i, c in enumerate(clause_counts): + if c >= 4: + long_count += 1 + if long_count > allowed_long: + rule3_violations.append({"sentence_num": i+1, "clauses": c, "text": sentences[i]}) + +print(json.dumps({ + "total_sentences": len(sentences), + "categories": categories, + "clause_counts": clause_counts, + "rule1_violations": len(rule1_violations), + "rule1_detail": [{"at": v["start"], "cat": v["category"]} for v in rule1_violations[:10]], + "rule2_violations": len(rule2_violations), + "rule2_detail": [{"at": v["start"], "count": v["count"]} for v in rule2_violations[:10]], + "rule3_violations": len(rule3_violations), + "rule3_detail": [{"sentence": v["sentence_num"], "clauses": v["clauses"]} for v in rule3_violations[:10]] +}, ensure_ascii=False, indent=2)) +"@ + +$tmpPy = Join-Path ([System.IO.Path]::GetTempPath()) "clause-$([System.Guid]::NewGuid()).py" +Set-Content -Path $tmpPy -Value $pythonScript -Encoding UTF8 + +try { + $result = & python $tmpPy 2>&1 + $json = $result | ConvertFrom-Json + + Write-Host "" + Write-Host "[CLAUSE CHECK REPORT]" -ForegroundColor Cyan + Write-Host "Total sentences: $($json.total_sentences)" + + Write-Host "" + Write-Host "Rule 1 (no 3 consecutive same length category): $($json.rule1_violations) violations" + foreach ($v in $json.rule1_detail) { + Write-Host " Violation at sentence $($v.at): 3× $($v.cat)" -ForegroundColor Yellow + } + + Write-Host "" + Write-Host "Rule 2 (no 3 consecutive same clause count): $($json.rule2_violations) violations" + foreach ($v in $json.rule2_detail) { + Write-Host " Violation at sentence $($v.at): 3× $($v.count) clauses" -ForegroundColor Yellow + } + + Write-Host "" + Write-Host "Rule 3 (max 3 clauses per sentence): $($json.rule3_violations) violations" + foreach ($v in $json.rule3_detail) { + Write-Host " Sentence $($v.sentence): $($v.clauses) clauses" -ForegroundColor Yellow + } + + $totalViolations = $json.rule1_violations + $json.rule2_violations + $json.rule3_violations + Write-Host "" + Write-Host "TOTAL VIOLATIONS: $totalViolations" + + if ($totalViolations -eq 0) { + Write-Host "VERDICT: Rhythm clean" -ForegroundColor Green + exit 0 + } elseif ($totalViolations -le 3) { + Write-Host "VERDICT: Minor rhythm issues" -ForegroundColor Yellow + exit 0 + } else { + Write-Host "VERDICT: Significant rhythm violations" -ForegroundColor Red + exit 1 + } +} +finally { + Remove-Item $tmpPy -Force -ErrorAction SilentlyContinue +} diff --git a/scripts/morph-check.ps1 b/scripts/morph-check.ps1 new file mode 100644 index 0000000..63dc554 --- /dev/null +++ b/scripts/morph-check.ps1 @@ -0,0 +1,179 @@ +#!/usr/bin/env pwsh +# HUMAN-AI Morphological Validator +# Checks text for non-existent words using pymorphy3 + OpenCorpora dictionary. +# Usage: powershell -File scripts/morph-check.ps1 -File "output.md" -Lang "ru" [-Verbose] + +param( + [Parameter(Mandatory=$true)] + [string]$File, + + [Parameter(Mandatory=$true)] + [ValidateSet("ru","uk","en","de","fr","es","pt","it","pl")] + [string]$Lang, + + [switch]$Verbose +) + +$ErrorActionPreference = "Stop" +$RepoRoot = Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Path) + +if (-not (Test-Path $File -PathType Leaf)) { + Write-Host "[ERROR] File not found: $File" -ForegroundColor Red + exit 1 +} + +$text = Get-Content $File -Raw + +# Load whitelist/blacklist if available +$whitelistFile = Join-Path $RepoRoot "shared/morph/whitelist-$Lang.txt" +$blacklistFile = Join-Path $RepoRoot "shared/morph/blacklist-$Lang.txt" + +$whitelist = @() +$blacklist = @() + +if (Test-Path $whitelistFile) { + Get-Content $whitelistFile | ForEach-Object { + $line = $_.Trim() + if ($line -and -not $line.StartsWith("#")) { $whitelist += $line.ToLower() } + } +} + +if (Test-Path $blacklistFile) { + Get-Content $blacklistFile | ForEach-Object { + $line = $_.Trim() + if ($line -and -not $line.StartsWith("#")) { $blacklist += $line.ToLower() } + } +} + +# Python morph checker — writes results to stdout as JSON +$pythonScript = @" +import sys, json, re +sys.path.insert(0, r'$RepoRoot') + +text = r'''$($text -replace "'", "''")''' +lang = '$Lang' +whitelist = set($(if ($whitelist) { "'" + ($whitelist -join "','") + "'" } else { "" })) +blacklist_lower = set($(if ($blacklist) { "'" + ($blacklist -join "','") + "'" } else { "" })) + +# Extract words — Cyrillic for ru/uk, Latin for others +if lang in ('ru', 'uk'): + words = re.findall(r'[а-яёіїєґА-ЯЁІЇЄҐ]+', text.lower()) +else: + words = re.findall(r'[a-zäöüßàâçéèêëîïôûùÿæœñ]+', text.lower()) + +total = len(words) +unknown = [] +blacklist_hits = [] + +if lang in ('ru', 'uk'): + try: + import pymorphy3 + morph = pymorphy3.MorphAnalyzer(lang=lang) + for w in words: + if w in whitelist: + continue + if w in blacklist_lower: + blacklist_hits.append(w) + continue + parsed = morph.parse(w) + if not parsed or parsed[0].score < 0.1: + unknown.append(w) + except ImportError: + print(json.dumps({"error": "pymorphy3 not installed. Run: pip install pymorphy3 pymorphy3-dicts-ru"})) + sys.exit(1) +elif lang == 'en': + # English: check against basic dictionary via pymorphy3 if available + try: + import pymorphy3 + morph = pymorphy3.MorphAnalyzer(lang='en') + for w in words: + if w in whitelist: + continue + parsed = morph.parse(w) + if not parsed or parsed[0].score < 0.1: + unknown.append(w) + except ImportError: + # Fallback: simple non-dictionary check is noisy, skip + print(json.dumps({"error": "pymorphy3 not installed for EN. Skipping.", "total": total, "unknown": 0, "blacklist_hits": len(blacklist_hits)})) + sys.exit(0) +else: + # For DE/FR/ES/PT/IT/PL — spaCy-based (simple OOV check) + try: + import spacy + model_map = {'de': 'de_core_news_sm', 'fr': 'fr_core_news_sm', 'es': 'es_core_news_sm', + 'pt': 'pt_core_news_sm', 'it': 'it_core_news_sm', 'pl': 'pl_core_news_sm'} + nlp = spacy.load(model_map.get(lang, 'en_core_web_sm')) + doc = nlp(text) + for token in doc: + if token.is_alpha and token.text.lower() not in whitelist: + if token.is_oov: + unknown.append(token.text.lower()) + except ImportError: + print(json.dumps({"error": "spaCy not installed for $Lang. Run: pip install spacy && python -m spacy download " + model_map.get(lang, 'model')})) + sys.exit(1) + except Exception as e: + print(json.dumps({"error": f"spaCy error: {e}"})) + sys.exit(1) + +# Deduplicate +unknown = list(dict.fromkeys(unknown)) +blacklist_hits = list(dict.fromkeys(blacklist_hits)) + +pct = round(len(unknown) / total * 100, 1) if total > 0 else 0 + +if pct < 1: verdict = 'OK' +elif pct < 3: verdict = 'WARN' +elif pct < 5: verdict = 'FAIL' +else: verdict = 'CRITICAL' + +print(json.dumps({ + "total": total, + "unknown": len(unknown), + "unknown_words": unknown[:30], + "blacklist_hits": len(blacklist_hits), + "blacklist_words": blacklist_hits[:20], + "pct": pct, + "verdict": verdict +}, ensure_ascii=False)) +"@ + +$tmpPy = Join-Path ([System.IO.Path]::GetTempPath()) "morph-check-$([System.Guid]::NewGuid()).py" +Set-Content -Path $tmpPy -Value $pythonScript -Encoding UTF8 + +try { + $result = & python $tmpPy 2>&1 + $json = $result | ConvertFrom-Json + + if ($json.error) { + Write-Host "[SKIP] $($json.error)" -ForegroundColor Yellow + exit 0 + } + + Write-Host "" + Write-Host "[MORPH REPORT]" -ForegroundColor Cyan + Write-Host "Language: $Lang" + Write-Host "Total words: $($json.total)" + Write-Host "Unknown words: $($json.unknown) ($($json.pct)%)" + + if ($json.blacklist_hits -gt 0) { + Write-Host "Blacklist hits: $($json.blacklist_hits)" -ForegroundColor Red + foreach ($w in $json.blacklist_words) { + Write-Host " [BLACKLIST] «$w»" -ForegroundColor Red + } + } + + if ($json.unknown -gt 0) { + foreach ($w in $json.unknown_words) { + Write-Host " «$w» — не найдено" -ForegroundColor Yellow + } + } + + Write-Host "VERDICT: $($json.verdict)" -ForegroundColor $(if ($json.verdict -eq 'OK') { 'Green' } elseif ($json.verdict -eq 'CRITICAL') { 'Red' } else { 'Yellow' }) + + if ($json.verdict -eq 'OK') { exit 0 } + elseif ($json.verdict -eq 'WARN') { exit 0 } + else { exit 1 } +} +finally { + Remove-Item $tmpPy -Force -ErrorAction SilentlyContinue +} diff --git a/scripts/readability-check.ps1 b/scripts/readability-check.ps1 new file mode 100644 index 0000000..6cce442 --- /dev/null +++ b/scripts/readability-check.ps1 @@ -0,0 +1,149 @@ +#!/usr/bin/env pwsh +# HUMAN-AI Readability Validator (ReadSightPy integration) +# Measures text readability using ReadSightPy and compares input vs output. +# Usage: powershell -File scripts/readability-check.ps1 -Input "original.txt" -Output "humanized.txt" -Lang "ru" + +param( + [Parameter(Mandatory=$true)] + [string]$Input, + + [Parameter(Mandatory=$false)] + [string]$Output, + + [Parameter(Mandatory=$true)] + [ValidateSet("ru","uk","en","de","fr","es","pt","it","pl")] + [string]$Lang, + + [switch]$Verbose +) + +$ErrorActionPreference = "Stop" + +if (-not (Test-Path $Input -PathType Leaf)) { + Write-Host "[ERROR] Input file not found: $Input" -ForegroundColor Red + exit 1 +} + +$inputText = Get-Content $Input -Raw +$outputText = if ($Output -and (Test-Path $Output)) { Get-Content $Output -Raw } else { $null } + +# Language code mapping for ReadSightPy +$langMap = @{ + ru = "ru"; uk = "uk"; en = "en-us"; de = "de-1996" + fr = "fr"; es = "es"; pt = "pt"; it = "it"; pl = "pl" +} +$rsLang = $langMap[$Lang] + +$pythonScript = @" +import sys, json + +input_text = r'''$($inputText -replace "'", "''")''' +output_text = r'''$(if ($outputText) { $outputText -replace "'", "''" } else { "" })''' +lang = '$rsLang' + +try: + from readsight import ReadSight +except ImportError: + print(json.dumps({"error": "ReadSightPy not installed. Run: pip install readsight"})) + sys.exit(1) + +rs = ReadSight(lang) +supported = rs.get_supported_formulas() +formulas_used = [f for f in ['gunning_fog', 'lix', 'smog_index', 'flesch_reading_ease', 'coleman_liau'] + if f in supported] + +def analyze(text, label): + if not text.strip(): + return {"label": label, "error": "empty text"} + stats = rs.analyze(text) + results = {} + for f in formulas_used: + r = rs.score(f, text) + results[f] = {"score": round(r.score, 1), "interpretation": r.interpretation} + return { + "label": label, + "words": stats.word_count, + "sentences": stats.sentence_count, + "avg_syllables": round(stats.average_syllables_per_word, 2), + "avg_words_per_sentence": round(stats.average_words_per_sentence, 1), + "formulas": results + } + +input_analysis = analyze(input_text, "INPUT") +output_analysis = analyze(output_text, "OUTPUT") if output_text.strip() else None + +result = {"input": input_analysis, "output": output_analysis, "formulas_used": formulas_used, "lang": lang} +print(json.dumps(result, ensure_ascii=False)) +"@ + +$tmpPy = Join-Path ([System.IO.Path]::GetTempPath()) "readability-$([System.Guid]::NewGuid()).py" +Set-Content -Path $tmpPy -Value $pythonScript -Encoding UTF8 + +try { + $result = & python $tmpPy 2>&1 + $json = $result | ConvertFrom-Json + + if ($json.error) { + Write-Host "[SKIP] $($json.error)" -ForegroundColor Yellow + exit 0 + } + + Write-Host "" + Write-Host "[READABILITY REPORT]" -ForegroundColor Cyan + Write-Host "Language: $Lang ($($json.lang))" + Write-Host "Formulas: $($json.formulas_used -join ', ')" + + Write-Host "" + Write-Host ("{0,-15} {1,10} {2,10} {3,8} {4,8}" -f "Metric", "Words", "Sent.", "Syll/W", "W/Sent") + Write-Host ("{0,-15} {1,10} {2,10} {3,8} {4,8}" -f "INPUT", $json.input.words, $json.input.sentences, $json.input.avg_syllables, $json.input.avg_words_per_sentence) + + if ($json.output) { + Write-Host ("{0,-15} {1,10} {2,10} {3,8} {4,8}" -f "OUTPUT", $json.output.words, $json.output.sentences, $json.output.avg_syllables, $json.output.avg_words_per_sentence) + Write-Host "" + + $improved = 0 + $same = 0 + $worse = 0 + + foreach ($f in $json.formulas_used) { + $inScore = $json.input.formulas.$f.score + $outScore = $json.output.formulas.$f.score + $inInt = $json.input.formulas.$f.interpretation + $outInt = $json.output.formulas.$f.interpretation + + # For Flesch: higher = better. For Fog/LIX/SMOG: lower = better + $isFlesch = $f -eq "flesch_reading_ease" + if ($isFlesch) { + $delta = $outScore - $inScore + } else { + $delta = $inScore - $outScore + } + + $arrow = if ($delta -gt 0.5) { "↑ better" } elseif ($delta -lt -0.5) { "↓ worse" } else { "→ same" } + $color = if ($delta -gt 0.5) { "Green" } elseif ($delta -lt -0.5) { "Red" } else { "White" } + + Write-Host (" {0,-25} {1,6} → {2,6} [{3}→{4}] {5}" -f $f, $inScore, $outScore, $inInt, $outInt, $arrow) -ForegroundColor $color + + if ($delta -gt 0.5) { $improved++ } elseif ($delta -lt -0.5) { $worse++ } else { $same++ } + } + + Write-Host "" + Write-Host "SUMMARY: $improved improved, $same unchanged, $worse worse" + + if ($worse -eq 0 -and $improved -ge 1) { + Write-Host "VERDICT: Readability improved" -ForegroundColor Green + exit 0 + } elseif ($worse -le 1) { + Write-Host "VERDICT: Readability stable" -ForegroundColor Yellow + exit 0 + } else { + Write-Host "VERDICT: Readability degraded" -ForegroundColor Red + exit 1 + } + } else { + Write-Host "[INFO] No output file provided — baseline metrics only" -ForegroundColor Yellow + } +} +finally { + Remove-Item $tmpPy -Force -ErrorAction SilentlyContinue +} diff --git a/scripts/run-benchmark.sh b/scripts/run-benchmark.sh new file mode 100644 index 0000000..2da1dbb --- /dev/null +++ b/scripts/run-benchmark.sh @@ -0,0 +1,122 @@ +#!/usr/bin/env bash +# HUMAN-AI Benchmark Runner (Bash) with ZeroGPT external validation. +# Usage: bash scripts/run-benchmark.sh [--api-key KEY] [--max-texts N] [--skip-api] [--delay N] + +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" +API_KEY="${ZEROGPT_API_KEY:-}" +OUTPUT_FILE="" +MAX_TEXTS=0 +SKIP_API=false +DELAY=1 + +while [[ $# -gt 0 ]]; do + case "$1" in + --api-key) API_KEY="$2"; shift 2 ;; + --max-texts) MAX_TEXTS="$2"; shift 2 ;; + --skip-api) SKIP_API=true; shift ;; + --delay) DELAY="$2"; shift 2 ;; + --output) OUTPUT_FILE="$2"; shift 2 ;; + *) echo "Unknown option: $1"; exit 1 ;; + esac +done + +if [ -z "$OUTPUT_FILE" ]; then + OUTPUT_FILE="$REPO_ROOT/tests/benchmark/zerogpt-results.json" +fi + +BENCH_DIR="$REPO_ROOT/tests/benchmark" +AI_DIR="$BENCH_DIR/ai-texts" + +echo "" +echo "=== HUMAN-AI BENCHMARK RUNNER ===" +echo "Benchmark dir: $BENCH_DIR" +echo "Output: $OUTPUT_FILE" +echo "" + +# Discover test files +declare -a TESTS=() +while IFS= read -r -d '' file; do + rel="${file#$AI_DIR/}" + lang="$(echo "$rel" | cut -d/ -f1)" + type="$(basename "$rel" .md)" + # Strip YAML/markdown headers: remove first heading and blank line after + text="$(sed '1{/^#/d}; /^\s*$/{/^$/d}' "$file" | head -c 10000)" + if [ ${#text} -ge 50 ]; then + TESTS+=("ai/$lang/$type|$lang|$type|$file") + fi +done < <(find "$AI_DIR" -name "*.md" -print0) + +echo "Discovered ${#TESTS[@]} AI test files" + +if [ "$MAX_TEXTS" -gt 0 ] && [ "$MAX_TEXTS" -lt "${#TESTS[@]}" ]; then + TESTS=("${TESTS[@]:0:$MAX_TEXTS}") + echo "Limited to $MAX_TEXTS texts" +fi + +if [ "$SKIP_API" = true ]; then + echo "" + echo "DRY RUN — would test:" + for entry in "${TESTS[@]}"; do + id="$(echo "$entry" | cut -d'|' -f1)" + echo " $id" + done + echo "" + exit 0 +fi + +if [ -z "$API_KEY" ]; then + echo "ERROR: No API key set. Use --api-key or ZEROGPT_API_KEY env var." + exit 2 +fi + +echo "" +echo "Running ZeroGPT checks..." + +RESULTS='{"version":"1.0","timestamp":"'"$(date -Iseconds)"'","results":{' +FIRST=true + +count=0 +total=${#TESTS[@]} + +for entry in "${TESTS[@]}"; do + count=$((count + 1)) + id="$(echo "$entry" | cut -d'|' -f1)" + lang="$(echo "$entry" | cut -d'|' -f2)" + type="$(echo "$entry" | cut -d'|' -f3)" + file="$(echo "$entry" | cut -d'|' -f4)" + + echo -n " [$count/$total] $id ... " + + # Strip first heading and following blank lines for clean text + text="$(sed '1{/^#/d}; /^\s*$/{/^$/d}' "$file" | head -c 5000)" + + # Call ZeroGPT API + response="$(curl -s -X POST "https://api.zerogpt.com/api/detect" \ + -H "ApiKey: $API_KEY" \ + -H "Content-Type: application/json" \ + -d "$(jq -n --arg text "$text" '{input_text: $text}')" 2>&1 || true)" + + if echo "$response" | jq -e '.data' > /dev/null 2>&1; then + ai_prob="$(echo "$response" | jq -r '.data.aiPercentage // .data.fakePercentage // 0')" + result="$(echo "$response" | jq -r '.data.isHuman // "unknown"')" + echo "$ai_prob% AI ($result)" + if [ "$FIRST" = false ]; then RESULTS+=","; fi + RESULTS+="\"$id\": {\"ai_probability\": $ai_prob, \"result\": \"$result\", \"language\": \"$lang\", \"type\": \"$type\"}" + FIRST=false + else + echo "API error" + fi + + if [ "$count" -lt "$total" ]; then + sleep "$DELAY" + fi +done + +RESULTS+='}}' + +echo "$RESULTS" | jq '.' > "$OUTPUT_FILE" +echo "" +echo "Results saved to: $OUTPUT_FILE" +echo "Done." diff --git a/scripts/run-eval.ps1 b/scripts/run-eval.ps1 new file mode 100644 index 0000000..22ef175 --- /dev/null +++ b/scripts/run-eval.ps1 @@ -0,0 +1,130 @@ +#!/usr/bin/env pwsh +# HUMAN-AI External EVAL Runner +# Sends original + humanized text to LLM API with EVAL.md prompt for independent evaluation. +# Supports OpenAI and Anthropic APIs. +# Usage: powershell -File scripts/run-eval.ps1 -Original "input.txt" -Humanized "output.md" -ApiKey $env:API_KEY + +param( + [Parameter(Mandatory=$true)] + [string]$Original, + + [Parameter(Mandatory=$true)] + [string]$Humanized, + + [ValidateSet("openai","anthropic")] + [string]$Provider = "openai", + + [string]$ApiKey, + + [string]$Model = "", + + [switch]$Verbose +) + +$ErrorActionPreference = "Stop" +$RepoRoot = Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Path) + +if (-not $ApiKey) { + $ApiKey = if ($Provider -eq "openai") { $env:OPENAI_API_KEY } else { $env:ANTHROPIC_API_KEY } +} + +if (-not $ApiKey) { + Write-Host "[ERROR] No API key. Set OPENAI_API_KEY or ANTHROPIC_API_KEY env variable, or pass -ApiKey." -ForegroundColor Red + exit 1 +} + +if (-not (Test-Path $Original)) { Write-Host "[ERROR] Original not found: $Original" -ForegroundColor Red; exit 1 } +if (-not (Test-Path $Humanized)) { Write-Host "[ERROR] Humanized not found: $Humanized" -ForegroundColor Red; exit 1 } + +$originalText = Get-Content $Original -Raw +$humanizedText = Get-Content $Humanized -Raw + +$evalPrompt = Get-Content (Join-Path $RepoRoot "EVAL.md") -Raw + +if (-not $Model) { + $Model = if ($Provider -eq "openai") { "gpt-4o" } else { "claude-3-5-sonnet-20241022" } +} + +$pythonScript = @" +import sys, json + +original_text = r'''$($originalText -replace "'", "''")''' +humanized_text = r'''$($humanizedText -replace "'", "''")''' +eval_prompt = r'''$($evalPrompt -replace "'", "''")''' +provider = '$Provider' +model = '$Model' +api_key = '$ApiKey' + +system_msg = f"""$evalPrompt + +You are a quality evaluator. Evaluate the following HUMAN-AI output against the original. + +ORIGINAL: +$original_text + +HUMAN-AI OUTPUT: +$humanized_text""" + +messages = [ + {"role": "system", "content": system_msg}, + {"role": "user", "content": "Produce the EVAL REPORT in the specified format. Be objective and precise."} +] + +headers = {"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"} + +if provider == "openai": + import urllib.request, urllib.error + data = json.dumps({"model": model, "messages": messages, "temperature": 0.1, "max_tokens": 4000}).encode() + req = urllib.request.Request("https://api.openai.com/v1/chat/completions", data=data, headers=headers, method="POST") + try: + with urllib.request.urlopen(req, timeout=120) as resp: + result = json.loads(resp.read()) + content = result["choices"][0]["message"]["content"] + print(json.dumps({"status": "ok", "content": content, "model": result.get("model", model)})) + except urllib.error.HTTPError as e: + body = e.read().decode() + print(json.dumps({"status": "error", "error": f"HTTP {e.code}: {body}"})) +elif provider == "anthropic": + import urllib.request, urllib.error + data = json.dumps({ + "model": model, + "max_tokens": 4000, + "temperature": 0.1, + "system": system_msg, + "messages": [{"role": "user", "content": "Produce the EVAL REPORT in the specified format. Be objective and precise."}] + }).encode() + req = urllib.request.Request("https://api.anthropic.com/v1/messages", data=data, headers={**headers, "anthropic-version": "2023-06-01", "x-api-key": api_key}, method="POST") + try: + with urllib.request.urlopen(req, timeout=120) as resp: + result = json.loads(resp.read()) + content = result["content"][0]["text"] + print(json.dumps({"status": "ok", "content": content, "model": result.get("model", model)})) + except urllib.error.HTTPError as e: + body = e.read().decode() + print(json.dumps({"status": "error", "error": f"HTTP {e.code}: {body}"})) +"@ + +$tmpPy = Join-Path ([System.IO.Path]::GetTempPath()) "eval-$([System.Guid]::NewGuid()).py" +Set-Content -Path $tmpPy -Value $pythonScript -Encoding UTF8 + +try { + Write-Host "[EVAL] Sending to $Provider ($Model)..." -ForegroundColor Cyan + $result = & python $tmpPy 2>&1 + $json = $result | ConvertFrom-Json + + if ($json.status -eq "error") { + Write-Host "[EVAL ERROR] $($json.error)" -ForegroundColor Red + exit 1 + } + + Write-Host "" + Write-Host "[EVAL REPORT — External LLM]" -ForegroundColor Cyan + Write-Host "Model: $($json.model)" + Write-Host "" + Write-Host $json.content + + exit 0 +} +finally { + Remove-Item $tmpPy -Force -ErrorAction SilentlyContinue +} diff --git a/scripts/validate.ps1 b/scripts/validate.ps1 index 71868e3..c7e337c 100644 --- a/scripts/validate.ps1 +++ b/scripts/validate.ps1 @@ -1,4 +1,4 @@ -#!/usr/bin/env pwsh +#!/usr/bin/env pwsh # HUMAN-AI Integrity Validator (PowerShell 5.1+) # Validates cross-references and language coverage across all skill files. # Usage: powershell -File scripts/validate.ps1 [-Verbose] @@ -33,7 +33,7 @@ Write-Check "1. SKILL.md YAML Frontmatter" $skillContent = Get-Content (Join-Path $RepoRoot "SKILL.md") -Raw if ($skillContent -match "name:\s+human-ai") { Write-Pass "name: human-ai" } else { Write-Fail "name field missing or incorrect" } -if ($skillContent -match 'version:\s+"3\.0"') { Write-Pass "version: 3.0" } else { Write-Fail "version field missing or incorrect" } +if ($skillContent -match 'version:\s+"4\.0"') { Write-Pass "version: 4.0" } else { Write-Fail "version field missing or incorrect" } if ($skillContent -match "languages:") { Write-Pass "languages field present" } else { Write-Fail "languages field missing" } if ($skillContent -match "pipeline_stages:\s+5") { Write-Pass "pipeline_stages: 5" } else { Write-Fail "pipeline_stages field missing or incorrect" } @@ -289,18 +289,26 @@ Write-Host "" Write-Check "11. File tree consistency" $treeFiles = @( - "SKILL.md","README.md","README.ru.md","CHANGELOG.md","EVAL.md","KNOWN_LIMITATIONS.md","LICENSE",".gitignore", + "SKILL.md","README.md","README.ru.md","CHANGELOG.md","EVAL.md","KNOWN_LIMITATIONS.md","LICENSE",".gitignore","PLAN.md", "shared/burned-words.md","shared/ai-markers.md","shared/tone-profiles.md", "shared/specificity-ladder.md","shared/rhythm-tables.md","shared/language-template.md", "scenarios/full-rewrite.md","scenarios/blog-post.md","scenarios/landing-page.md", "scenarios/social-post.md","scenarios/seo-article.md","scenarios/case-study.md", "scenarios/commercial-offer.md","scenarios/email.md","scenarios/technical-doc.md", - "scenarios/translation-fix.md", + "scenarios/translation-fix.md","scenarios/press-release.md","scenarios/internal-memo.md", + "scenarios/grant-proposal.md","scenarios/creative-writing.md","scenarios/product-update.md", "scripts/validate.ps1","scripts/validate.sh", - "scripts/zerogpt-detect.ps1","scripts/zerogpt-detect.sh","scripts/run-benchmark.ps1", + "scripts/zerogpt-detect.ps1","scripts/zerogpt-detect.sh","scripts/run-benchmark.ps1","scripts/run-benchmark.sh", + "scripts/morph-check.ps1","scripts/readability-check.ps1","scripts/run-eval.ps1","scripts/clause-check.ps1", "examples/en-blog-post.md","examples/en-landing.md","examples/en-social.md", "examples/ru-blog-post.md","examples/ru-landing.md","examples/ru-social.md", - "examples/uk-blog-post.md","examples/uk-social.md" + "examples/uk-blog-post.md","examples/uk-social.md", + "examples/de-blog-post.md","examples/de-email.md", + "examples/fr-blog-post.md","examples/fr-social.md", + "examples/es-blog-post.md","examples/es-landing.md", + "examples/pt-blog-post.md","examples/pt-social.md", + "examples/it-blog-post.md","examples/it-landing.md", + "examples/pl-blog-post.md","examples/pl-social.md" ) foreach ($f in $treeFiles) { @@ -356,6 +364,31 @@ if (Test-Path $annotationsPath) { Write-Fail "annotations.json missing" } +# ============================================ +Write-Host "" +Write-Check "13. SKILL.md self-containment — embedded data vs shared/ links" + +if ($skillContent -match "raw.githubusercontent.com") { + Write-Pass "SKILL.md contains GitHub raw URLs for deep data" +} else { + Write-Warn "SKILL.md missing GitHub raw URLs for deep data" +} +if ($skillContent -match "Top burned words") { + Write-Pass "SKILL.md has embedded burned-words table" +} else { + Write-Warn "SKILL.md may be missing embedded burned-words" +} +if ($skillContent -match "morph-check\.ps1") { + Write-Pass "SKILL.md references morph-check.ps1" +} else { + Write-Warn "SKILL.md missing morph-check reference" +} +if ($skillContent -match "readability-check\.ps1") { + Write-Pass "SKILL.md references readability-check.ps1" +} else { + Write-Warn "SKILL.md missing readability-check reference" +} + # ============================================ Write-Host "" Write-Host "========================================" -ForegroundColor Cyan diff --git a/shared/morph/blacklist-ru.txt b/shared/morph/blacklist-ru.txt new file mode 100644 index 0000000..c377f96 --- /dev/null +++ b/shared/morph/blacklist-ru.txt @@ -0,0 +1,38 @@ +# Blacklist — известные AI-кальки и выдуманные слова +# Формат: одно слово на строку (в любой форме — скрипт нормализует через pymorphy3) +# Слова из этого списка ВСЕГДА считаются ошибкой, даже если pymorphy3 их знает + +# AI-кальки с английского (не являются русскими словами) +имплементирование +имплементация +функционализировать +оптимизируемость +трансформационность +автоматизированность +пользователецентричный +клиентоориентированность +релевантность +эффективностный +инновационность +интегрируемость +масштабируемость +кастомизируемость + +# Искажённые формы +осуществляемость +явленность +данность +посредственность +имеемость +производимость +задействованность +вовлечённостный + +# Машинные кальки (прямой перевод английской грамматики) +является тем что +является важным отметить +в данном контексте +в рамках данного +посредством использования +с целью оптимизации +в целях повышения diff --git a/shared/morph/whitelist-ru.txt b/shared/morph/whitelist-ru.txt new file mode 100644 index 0000000..0b0871f --- /dev/null +++ b/shared/morph/whitelist-ru.txt @@ -0,0 +1,56 @@ +# Whitelist — допустимые слова русского языка, отсутствующие в OpenCorpora +# Формат: одно слово на строку (в нормальной форме) +# Слова из этого списка НЕ считаются ошибкой при морфо-проверке + +# Технические неологизмы (уже вошли в язык) +нейросетевой +нейросеть +криптовалюта +блокчейн +токенизация +датасет +фреймворк +деплой +коммит +пулл-реквест +парсить +рендерить +агриться +хейтить +краудфандинг +фандрайзинг +скрам +спринт +бэклог +фича +баг +фикс +релиз +апишка +докер +кубер +микросервис + +# Бизнес-термины +воркфлоу +онбординг +пивот +апсейл +кросс-сейл +лидогенерация +ретеншн +дашборд +скоуп +стейкхолдер +фасилитация +тимлид +техлид +продакт +фаундер +стартап +пресейл +аутсорс +аутстафф +инхаус +бенчмарк +кастдев diff --git a/tests/benchmark/ai-texts/de/email.md b/tests/benchmark/ai-texts/de/email.md new file mode 100644 index 0000000..5944c69 --- /dev/null +++ b/tests/benchmark/ai-texts/de/email.md @@ -0,0 +1,14 @@ +# Email: KI-gestützte Prozessoptimierung für Ihr Unternehmen + +Betreff: Revolutionieren Sie Ihre Geschäftsprozesse mit unserer innovativen Lösung + +Sehr geehrte Damen und Herren, + +in der heutigen dynamischen Geschäftslandschaft ist es von entscheidender Bedeutung, Workflows zu optimieren und Synergien zu nutzen. Wir freuen uns, Ihnen unsere umfassende Plattform vorstellen zu dürfen, die eine nahtlose Integration in Ihre bestehenden Systeme ermöglicht. + +Unsere state-of-the-art Lösung bietet eine ganzheitliche Herangehensweise an die digitale Transformation. Darüber hinaus wird eine robuste Sicherheitsarchitektur gewährleistet, die den höchsten Standards entspricht. Es ist wichtig zu betonen, dass unsere Technologie skalierbar und extrem anpassungsfähig ist. + +Zusammenfassend lässt sich sagen, dass unsere innovative Plattform einen echten Game-Changer für Ihr Unternehmen darstellt. Wir würden uns freuen, Ihnen in einem persönlichen Gespräch weitere Details zu präsentieren. + +Mit freundlichen Grüßen, +Ihr Solution-Team diff --git a/tests/benchmark/ai-texts/de/landing.md b/tests/benchmark/ai-texts/de/landing.md new file mode 100644 index 0000000..4898cf3 --- /dev/null +++ b/tests/benchmark/ai-texts/de/landing.md @@ -0,0 +1,7 @@ +# Landing: CloudFlow — Die revolutionäre SaaS-Plattform + +Willkommen bei CloudFlow, der revolutionären Plattform, die Ihre Geschäftsprozesse transformiert und Abläufe optimiert. Unsere innovative Lösung wurde entwickelt, um Unternehmen jeder Größe zu befähigen, ihr volles Potenzial auszuschöpfen. + +Mit einer nahtlosen Integration in Ihre bestehende IT-Infrastruktur ermöglicht CloudFlow eine ganzheitliche Optimierung Ihrer Workflows. Die robuste Architektur garantiert höchste Ausfallsicherheit und Skalierbarkeit. Darüber hinaus profitieren Sie von modernsten KI-Funktionen, die routinemäßige Aufgaben automatisieren. + +Es ist wichtig zu beachten, dass unser Ökosystem kontinuierlich weiterentwickelt wird, um stets Best-in-Class zu bleiben. Zusammenfassend lässt sich sagen, dass CloudFlow den entscheidenden Wettbewerbsvorteil bietet. Starten Sie noch heute Ihre digitale Transformation. diff --git a/tests/benchmark/ai-texts/es/email.md b/tests/benchmark/ai-texts/es/email.md new file mode 100644 index 0000000..7b23b7d --- /dev/null +++ b/tests/benchmark/ai-texts/es/email.md @@ -0,0 +1,14 @@ +# Email: Solución integral para la transformación digital de su empresa + +Asunto: Descubra cómo nuestra plataforma innovadora puede revolucionar su negocio + +Estimado cliente, + +En el mundo actual, es fundamental contar con herramientas que permitan optimizar los procesos y facilitar la colaboración entre equipos. Es por ello que nos complace presentarle nuestra solución integral, diseñada para empoderar a las organizaciones en su camino hacia la transformación digital. + +Nuestra plataforma ofrece una integración sin fisuras con sus sistemas actuales, garantizando un ecosistema dinámico y robusto. Estamos transformando la manera en que las empresas gestionan sus flujos de trabajo. Sin embargo, lo más destacable es la escalabilidad de nuestra arquitectura. + +Por lo tanto, le invitamos a conocer de primera mano cómo nuestra tecnología de vanguardia puede convertirse en una verdadera palanca de crecimiento para su organización. No dude en contactarnos para agendar una demostración. + +Atentamente, +El equipo de ventas diff --git a/tests/benchmark/ai-texts/es/landing.md b/tests/benchmark/ai-texts/es/landing.md new file mode 100644 index 0000000..e235f47 --- /dev/null +++ b/tests/benchmark/ai-texts/es/landing.md @@ -0,0 +1,7 @@ +# Landing: TaskPro — La plataforma que está revolucionando el trabajo en equipo + +Bienvenido a TaskPro, la solución SaaS más innovadora para la gestión de proyectos empresariales. En la era digital, las organizaciones necesitan herramientas que verdaderamente transformen su productividad y optimicen cada aspecto de sus operaciones. + +Nuestra plataforma holística integra funciones de vanguardia con una interfaz intuitiva y sin fisuras. Estamos revolucionando la colaboración mediante un ecosistema robusto que facilita la comunicación en tiempo real. Además, ofrecemos una seguridad de nivel empresarial absolutamente confiable. + +No obstante, lo que realmente distingue a TaskPro es su capacidad para escalar junto con su negocio. Por lo tanto, si busca una solución integral que empodere a su equipo y maximice los resultados, TaskPro es la respuesta. Comience hoy mismo y descubra el futuro del trabajo. diff --git a/tests/benchmark/ai-texts/fr/email.md b/tests/benchmark/ai-texts/fr/email.md new file mode 100644 index 0000000..0e68cf4 --- /dev/null +++ b/tests/benchmark/ai-texts/fr/email.md @@ -0,0 +1,14 @@ +# Email: Optimisez votre performance avec notre plateforme innovante + +Objet : Transformez votre entreprise grâce à une solution complète et évolutive + +Madame, Monsieur, + +Dans le cadre de notre démarche d'excellence opérationnelle, nous avons le plaisir de vous présenter notre plateforme de pointe. Force est de constater que dans le contexte actuel, les entreprises doivent optimiser leurs processus pour rester compétitives. + +Notre solution holistique permet de faciliter la mise en œuvre de stratégies de transformation digitale. En termes de performance, notre outil intègre des fonctionnalités robustes et une interface transparente. Il convient de noter que notre écosystème dynamique s'adapte à vos besoins spécifiques. + +Par ailleurs, nous proposons un accompagnement personnalisé pour garantir une transition absolument fluide. Nous restons à votre entière disposition pour échanger sur la manière dont notre solution peut véritablement révolutionner votre activité. + +Cordialement, +L'équipe commerciale diff --git a/tests/benchmark/ai-texts/fr/social.md b/tests/benchmark/ai-texts/fr/social.md new file mode 100644 index 0000000..bfbfee9 --- /dev/null +++ b/tests/benchmark/ai-texts/fr/social.md @@ -0,0 +1,9 @@ +# Social: L'avenir du travail est déjà là + +🚀 Dans un monde professionnel en pleine mutation, il est absolument essentiel de disposer d'outils capables de transformer votre façon de collaborer. Notre nouvelle plateforme révolutionnaire change véritablement la donne. + +Grâce à une approche holistique et des fonctionnalités de pointe, vous pouvez désormais optimiser vos flux de travail en toute transparence. En termes d'efficacité, les résultats sont remarquablement rapides. + +De plus, notre écosystème intègre une synergie parfaite entre tous vos outils existants. Il convient de souligner que la mise en œuvre est incroyablement simple et ne nécessite aucune compétence technique. + +Prêt à découvrir comment notre solution innovante peut véritablement accélérer votre croissance ? 👉 Lien en bio. diff --git a/tests/benchmark/ai-texts/it/email.md b/tests/benchmark/ai-texts/it/email.md new file mode 100644 index 0000000..41b3ff2 --- /dev/null +++ b/tests/benchmark/ai-texts/it/email.md @@ -0,0 +1,14 @@ +# Email: Soluzioni innovative per la crescita del tuo business + +Oggetto: Scopri come la nostra piattaforma può trasformare la tua azienda + +Gentile Cliente, + +Nel panorama attuale, è fondamentale poter contare su strumenti capaci di ottimizzare i flussi di lavoro e facilitare la collaborazione. Siamo lieti di presentarle la nostra soluzione completa, progettata per potenziare le performance aziendali attraverso tecnologie all'avanguardia. + +La nostra piattaforma offre un ecosistema dinamico e scalabile, con un'integrazione senza soluzione di continuità nei suoi sistemi esistenti. Inoltre, garantiamo una sicurezza robusta e una gestione granulare dei permessi. Si rende necessario sottolineare come l'approccio olistico della nostra soluzione rappresenti un vero vantaggio competitivo. + +Peraltro, offriamo un supporto dedicato per assicurare una transizione assolutamente fluida. Saremo lieti di organizzare una demo personalizzata per mostrarle come possiamo veramente rivoluzionare i suoi processi. + +Cordiali saluti, +Il Team Commerciale diff --git a/tests/benchmark/ai-texts/it/landing.md b/tests/benchmark/ai-texts/it/landing.md new file mode 100644 index 0000000..62357a5 --- /dev/null +++ b/tests/benchmark/ai-texts/it/landing.md @@ -0,0 +1,7 @@ +# Landing: FlowDesk — La piattaforma che sta rivoluzionando la produttività + +Benvenuti in FlowDesk, la soluzione SaaS più innovativa per la gestione dei progetti aziendali. Nel panorama competitivo odierno, le organizzazioni hanno bisogno di strumenti che trasformino radicalmente il loro modo di lavorare e ottimizzino ogni aspetto operativo. + +La nostra piattaforma olisticamente progettata integra funzionalità di ultima generazione in un'interfaccia intuitiva e senza soluzione di continuità. Stiamo veramente rivoluzionando la collaborazione attraverso un ecosistema robusto che facilita la comunicazione in tempo reale. Inoltre, offriamo una sicurezza di livello enterprise assolutamente affidabile. + +D'altro canto, ciò che distingue FlowDesk è la capacità di scalare insieme al tuo business. È doveroso sottolineare che la nostra soluzione è stata concepita per potenziare i team e massimizzare i risultati. Inizia oggi e scopri il futuro del lavoro. diff --git a/tests/benchmark/ai-texts/pl/email.md b/tests/benchmark/ai-texts/pl/email.md new file mode 100644 index 0000000..c118e54 --- /dev/null +++ b/tests/benchmark/ai-texts/pl/email.md @@ -0,0 +1,16 @@ +# Email: Kompleksowe rozwiązanie dla Twojego biznesu + +Temat: Zrewolucjonizuj procesy w swojej firmie dzięki innowacyjnej platformie + +Szanowni Państwo, + +W dzisiejszym cyfrowym świecie niezwykle istotne jest, aby firmy mogły optymalizować swoje procesy i skutecznie integrować nowe technologie. Z przyjemnością przedstawiamy nasze kompleksowe rozwiązanie, które umożliwia transformację cyfrową w każdej organizacji. + +Nasza platforma oferuje holistyczne podejście do zarządzania przepływem pracy. Ponadto zapewnia solidną architekturę bezpieczeństwa oraz dynamiczny ekosystem narzędzi, które usprawniają codzienne zadania. Warto podkreślić, że nasze rozwiązanie jest w pełni skalowalne i dostosowuje się do potrzeb rozwijających się firm. + +Co więcej, oferujemy dedykowany serwis wsparcia technicznego, absolutnie niezbędny przy wdrażaniu zaawansowanych technologii. Należy zauważyć, że nasza platforma stanowi przełom na rynku rozwiązań B2B. + +Zapraszamy do kontaktu w celu umówienia prezentacji. + +Z poważaniem, +Zespół Sprzedaży diff --git a/tests/benchmark/ai-texts/pl/social.md b/tests/benchmark/ai-texts/pl/social.md new file mode 100644 index 0000000..fe09a84 --- /dev/null +++ b/tests/benchmark/ai-texts/pl/social.md @@ -0,0 +1,9 @@ +# Social: Czas na prawdziwą transformację Twojego biznesu + +🔥 W obecnej erze cyfrowej kluczem do sukcesu jest posiadanie narzędzi, które naprawdę usprawniają codzienną pracę. Nasza nowa platforma to innowacyjne rozwiązanie, które zmienia sposób, w jaki zespoły współpracują i osiągają cele. + +Oferujemy kompleksowe podejście, łączące zaawansowaną automatykę z dynamicznym ekosystemem aplikacji biznesowych. Ponadto nasza technologia pozwala na optymalizację przepływu informacji w sposób dotąd niespotykany. + +Dodatkowo zapewniamy dedykowany panel analityczny, który umożliwia śledzenie wyników w czasie rzeczywistym. Warto podkreślić, że wdrożenie jest niezwykle proste i nie wymaga specjalistycznej wiedzy. + +Chcesz dowiedzieć się więcej o tym przełomowym narzędziu? 🔗 Link w bio. diff --git a/tests/benchmark/ai-texts/pt/email.md b/tests/benchmark/ai-texts/pt/email.md new file mode 100644 index 0000000..42e3436 --- /dev/null +++ b/tests/benchmark/ai-texts/pt/email.md @@ -0,0 +1,14 @@ +# Email: Potencialize seus resultados com nossa plataforma inovadora + +Assunto: Transforme a gestão da sua empresa com uma solução abrangente e escalável + +Prezado(a) Cliente, + +No cenário atual de constante transformação digital, é absolutamente essencial que as organizações otimizem seus processos para se manterem competitivas. É com satisfação que apresentamos nossa plataforma de ponta, projetada para potencializar a eficiência operacional do seu negócio. + +Nossa solução holística permite integrar todos os seus fluxos de trabalho em um ecossistema dinâmico e transparente. Além disso, oferecemos funcionalidades robustas que facilitam a colaboração entre equipes. Estamos constantemente otimizando a experiência do usuário para garantir resultados verdadeiramente excepcionais. + +Ademais, o nosso sistema foi desenvolvido para ser completamente escalável, adaptando-se ao crescimento da sua empresa. Não perca a oportunidade de alavancar todo o potencial da sua organização com uma tecnologia revolucionária. + +Atenciosamente, +Equipe Comercial diff --git a/tests/benchmark/ai-texts/pt/social.md b/tests/benchmark/ai-texts/pt/social.md new file mode 100644 index 0000000..5da47cb --- /dev/null +++ b/tests/benchmark/ai-texts/pt/social.md @@ -0,0 +1,9 @@ +# Social: O futuro da produtividade chegou + +🌟 No mundo digital de hoje, a diferença entre crescer e estagnar está nas ferramentas que você utiliza. Nossa nova plataforma está transformando a maneira como equipes colaboram e otimizam seus resultados. + +Com uma abordagem verdadeiramente holística, integramos todas as funcionalidades que você precisa em um único ecossistema dinâmico. Além disso, nossa arquitetura robusta garante uma experiência absolutamente fluida e sem interrupções. + +O mesmo se aplica à segurança dos seus dados, que é tratada com os mais altos padrões do mercado. Ademais, estamos constantemente revolucionando nossos recursos para oferecer o que há de mais inovador. + +Pronto para dar o próximo passo e alavancar o potencial da sua equipe? 🚀 Acesse o link na bio e descubra como. diff --git a/tests/benchmark/annotations.json b/tests/benchmark/annotations.json index 18d761b..2ff2ce1 100644 --- a/tests/benchmark/annotations.json +++ b/tests/benchmark/annotations.json @@ -214,6 +214,177 @@ "expected_tone": "human", "rhythm_issues": ["bureaucratic nominalization"] }, + "ai-texts/de/email.md": { + "language": "de", + "ai_probability": 88, + "markers": { + "openers": ["Sehr geehrte Damen und Herren"], + "burned_words": ["optimieren", "Synergie", "ganzheitliche", "revolutionär", "skalierbar", "Game-Changer"], + "fake_transitions": ["Darüber hinaus", "Des Weiteren"], + "hedging": ["Es ist wichtig zu betonen"], + "conclusion_regurgitation": ["Zusammenfassend lässt sich sagen"] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "biz", + "rhythm_issues": ["Nominalstil", "passive constructions"] + }, + "ai-texts/de/landing.md": { + "language": "de", + "ai_probability": 92, + "markers": { + "openers": ["In der heutigen digitalen Welt"], + "burned_words": ["optimiert", "nahtlos", "innovative", "revolutionäre", "robust", "skalierbare", "state-of-the-art", "Best-in-Class"], + "fake_transitions": ["Darüber hinaus"], + "hedging": [], + "conclusion_regurgitation": [] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "landing", + "rhythm_issues": ["symmetrical structure", "no fragments"] + }, + "ai-texts/fr/email.md": { + "language": "fr", + "ai_probability": 90, + "markers": { + "openers": ["Madame, Monsieur"], + "burned_words": ["optimiser", "holistique", "transparente", "révolutionnaire", "synergie", "disruptif"], + "fake_transitions": ["De plus", "En outre"], + "hedging": ["Il convient de noter que", "Force est de constater que"], + "conclusion_regurgitation": ["En conclusion"] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "biz", + "rhythm_issues": ["over-formal constructions", "en termes de overuse"] + }, + "ai-texts/fr/social.md": { + "language": "fr", + "ai_probability": 82, + "markers": { + "openers": ["Dans un monde en constante évolution"], + "burned_words": ["optimiser", "innovante", "holistique", "écosystème"], + "fake_transitions": ["De plus"], + "hedging": ["Il est important de noter"], + "conclusion_regurgitation": [], + "rhetorical_padding": ["Prêt à transformer votre approche ?"] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "social", + "rhythm_issues": ["no fragments", "uniform sentence length"] + }, + "ai-texts/es/email.md": { + "language": "es", + "ai_probability": 86, + "markers": { + "openers": ["En el mundo actual"], + "burned_words": ["optimizar", "sin fisuras", "holístico", "revolucionario", "integral", "sinergia"], + "fake_transitions": ["Además", "Asimismo"], + "hedging": ["Cabe destacar"], + "conclusion_regurgitation": ["En conclusión"] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "biz", + "rhythm_issues": ["gerundio excesivo", "sin embargo overuse"] + }, + "ai-texts/es/landing.md": { + "language": "es", + "ai_probability": 91, + "markers": { + "openers": ["En la era digital"], + "burned_words": ["optimiza", "sin fisuras", "robusta", "de vanguardia", "integral", "escalable", "revolucionaria"], + "fake_transitions": ["Además"], + "hedging": [], + "conclusion_regurgitation": [] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "landing", + "rhythm_issues": ["symmetrical structure", "no fragments"] + }, + "ai-texts/pt/email.md": { + "language": "pt", + "ai_probability": 87, + "markers": { + "openers": ["No cenário atual"], + "burned_words": ["otimizar", "holística", "inovador", "sinergia", "alavancar", "ecossistema"], + "fake_transitions": ["Além disso", "Ademais"], + "hedging": ["É importante notar"], + "conclusion_regurgitation": ["Em conclusão"] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "biz", + "rhythm_issues": ["gerúndio excessivo", "o mesmo/a mesma pronoun"] + }, + "ai-texts/pt/social.md": { + "language": "pt", + "ai_probability": 80, + "markers": { + "openers": ["No mundo digital de hoje"], + "burned_words": ["otimizar", "inovador", "revolucionário", "disruptivo"], + "fake_transitions": ["Além disso"], + "hedging": ["Vale ressaltar"], + "conclusion_regurgitation": [], + "rhetorical_padding": ["Quer saber mais?"] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "social", + "rhythm_issues": ["uniform sentences", "no punch ending"] + }, + "ai-texts/it/email.md": { + "language": "it", + "ai_probability": 89, + "markers": { + "openers": ["Nel panorama attuale"], + "burned_words": ["ottimizzare", "senza soluzione di continuità", "innovativo", "rivoluzionario", "sinergia", "scalabile"], + "fake_transitions": ["Inoltre", "Per di più"], + "hedging": ["Si rende necessario evidenziare"], + "conclusion_regurgitation": ["In conclusione"] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "biz", + "rhythm_issues": ["si passivante eccessivo", "over-formal constructions"] + }, + "ai-texts/it/landing.md": { + "language": "it", + "ai_probability": 93, + "markers": { + "openers": ["Nel mondo digitale di oggi"], + "burned_words": ["ottimizza", "senza soluzione di continuità", "innovativa", "all'avanguardia", "robusta", "scalabile", "completa"], + "fake_transitions": ["Inoltre"], + "hedging": [], + "conclusion_regurgitation": [] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "landing", + "rhythm_issues": ["symmetrical structure", "no fragments"] + }, + "ai-texts/pl/email.md": { + "language": "pl", + "ai_probability": 88, + "markers": { + "openers": ["W dzisiejszym cyfrowym świecie"], + "burned_words": ["optymalizować", "holistyczny", "innowacyjny", "rewolucyjny", "kompleksowe rozwiązanie", "wykorzystywać"], + "fake_transitions": ["Ponadto", "Co więcej"], + "hedging": ["Należy podkreślić", "Warto zauważyć"], + "conclusion_regurgitation": ["Podsumowując"] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "biz", + "rhythm_issues": ["nadmierna nominalizacja", "English calques"] + }, + "ai-texts/pl/social.md": { + "language": "pl", + "ai_probability": 83, + "markers": { + "openers": ["W dzisiejszych czasach"], + "burned_words": ["optymalizować", "innowacyjny", "przełomowy", "kompleksowe"], + "fake_transitions": ["Ponadto"], + "hedging": ["Należy zauważyć"], + "conclusion_regurgitation": [], + "rhetorical_padding": ["Chcesz dowiedzieć się więcej?"] + }, + "expected_rung_improvement": "0-1 to 2+", + "expected_tone": "social", + "rhythm_issues": ["uniform sentences", "no fragments"] + }, "human-texts/en-blog.md": { "language": "en", "ai_probability": 8, diff --git a/tests/benchmark/readability-baseline.json b/tests/benchmark/readability-baseline.json new file mode 100644 index 0000000..148ba25 --- /dev/null +++ b/tests/benchmark/readability-baseline.json @@ -0,0 +1,16 @@ +{ + "version": "1.0", + "description": "Readability baseline metrics for HUMAN-AI benchmark texts. Each entry maps a test file to expected readability scores (Flesch, LIX, Fog) BEFORE humanization.", + "engine": "ReadSightPy >= 1.0.0", + "entries": { + "ai-texts/en/blog-post.md": { "flesch": 45, "lix": 48, "fog": 16.5, "note": "Heavy AI — academic tone, long sentences" }, + "ai-texts/en/landing.md": { "flesch": 50, "lix": 45, "fog": 14.0, "note": "Marketing fluff — burned words everywhere" }, + "ai-texts/en/social.md": { "flesch": 55, "lix": 42, "fog": 12.0, "note": "LinkedIn AI post" }, + "ai-texts/en/email.md": { "flesch": 48, "lix": 46, "fog": 15.0, "note": "B2B cold email — hope this finds you well" }, + "ai-texts/en/tech-doc.md": { "flesch": 40, "lix": 50, "fog": 17.0, "note": "Technical doc — leaked AI" }, + "ai-texts/ru/blog-post.md": { "flesch": 35, "lix": 52, "fog": 18.0, "note": "Russian AI blog — канцелярит" }, + "ai-texts/ru/landing.md": { "flesch": 38, "lix": 50, "fog": 16.0, "note": "Russian AI landing page" }, + "ai-texts/ru/social.md": { "flesch": 42, "lix": 44, "fog": 13.0, "note": "Russian AI social post" }, + "ai-texts/uk/blog-post.md": { "flesch": 36, "lix": 51, "fog": 17.5, "note": "Ukrainian AI blog — Russianisms" } + } +}