# Carousel YAML Generation Rules

These rules are derived from the 3 sample files in `samples/` and their source articles in `src/content/blog/...`.

## 1. Purpose

A carousel YAML is a faithful, slide-by-slide **short version** of one article for social media publishing.
- It must read like a compact standalone text, not like commentary *about* the article.
- Preserve the article's thesis and argumentative flow.
- Compress details without inventing claims, numbers, or sources.
- Keep a neutral-analytical tone consistent with the source article.

## 2. Required YAML Structure

Use this shape:

```yaml
title: <main article title or series title>
subtitle: <section/topic subtitle>
slides:
  - title: <string, can be empty '' if needed>
    text: <slide text as a single unbroken line>
```

Rules:
- `title`, `subtitle`, `slides` are mandatory top-level keys.
- `slides` is an ordered list.
- Each slide must have `title` and `text`.
- `text` uses `|-` block scalar. Newlines are preserved and imported as paragraph breaks in Figma, so use them **only** for intentional divisions (between paragraphs or between bullet items).
- **Never break a sentence across multiple lines.** Each paragraph or bullet item must be on exactly one line.
- Correct (`\n` only at intentional boundaries):
  ```
  text: |-
    Primo paragrafo su una riga sola, anche se lungo.
    Secondo paragrafo, anch'esso su una riga sola.
    - Voce di elenco uno.
    - Voce di elenco due.
  ```
- Wrong (a capo in mezzo a una frase):
  ```
  text: |-
    Primo paragrafo su una riga sola,
    anche se lungo.
  ```

## 3. Slide Count

- Hard maximum: **20 slides**.
- No hard minimum, but target at least **4-5 slides** for short articles.
- For typical long-form articles, prefer **6-12 slides**.
- Use more slides when needed for clarity, never by splitting one point arbitrarily.

## 4. Word Limits Per Slide

Observed samples range from ~83 to ~197 words per slide.

Use these constraints:
- Target range: **150-170 words** per slide, including intro and outro slides.
- Absolute maximum: **200 words** per slide.

## 5. Content Mapping Rules

1. Slide 1: context + framing of the article question.
2. Slide 2: **table of contents** — a bullet list of the main topics covered, using `–` as bullet marker (one per line). Use the article's section headings as base, optionally adding a keyword or two to clarify each entry. Keep this slide short (60–120 words); it is navigational, not argumentative, so the word-count target does not apply. Title should be "Di cosa parleremo" or equivalent.
3. Middle slides: one key argument/chunk each, in original logical order.
4. Keep important quantitative findings (percentages, dates, comparisons) when central.
   Prefer concrete values over vague wording (e.g., write "54% vs 71%" instead of "much lower").
5. If a section is broad, split into 2 slides with same title (allowed).
6. Final slide: synthesis/conclusion; concise recap bullets are allowed.

## 6. Writing Style

- Language: keep the article language (samples are Italian).
- Voice: explanatory, precise, critical where the article is critical.
- Density: high-information prose, low fluff.
- Keep nuance and uncertainty markers when present (e.g., "non è chiaro", "in parte").
- Avoid direct citations unless essential; prefer paraphrase.
- Avoid markdown-heavy formatting; plain paragraphs are default.
- Simple bullet lists inside `text` are allowed when summarizing key points.
- **Do not use meta-summary phrasing** that talks about the article itself.
- Write claims directly as content, not as commentary on what the article says.
- Dashes: use the mid-length dash `–` (en-dash), neither the long `—` (em-dash) nor the short dash `-`.

Forbidden examples:
- "La tesi dell'articolo è..."
- "L'articolo critica..."
- "In questo articolo si analizza..."

Preferred style:
- State points directly (e.g., "Nel mercato del lavoro italiano...", "I dati mostrano...").

## 7. Fidelity and Safety Rules

- Do not introduce new evidence not present in the article.
- Do not alter the article's conclusion direction.
- Do not overstate causality if the article states correlation/ambiguity.
- Keep controversial claims framed as the article's analysis, not universal fact.
- When possible, preserve actual numbers from the source (%, counts, years, ranges), especially for key claims.

## 8. Quality Checklist (before finalizing)

- YAML is valid and parseable: it shall be output to a `.yml` file with the same title (kebab-case) as the article.
- Slide count is `<= 20`.
- Each slide respects the word cap (`<= 200`).
- Narrative progression is coherent from intro to conclusion.
- Core data points and caveats from the source article are preserved.
- No duplicated slides unless intentionally split by subtopic.

## 9. Reusable Prompt Add-on

Use this in future Codex prompts:

"Generate a carousel YAML from the article 'title.mdx' following `rules.md`. Keep the same language as the article, preserve argument order, use 4-20 slides (as needed by length), with 8-12 as an ideal target (excluding the TOC slide), and keep each content slide between 90 and 180 words (hard max 200). Always include a TOC slide as slide 2."