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:

1. Find line matching ## [{version}]
2. Extract all content until next ## [ line
3. Parse ### Added, ### Changed, ### Fixed sections

Week range:

1. Collect all ## [X.Y.Z] - YYYY-MM-DD entries where date falls in range
2. 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:

1. 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]
   

2. Ask angle:

   • Auto (highest scored = hook)
   • User picks specific entry as hook
   • Custom angle (user provides theme)

3. Ask target audience:

   • devs (technical depth)
   • tech-leads (impact focus)
   • general (accessible language)
   • all (default, balanced)

4. Ask primary highlight:

   • Auto (top score)
   • User selects from list

5. 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):

1. Read the corresponding template from assets/
2. Fill template fields using scored and transformed entries
3. 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)

```text
[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)