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

--interactive

--format=X

linkedin

twitter

newsletter

slack

--lang=X

fr

en

--save

[project-docs]/social-posts/

--force

Workflow (7 Steps)

Step 1: Parse Input

Parse

$ARGUMENTS

latest

## [X.Y.Z]

[Unreleased]

vX.Y.Z

X.Y.Z

week

week YYYY-MM-DD

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

Step 2: Extract CHANGELOG Entries

Read

CHANGELOG.md

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

Step 3: Categorize Entries

For each top-level entry (first-level bullet under

###

NEW_CONTENT

GROWTH_METRIC

RESEARCH

FIX

### Fixed

MAINTENANCE

See

references/changelog-parsing-rules.md

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

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

If

--interactive

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

--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:

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

[project-docs]/social-posts/YYYY-MM-DD-vX.Y.Z.md

[project-docs]/social-posts/YYYY-MM-DD-week.md

[project-docs]/social-posts/

Error Handling

latest

--force

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)