shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

ring:release-guide-info

Generate Ops Update Guide from Git Diff. Produces internal Operations-facing update/migration guides based on git diff analysis. Supports STRICT_NO_TOUCH (default) and TEMP_CLONE_FOR_FRESH_REFS modes. Includes tag auto-detection and commit log analysis.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Release Guide Info — Ops Update Guide Generator

Modularization Note

⚠️ CANDIDATE FOR MODULARIZATION: This skill file exceeds 700 lines and is a candidate for splitting into sub-skills. Future work MUST consider:

  1. Template extraction: Move language-specific templates (EN, PT-BR) to separate template files
  2. Section generators: Split each guide section (Breaking Changes, Configuration, Database, etc.) into separate template modules
  3. Git analysis separation: Extract git diff/commit analysis logic from documentation generation
  4. Output formatters: Separate markdown generation from content analysis

MUST NOT add new sections or languages without first implementing modularization to prevent further bloat.

Overview

You are a code-aware documentation agent. Produce an internal Operations-facing update/migration guide.

Runtime Inputs (REQUIRED)

| Input | Description | Example | |-------|-------------|---------| | BASE_REF | Starting point (branch, tag, or SHA) | main, release/v3.4.x, v1.0.0 | | TARGET_REF | Ending point (branch, tag, or SHA) | feature/foo, HEAD, v1.1.0 | | VERSION (optional) | Version number (auto-detected from tags if not provided) | v2.0.0, 1.5.0 | | LANGUAGE (optional) | Output language | en (default), pt-br, both | | MODE (optional) | Execution mode | STRICT_NO_TOUCH (default), TEMP_CLONE_FOR_FRESH_REFS |

Language options:

  • en — English only (default)
  • pt-br — Portuguese (Brazil) only
  • both — Generate two files, one in each language

Version handling:

  • If VERSION provided → Use it directly
  • If TARGET_REF is a tag → Auto-extract version from tag name
  • If neither → Omit version from output

Comparison range: Always use triple-dot BASE_REF...TARGET_REF

Safety Invariants

STRICT_NO_TOUCH (default)

Hard requirement: Do NOT alter anything in the current local repo.

FORBIDDEN commands:

  • git fetch, git pull, git push
  • git checkout, git switch, git reset, git clean
  • git commit, git merge, git rebase, git cherry-pick
  • git worktree, git gc, git repack, git prune
  • Any write operation to .git/ files

ALLOWED commands (read-only):

  • git rev-parse, git diff, git show, git log, git remote get-url

If ref does not exist locally: STOP and report:

  • Which ref failed to resolve
  • That STRICT_NO_TOUCH forbids fetching
  • Suggest alternative: TEMP_CLONE_FOR_FRESH_REFS

TEMP_CLONE_FOR_FRESH_REFS (optional)

Goal: Do NOT touch current repo, but allow obtaining up-to-date remote refs in an isolated temporary clone.

Process:

# 1. Get remote URL
REMOTE_URL=$(git remote get-url origin)

# 2. Create isolated temp clone
TMP_DIR=$(mktemp -d) || { echo "Failed to create temp directory"; exit 1; }
git clone --no-checkout "$REMOTE_URL" "$TMP_DIR"

# 3. Fetch refs in temp clone
cd "$TMP_DIR"
git fetch origin --prune --tags

# 4. Continue steps inside temp clone only

# 5. Cleanup after guide is generated
cd - >/dev/null
rm -rf "$TMP_DIR"

The Process

Step 0 — Determine Execution Location

If MODE=STRICT_NO_TOUCH: Operate in current repo with read-only commands only.

If MODE=TEMP_CLONE_FOR_FRESH_REFS: Create temp clone, operate there, cleanup after.

Step 1 — Resolve Refs and Metadata

# Verify refs exist
git rev-parse --verify BASE_REF^{commit}
git rev-parse --verify TARGET_REF^{commit}

# Capture SHAs
BASE_SHA=$(git rev-parse --short BASE_REF)
TARGET_SHA=$(git rev-parse --short TARGET_REF)

# Get repo/service name
origin_url="$(git remote get-url origin 2>/dev/null)"
[ -n "$origin_url" ] && printf '%s\n' "$origin_url" | sed 's|.*[:/]||;s|\.git$||' || basename "$(pwd)"

