guide-recap

# 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)