| name | ring:generating-release-guides |
| description | Generating an internal Operations-facing update/migration guide from the git diff between two refs, documenting per-change client impact, deploy ordering, monitoring, and rollback notes in English, pt-br, or both. Use when preparing a version release or recording what changed for the Ops team. Runs read-only by default and previews before writing. Skip with no git repo or a trivial single-file change. |
Release Guide — Ops Update Guide Generator
When to use
- Preparing to release a new version
- Need to document what changed between refs
- Creating operational update guide
- Communicating version updates to Ops team
Skip when
- No git repository available
- Single file change (too small for formal guide)
- Customer-facing release notes only (use simpler template)
Inputs
BASE_REF (string, required): e.g. main, v1.0.0TARGET_REF (string, required): e.g. HEAD, v1.1.0VERSION (string, optional): auto-detected from tags if not providedLANGUAGE (enum, optional, default en): en, pt-br, bothMODE (enum, optional, default STRICT_NO_TOUCH): STRICT_NO_TOUCH, TEMP_CLONE_FOR_FRESH_REFS
Produce an internal Operations-facing update/migration guide from git diff analysis.
Safety Modes
STRICT_NO_TOUCH (default): Read-only git commands only. Forbidden: fetch, pull, push, checkout, switch, reset, commit, merge, rebase. If ref doesn't exist locally → STOP and suggest TEMP_CLONE mode.
TEMP_CLONE_FOR_FRESH_REFS: Clone to temp dir, fetch refs there, run all analysis in clone, cleanup after. Never touches current repo.
Process
Step 0: Execution Location
Determine mode. In TEMP_CLONE mode, create isolated clone before proceeding.
Step 1: Resolve Refs
git rev-parse --verify BASE_REF^{commit}
git rev-parse --verify TARGET_REF^{commit}
BASE_SHA=$(git rev-parse --short BASE_REF)
TARGET_SHA=$(git rev-parse --short TARGET_REF)
Step 1.5: Version Detection
if git tag -l "$TARGET_REF" | grep -q .; then
AUTO_VERSION=$(echo "$TARGET_REF" | sed -E 's/^[Vv]//;s/^[Rr]elease[-_]?//;s/^[Vv]ersion[-_]?//')
fi
Step 1.6: Commit Log Analysis
git log --oneline --no-merges BASE_REF...TARGET_REF
git log --pretty=format:"%h %s%n%b" --no-merges BASE_REF...TARGET_REF
Parse commit prefixes: feat: → Feature, fix: → Bug Fix, refactor: → Improvement, breaking: / BREAKING CHANGE: → Breaking.
Step 2: Produce Diff
git diff --find-renames --find-copies --stat BASE_REF...TARGET_REF
git diff --find-renames --find-copies BASE_REF...TARGET_REF
Step 3: Build Change Inventory
From diff, identify: endpoints (new/changed/removed), DB schema/migrations, messaging (topics/payloads), config/env vars, auth changes, performance (timeouts/pools), dependency bumps with runtime impact, observability changes.
Step 4: Write Guide
Use language-appropriate template based on LANGUAGE parameter.
English title: # Ops Update Guide — <repo> — <VERSION> — <TARGET_SHA>
Portuguese title: # Guia de Atualização (Ops) — <repo> — <VERSION> — <TARGET_SHA>
(Without version: use BASE_REF → TARGET_REF instead of <VERSION>)
Header block: Mode, Comparison, Base SHA, Target SHA, Date, Source.
Per section format: ## N. Descriptive Title [Category Emoji]
| Category | English | Portuguese | Emoji |
|---|
| Feature | Feature | Funcionalidade | ✨ |
| Bug Fix | Bug Fix | Correção | 🐛 |
| Improvement | Improvement | Melhoria | 🆙 |
| Breaking | Breaking | Breaking | ⚠️ |
| Infrastructure | Infrastructure | Infra | 🔧 |
| Observability | Observability | Observabilidade | 📊 |
| Data | Data | Dados | 💾 |
Each section contains (in order):
- Contextual narrative (1-3 paragraphs) — business/operational context, why this changed
- What Changed / O que mudou — bullet list with file:line references
- Why It Changed / Por que mudou — infer from code; if uncertain mark as ASSUMPTION + HOW TO VALIDATE
- Client Impact / Impacto para clientes — who's affected, risk level (Low/Medium/High)
- Required Client Action / Ação necessária do cliente — "None" or exact steps
- Deploy/Upgrade Notes / Notas de deploy/upgrade — ordering, rolling deploy safety
- Post-Deploy Monitoring / O que monitorar pós-deploy — logs in table format (Level | Message | Meaning), tracing spans in table format
- Rollback — Safety: Safe/Conditional/Not recommended (or pt-br equivalents) + steps
Special sections when applicable:
### ⚠️ Attention Point — confusing but expected behaviors- Backward compatibility table for data/schema changes
Step 5: Summary Section
English: Summary table (Features/Bug Fixes/Improvements/Data counts) + Rollback Compatibility matrix (| Item | Rollback | Justification |).
Portuguese: ## Resumo + ## Análise de Compatibilidade de Rollback with same structure.
Step 6: Preview Before Saving (MANDATORY)
Show before writing to disk:
- Repository, comparison range, version detected, language(s), mode
- Change summary table (categories + counts)
- Top 5 key changes
- Output file path(s)
Wait for user confirmation.
Step 7: Save File
Output directory: notes/releases/
| Has Version? | LANGUAGE | Filename |
|---|
| Yes | en | {DATE}_{REPO}-{VERSION}.md |
| Yes | pt-br | {DATE}_{REPO}-{VERSION}_pt-br.md |
| No | en | {DATE}_{REPO}-{BASE}-to-{TARGET}.md |
| No | pt-br | {DATE}_{REPO}-{BASE}-to-{TARGET}_pt-br.md |
| Any | both | Both files above |
Confirm after saving: file path(s), refs/SHAs used, version, language(s).
Hard Rules
| Rule | Requirement |
|---|
| No invented changes | MUST: All changes traceable to diff — nothing invented |
| Uncertain info | MUST: Mark uncertain claims as ASSUMPTION + HOW TO VALIDATE |
| Preview required | MUST: Show preview before saving — never skip |
| User confirmation | MUST: Wait for explicit user confirmation before writing files |
| Special change types | MUST: Explicitly document DB migrations, breaking API, feature flags, security/auth, log level changes |
Blocker Conditions
| Condition | Action |
|---|
| Ref cannot be resolved in STRICT mode | STOP — suggest TEMP_CLONE mode |
| Not in git repository | STOP — skill requires git context |
| diff returns empty | STOP — verify refs have commits between them |
| User declines preview | STOP — ask for corrections or abort confirmation |