If verification fails:

  • STRICT_NO_TOUCH: STOP + suggest TEMP_CLONE_FOR_FRESH_REFS
  • TEMP_CLONE: STOP (refs truly not found)

Step 1.5 — Tag Auto-Detection and Version Resolution

Detect if refs are tags and extract version:

# Check if TARGET_REF is a tag
if git tag -l "$TARGET_REF" | grep -q .; then
    IS_TAG=true
    # Extract version from tag (handles v1.0.0, 1.0.0, release-1.0.0, etc.)
    AUTO_VERSION=$(echo "$TARGET_REF" | sed -E 's/^(v|release[-_]?|version[-_]?)?//i')
else
    IS_TAG=false
    AUTO_VERSION=""
fi

# Check if BASE_REF is a tag
if git tag -l "$BASE_REF" | grep -q .; then
    BASE_IS_TAG=true
else
    BASE_IS_TAG=false
fi

# Resolve final VERSION
if [ -n "$VERSION" ]; then
    FINAL_VERSION="$VERSION"
elif [ -n "$AUTO_VERSION" ]; then
    FINAL_VERSION="$AUTO_VERSION"
else
    FINAL_VERSION=""
fi

Version detection output:

| Scenario | Result | |----------|--------| | VERSION provided | Use provided version | | TARGET_REF is tag v2.0.0 | Auto-detect: 2.0.0 | | TARGET_REF is tag release-1.5.0 | Auto-detect: 1.5.0 | | TARGET_REF is branch/SHA | No version (omit from title) |

Step 1.6 — Commit Log Analysis

Extract context from commit messages:

# Get commit messages between refs
git log --oneline --no-merges BASE_REF...TARGET_REF

# Get detailed commit messages for context
git log --pretty=format:"%h %s%n%b" --no-merges BASE_REF...TARGET_REF

Parse commit messages for:

| Pattern | Category | Example | |---------|----------|---------| | feat:, feature: | Feature | feat: add user authentication | | fix:, bugfix: | Bug Fix | fix: resolve null pointer exception | | refactor: | Improvement | refactor: optimize database queries | | breaking:, BREAKING CHANGE: | Breaking | breaking: remove deprecated API | | perf: | Performance | perf: improve response time | | docs: | Documentation | docs: update API documentation | | chore:, build:, ci: | Infrastructure | chore: update dependencies |

