Guide Recap

Generate social media content from CHANGELOG.md entries. Produces 8 outputs by default (4 formats x 2 languages).

When to Use

• After running /release to create social announcements

• Weekly to summarize multiple releases

• Before posting on LinkedIn, Twitter/X, newsletter, or Slack

Usage

/guide-recap latest # Latest released version /guide-recap v3.20.5 # Specific version /guide-recap week # Current week (Monday to today) /guide-recap week 2026-01-27 # Specific week (Monday to Sunday)

Flags

Flag Effect Default

--interactive

Guide mode: choose angle, audience, highlight Off (auto-draft)

--format=X

Single format: linkedin , twitter , newsletter , slack

All 4 formats

--lang=X

Single language: fr , en

Both FR + EN

--save

Save output to [project-docs]/social-posts/

Display only

--force

Generate even if only maintenance entries Skip low-score

Workflow (7 Steps)

Step 1: Parse Input

Parse $ARGUMENTS to determine mode:

Input Mode Target

latest

Single version First ## [X.Y.Z] after [Unreleased]

vX.Y.Z or X.Y.Z

Single version Exact version match

week

Week range Monday of current week -> today

week YYYY-MM-DD

Week range That Monday -> following Sunday

If no argument or invalid argument, display usage and exit.

Step 2: Extract CHANGELOG Entries

Read CHANGELOG.md from the project root.

Single version:

• Find line matching ## [{version}]

• Extract all content until next ## [ line

• Parse ### Added , ### Changed , ### Fixed sections

Week range:

• Collect all ## [X.Y.Z] - YYYY-MM-DD entries where date falls in range

• Parse all sections from all matching versions

Error: version not found -> List last 5 versions, suggest latest . Error: week has no entries -> Show date of last release, suggest that version.

Step 3: Categorize Entries

For each top-level entry (first-level bullet under ### ), assign a category:

Category Weight Detection

NEW_CONTENT

3 New files, new sections, new diagrams, new quiz questions

GROWTH_METRIC

2 Line count growth, item count changes

RESEARCH

1 Resource evaluations, external source integrations

FIX

1 Under ### Fixed , corrections

MAINTENANCE

0 README updates, badge syncs, landing syncs, count updates

See references/changelog-parsing-rules.md for detailed classification rules.

Step 4: Transform to User Value

Apply mappings from references/content-transformation.md :

• Technical language -> user benefit

• Extract concrete numbers

• Credit named sources

• Cluster related entries

Validate against references/tone-guidelines.md DO/DON'T checklist.

Step 4b: Interactive Mode (--interactive only)

If --interactive flag is set, insert between steps 4 and 5:

Display candidate highlights with scores:

Highlights (by score): [14] 4 new ASCII diagrams (16 -> 20) [NEW_CONTENT] [ 9] 30 new quiz questions (227 -> 257) [NEW_CONTENT] [ 6] Docker sandbox isolation guide [NEW_CONTENT] [ 1] README updated [MAINTENANCE]

Ask angle:

• Auto (highest scored = hook)

• User picks specific entry as hook

• Custom angle (user provides theme)

Ask target audience:

• devs (technical depth)

• tech-leads (impact focus)

• general (accessible language)

• all (default, balanced)

Ask primary highlight:

• Auto (top score)

• User selects from list

Confirm selection and proceed to step 5.

Step 5: Score and Select

Compute score for each entry:

score = (category_weight * 3) + (has_number * 2) + (named_source * 1) + (new_file * 1) + (min(impact_files, 3)) + (breaking * 2)

Select top 3-4 entries by score. Highest score = hook line.

If all scores < 3: Output "No social content recommended for this version. Use --force to generate anyway." and exit (unless --force ).

Step 6: Generate Content

For each requested format (default: all 4) and language (default: both):

• Read the corresponding template from assets/

• Fill template fields using scored and transformed entries

• Apply tone-guidelines.md quality checklist

Links:

Format Link Target

LinkedIn Landing site URL

Twitter GitHub repo URL

Newsletter Both (landing + GitHub)

Slack GitHub repo URL

URLs:

• Landing: https://{DOMAIN}/

• GitHub: https://github.com/{OWNER}/{REPO}

Step 7: Output

Display each generated post in a fenced code block, labeled by format and language:

LinkedIn (FR)

[content]
`` `

## LinkedIn (EN)

```text
[content]
`` `

## Twitter/X (FR)

```text
[content]
`` `

...

If --save
 flag: write all outputs to [project-docs]/social-posts/YYYY-MM-DD-vX.Y.Z.md
 (for version) or [project-docs]/social-posts/YYYY-MM-DD-week.md
 (for week). Create [project-docs]/social-posts/
 directory if it doesn't exist.

Error Handling

Error
Response

No argument
Display usage block

Invalid argument
Display usage block with examples

Version not found
List 5 most recent versions, suggest latest

Week has no entries
Show date of last release, suggest version

All entries MAINTENANCE (score 0)
"No social content recommended. Use --force
 to override."

CHANGELOG.md not found
"CHANGELOG.md not found in project root."

Reference Files

- references/tone-guidelines.md
 - DO/DON'T rules, emoji budget, language register

- references/changelog-parsing-rules.md
 - CHANGELOG format, extraction, scoring algorithm

- references/content-transformation.md
 - Technical -> user value mappings (30+)

- assets/linkedin-template.md
 - ~1300 chars, hook + bullets + CTA + hashtags

- assets/twitter-template.md
 - 280 chars single or 2-3 tweet thread

- assets/newsletter-template.md
 - ~500 words, structured sections

- assets/slack-template.md
 - Compact, emoji-rich, Slack formatting

- examples/version-output.md
 - Full example output for v3.20.5

- examples/week-output.md
 - Full example output for week 2026-01-27

Tips

- Run /guide-recap latest
 right after /release
 to prepare social posts

- Use --interactive
 the first few times to understand the scoring

- Use --format=linkedin --lang=fr
 when you only need one specific output

- --save
 outputs are gitignored via [project-docs]/
 convention

- Review and personalize before posting (these are drafts, not final copy)