Use commit messages to:

  1. Supplement diff analysis with intent/context
  2. Identify breaking changes explicitly marked
  3. Group related changes by commit scope
  4. Extract ticket/issue references (e.g., #123, JIRA-456)

Step 2 — Produce the Diff

# Stats view
git diff --find-renames --find-copies --stat BASE_REF...TARGET_REF

# Full diff
git diff --find-renames --find-copies BASE_REF...TARGET_REF

Step 3 — Build Change Inventory

From the diff, identify:

| Category | What to Look For | |----------|------------------| | Endpoints | New/changed/removed (method/path/request/response/status codes) | | DB Schema | Migrations, backfills, indexes, constraints | | Messaging | Topics, payloads, headers, idempotency, ordering | | Config/Env | New vars, changed defaults | | Auth | Permissions, roles, tokens | | Performance | Timeouts, retries, connection pools | | Dependencies | Bumps with runtime behavior impact | | Observability | Logging, metrics, tracing changes | | Operations | Scripts, cron, job schedules |

Step 4 — Write the Ops Update Guide

Use the appropriate template based on LANGUAGE parameter.

Language Templates

Template Selection

| LANGUAGE | Use Template | |----------|--------------| | en | English Template | | pt-br | Portuguese Template | | both | Generate BOTH templates as separate files |

🇺🇸 English Template (LANGUAGE=en)

Title Format (with version):

# Ops Update Guide — <repo/service> — <VERSION> — <TARGET_SHA>

Title Format (without version):

# Ops Update Guide — <repo/service> — BASE_REF → TARGET_REF — <TARGET_SHA>

Header Block:

| Field | Value |
|-------|-------|
| **Mode** | `STRICT_NO_TOUCH` or `TEMP_CLONE_FOR_FRESH_REFS` |
| **Comparison** | `BASE_REF...TARGET_REF` |
| **Base SHA** | `<BASE_SHA>` |
| **Target SHA** | `<TARGET_SHA>` |
| **Date** | YYYY-MM-DD |
| **Source** | based on git diff |

Section Format:

## <N>. <Descriptive Title> [<Category> <Emoji>]

Category Mapping (English):

| Category | Emoji | |----------|-------| | Feature | ✨ | | Bug Fix | 🐛 | | Improvement | 🆙 | | Breaking | ⚠️ | | Infrastructure | 🔧 | | Observability | 📊 | | Data | 💾 |

Section Labels (English):

  • What Changed — Bullet list with concrete changes
  • Why It Changed — Infer from code/comments/tests
  • Client Impact — Risk level: Low/Medium/High
  • Required Client Action — "None" or exact steps
  • Deploy/Upgrade Notes — Order of operations, compatibility
  • Post-Deploy Monitoring — Logs, metrics, signals
  • Rollback — Safety: Safe/Conditional/Not recommended

Uncertain Info Markers (English):

  • Mark as ASSUMPTION + HOW TO VALIDATE

🇧🇷 Portuguese Template (LANGUAGE=pt-br)

Title Format (with version):

# Guia de Atualização (Ops) — <repo/serviço> — <VERSION> — <TARGET_SHA>

Title Format (without version):

# Guia de Atualização (Ops) — <repo/serviço> — BASE_REF → TARGET_REF — <TARGET_SHA>

Header Block:

| Campo | Valor |
|-------|-------|
| **Mode** | `STRICT_NO_TOUCH` ou `TEMP_CLONE_FOR_FRESH_REFS` |
| **Comparação** | `BASE_REF...TARGET_REF` |
| **Base SHA** | `<BASE_SHA>` |
| **Target SHA** | `<TARGET_SHA>` |
| **Data** | YYYY-MM-DD |
| **Fonte** | baseado em git diff |

Section Format:

## <N>. <Título descritivo> [<Categoria> <Emoji>]

Category Mapping (Portuguese):

| Categoria | Emoji | |-----------|-------| | Funcionalidade | ✨ | | Correção | 🐛 | | Melhoria | 🆙 | | Breaking | ⚠️ | | Infra | 🔧 | | Observabilidade | 📊 | | Dados | 💾 |

Section Labels (Portuguese):

  • O que mudou — Bullet list with concrete changes
  • Por que mudou — Infer from code/comments/tests
  • Impacto para clientes — Risk level: Baixo/Médio/Alto
  • Ação necessária do cliente — "Nenhuma" or exact steps
  • Notas de deploy/upgrade — Order of operations, compatibility
  • O que monitorar pós-deploy — Logs, metrics, signals
  • Rollback — Safety: Seguro/Condicional/Não recomendado

Uncertain Info Markers (Portuguese):

  • Mark as ASSUNÇÃO + COMO VALIDAR

Section Structure (applies to both languages)

1) Contextual Narrative (REQUIRED - comes FIRST)

  • 1-3 paragraphs explaining business/operational context
  • Problem being solved or scenario that triggered change
  • Concrete examples (anonymized if needed)

2) What Changed / O que mudou

  • Bullet list with concrete changes
  • Include file:line references (e.g., pkg/mmodel/balance.go:332-335)
  • Show key code snippets if they clarify behavior

3) Why It Changed / Por que mudou

  • Infer from code/comments/tests if possible
  • If not derivable, use the appropriate uncertainty marker for the language

4) Client Impact / Impacto para clientes

  • Who/what is impacted
  • Risk level with justification
  • Expected behavior differences

5) Required Client Action / Ação necessária do cliente

  • "None"/"Nenhuma" if none
  • If yes: exact steps (API fields, headers, retries, config updates)

6) Deploy/Upgrade Notes / Notas de deploy/upgrade

  • Order of operations, compatibility concerns
  • Rolling deploy safety
  • Flags/canary recommendations

7) Post-Deploy Monitoring / O que monitorar pós-deploy

For log messages:

| Level/Nível | Message/Mensagem | Meaning/Significado |
|-------------|------------------|---------------------|
| `INFO` | `Message text` | Explanation |
| `WARN` | `Warning text` | What this indicates |

For tracing spans:

#### Tracing Span: `span.name.here`

| Scenario/Cenário | Span Status | Description |
|------------------|-------------|-------------|
| Success/Sucesso | ✅ OK | Description |
| Error/Erro | ❌ Error | Description with error details |

Include:

  • Where/Onde: Log sources, dashboards, metric names
  • Suggested threshold/Threshold sugerido: If not derivable, label as "Suggestion"/"Sugestão"
  • Success signals/Sinais de sucesso: Expected positive indicators
  • Failure signals/Sinais de falha: Warning signs

8) Rollback

  • Safety/Segurança: Safe/Conditional/Not recommended (or Portuguese equivalent)
  • Steps/Passos: Specific steps (revert image, wait for TTL, etc.)
  • Concerns/Preocupações: Data/compat concerns

Special Sections

⚠️ Attention Point / Ponto de Atenção (when applicable)

English:

### ⚠️ Attention Point

**The client may observe [specific change] after this deploy.**

This is expected because:
- [Reason 1]
- [Reason 2]

**Upside**: [Benefit]
**Required action**: [What to do]

Portuguese:

### ⚠️ Ponto de Atenção

**O cliente pode observar [mudança específica] após este deploy.**

Isso é esperado porque:
- [Razão 1]
- [Razão 2]

**Lado positivo**: [Benefício]
**Ação necessária**: [O que fazer]

Compatibility Tables (when applicable)

English:

### Backward Compatibility

✅ **100% compatible** with existing data:

| Scenario | Handling | Location |
|----------|----------|----------|
| Scenario 1 | How handled | `file:line` |

Portuguese:

### Compatibilidade retroativa

✅ **100% compatível** com dados existentes:

| Cenário | Tratamento | Local |
|---------|------------|-------|
| Cenário 1 | Como tratado | `arquivo:linha` |

Step 5 — Write Summary Section

English Summary:

## Summary

| Category | Count |
|----------|-------|
| Features ✨ | N |
| Bug Fixes 🐛 | N |
| Improvements 🆙 | N |
| Data/Migrations 💾 | N |

## Rollback Compatibility Analysis

✅/⚠️ **[Overall assessment]**

| Item | Rollback | Justification |
|------|----------|---------------|
| 1. [Item name] | ✅ Safe | [Brief reason] |
| 2. [Item name] | ⚠️ Conditional | [Brief reason] |

Portuguese Summary:

## Resumo

| Categoria | Quantidade |
|-----------|------------|
| Funcionalidades ✨ | N |
| Correções 🐛 | N |
| Melhorias 🆙 | N |
| Dados/Migrações 💾 | N |

## Análise de Compatibilidade de Rollback

✅/⚠️ **[Avaliação geral]**

| Item | Rollback | Justificativa |
|------|----------|---------------|
| 1. [Nome do item] | ✅ Seguro | [Razão breve] |
| 2. [Nome do item] | ⚠️ Condicional | [Razão breve] |

End with:

  • Schema changes
  • Incompatible serialization changes
  • Data that old version cannot read
  • Irreversible migrations

Step 6 — Preview Before Saving

MANDATORY: Show preview summary before writing to disk.

Present to user for confirmation:

## 📋 Release Guide Preview

**Configuration:**
| Setting | Value |
|---------|-------|
| Repository | <repo-name> |
| Comparison | `BASE_REF...TARGET_REF` |
| Version | <VERSION or "Not detected"> |
| Language(s) | <en/pt-br/both> |
| Mode | <STRICT_NO_TOUCH/TEMP_CLONE_FOR_FRESH_REFS> |

**Change Summary:**
| Category | Count |
|----------|-------|
| Features ✨ | N |
| Bug Fixes 🐛 | N |
| Improvements 🆙 | N |
| Breaking Changes ⚠️ | N |
| Infrastructure 🔧 | N |
| Data/Migrations 💾 | N |

**Key Changes (top 5):**
1. [Brief description of most significant change]
2. [Second most significant]
3. [Third]
4. [Fourth]
5. [Fifth]

**Output File(s):**
- `notes/releases/{filename}.md`

---
**Proceed with saving?** [Yes/No]

Wait for user confirmation before Step 7.

Step 7 — Persist Guide to Disk

File naming convention:

| Has Version? | LANGUAGE | Filename Pattern | |--------------|----------|------------------| | 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 | Generate BOTH files above |

# Output directory
OUT_DIR="notes/releases"
mkdir -p "$OUT_DIR"

# Base filename components
DATE=$(date +%Y-%m-%d)
REPO_SLUG=<repo-kebab-case>
VERSION_SLUG=<version-sanitized>  # e.g., v2.0.0 -> v2-0-0
BASE_SLUG=<base-ref-sanitized>
TARGET_SLUG=<target-ref-sanitized>

# Determine filename based on version availability
if [ -n "$FINAL_VERSION" ]; then
    BASE_FILENAME="${DATE}_${REPO_SLUG}-${VERSION_SLUG}"
else
    BASE_FILENAME="${DATE}_${REPO_SLUG}-${BASE_SLUG}-to-${TARGET_SLUG}"
fi

# Generate files based on LANGUAGE
case "$LANGUAGE" in
  en)
    FILE="$OUT_DIR/${BASE_FILENAME}.md"
    # Write English guide
    ;;
  pt-br)
    FILE="$OUT_DIR/${BASE_FILENAME}_pt-br.md"
    # Write Portuguese guide
    ;;
  both)
    FILE_EN="$OUT_DIR/${BASE_FILENAME}.md"
    FILE_PT="$OUT_DIR/${BASE_FILENAME}_pt-br.md"
    # Write BOTH guides
    ;;
esac

After saving, confirm:

  • Path(s) of saved file(s)
  • BASE_REF...TARGET_REF used
  • SHAs used
  • Version (if detected/provided)
  • Language(s) generated

Hard Rules (Content)

| Rule | Enforcement | |------|-------------| | No invented changes | Everything MUST be supported by diff | | Uncertain info | Mark as ASSUMPTION + HOW TO VALIDATE | | Operational language | Audience is Ops, not customers | | External changes | API, events, DB, auth, timeouts MUST be called out | | Preview required | MUST show preview before saving | | User confirmation | MUST wait for user approval before writing files |

Blocker Criteria

STOP and report if:

| Decision Type | Blocker Condition | Required Action | |---|---|---| | Ref resolution failure | BASE_REF or TARGET_REF cannot be resolved | STOP and report which ref failed - suggest TEMP_CLONE mode | | No git repository | Not in a git repository or .git directory missing | STOP and report - skill requires git context | | Forbidden command attempt | STRICT_NO_TOUCH mode and need to fetch/pull | STOP and ask user to switch to TEMP_CLONE mode | | No diff available | git diff returns empty or fails | STOP and verify refs exist with commits between them | | User declined preview | User rejected preview confirmation | STOP and ask for corrections or confirmation to abort |

Cannot Be Overridden

The following requirements CANNOT be waived:

  • MUST show preview before writing any files to disk
  • MUST wait for user confirmation before saving
  • CANNOT invent changes not supported by the diff
  • CANNOT use forbidden git commands in STRICT_NO_TOUCH mode
  • MUST mark uncertain information as ASSUMPTION with validation steps

Severity Calibration

| Severity | Condition | Required Action | |---|---|---| | CRITICAL | Invented change not in diff included in guide | MUST remove or mark as ASSUMPTION with validation | | CRITICAL | Guide saved without user preview confirmation | MUST re-run preview step and get confirmation | | HIGH | Breaking change missed in analysis | MUST add breaking change section with migration steps | | HIGH | Rollback analysis omitted | MUST add rollback compatibility matrix | | MEDIUM | Contextual narrative missing from sections | Should add 1-3 paragraph context before technical details | | LOW | Minor formatting inconsistencies | Fix in next iteration |

Pressure Resistance

| User Says | Your Response | |---|---| | "Skip the preview, just save the file" | "CANNOT save without preview confirmation - MUST show preview first" | | "We need this fast, summarize the big diff" | "CANNOT summarize - Ops needs ALL significant changes documented" | | "This change is internal, Ops doesn't need it" | "CANNOT decide relevance - MUST document all changes, Ops will filter" | | "Just use STRICT mode even though ref is missing" | "CANNOT fetch in STRICT mode - MUST switch to TEMP_CLONE or provide existing ref" | | "Invent a reason, the commit message is unclear" | "CANNOT invent - MUST mark as ASSUMPTION with HOW TO VALIDATE" |

Anti-Rationalization Table

| Rationalization | Why It's WRONG | Required Action | |-----------------|----------------|-----------------| | "The diff is too large, I'll summarize" | Summarizing loses critical details. Ops needs specifics. | Document ALL significant changes | | "This change is obvious, no need to explain" | Obvious to you ≠ obvious to Ops. Context is required. | Add contextual narrative | | "I'll skip the preview, user is in a hurry" | Preview prevents errors. Skipping risks wrong output. | ALWAYS show preview first | | "No breaking changes detected" | Did you check commit messages for BREAKING CHANGE? | Verify commit messages AND diff | | "Version not important for this guide" | Version helps Ops track releases. Auto-detect or ask. | Include version when available | | "Rollback analysis not needed, changes are safe" | ALL changes need rollback assessment. No exceptions. | Include rollback section | | "I'll invent a likely reason for this change" | Invented reasons mislead Ops. Mark as ASSUMPTION. | Mark uncertain info clearly | | "This file change isn't relevant to Ops" | You don't decide relevance. Document it, Ops decides. | Document ALL changes | | "Skip commit log, diff is enough" | Commit messages contain intent not visible in diff. | Analyze commit messages | | "User didn't ask for Portuguese, skip it" | Check LANGUAGE parameter. If both, generate both. | Respect LANGUAGE parameter |

Quality Checklist

Before output, self-validate:

  • [ ] Every section starts with contextual narrative
  • [ ] All log messages in table format (Level | Message | Meaning)
  • [ ] All tracing spans in table format when applicable
  • [ ] Emojis used consistently for category tags
  • [ ] Rollback analysis consolidated as matrix at end
  • [ ] No invented changes - everything traceable to diff
  • [ ] File:line references included for key code changes
  • [ ] "⚠️ Attention Point" used for confusing expected behaviors

Special Handling Rules

| Change Type | Required Info | |-------------|---------------| | DB migrations | Forward steps, rollback steps, irreversibility, compat matrix | | Breaking API/events | Explicit contract diffs + mitigation/versioning | | Feature flags | Name, default, operational toggling guidance | | Security/auth | Privilege/role changes, operational checks | | Log level changes | Document what was ERROR→INFO, etc. |

Example Invocations

With version (from tag):

User: Generate release guide from <base-tag> to <target-tag>
Assistant: [Detects tags, auto-extracts version from <target-tag>]
Assistant: [Shows preview summary]
User: Yes, proceed
Assistant: [Writes guide]
Output: notes/releases/{DATE}_{REPO}-{VERSION}.md

With explicit version:

User: Generate release guide from <base-ref> to <target-ref>, version <version>
Assistant: [Uses provided version]
Assistant: [Shows preview summary]
User: Yes, proceed
Output: notes/releases/{DATE}_{REPO}-{VERSION}.md

Without version (branch to branch):

User: Generate ops guide from <base-branch> to <target-branch>
Assistant: [No version detected]
Assistant: [Shows preview summary]
User: Yes, proceed
Output: notes/releases/{DATE}_{REPO}-{BASE}-to-{TARGET}.md

Portuguese only:

User: Generate ops guide from <base-ref> to <target-ref> in Portuguese
Assistant: [Shows preview summary]
User: Yes, proceed
Output: notes/releases/{DATE}_{REPO}-{BASE}-to-{TARGET}_pt-br.md

Both languages:

User: Generate release guide for <version> in both English and Portuguese
Assistant: [Shows preview summary]
User: Yes, proceed
Output:
  - notes/releases/{DATE}_{REPO}-{VERSION}.md (English)
  - notes/releases/{DATE}_{REPO}-{VERSION}_pt-br.md (Portuguese)

Via slash command:

User: /ring:release-guide <base-ref> <target-ref>
Assistant: [Executes skill with BASE_REF and TARGET_REF]