From ring-default
Generates internal Ops update/migration guides from git diff analysis between refs. Auto-detects tags, analyzes commits for features, fixes, breaking changes; supports multi-language.
npx claudepluginhub lerianstudio/ring --plugin ring-defaultThis skill uses the workspace's default tool permissions.
> **⚠️ CANDIDATE FOR MODULARIZATION**: This skill file exceeds 700 lines and is a candidate for splitting into sub-skills. Future work MUST consider:
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
⚠️ CANDIDATE FOR MODULARIZATION: This skill file exceeds 700 lines and is a candidate for splitting into sub-skills. Future work MUST consider:
- Template extraction: Move language-specific templates (EN, PT-BR) to separate template files
- Section generators: Split each guide section (Breaking Changes, Configuration, Database, etc.) into separate template modules
- Git analysis separation: Extract git diff/commit analysis logic from documentation generation
- Output formatters: Separate markdown generation from content analysis
MUST NOT add new sections or languages without first implementing modularization to prevent further bloat.
You are a code-aware documentation agent. Produce an internal Operations-facing update/migration guide.
| 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) onlyboth — Generate two files, one in each languageVersion handling:
VERSION provided → Use it directlyTARGET_REF is a tag → Auto-extract version from tag nameComparison range: Always use triple-dot BASE_REF...TARGET_REF
Hard requirement: Do NOT alter anything in the current local repo.
FORBIDDEN commands:
git fetch, git pull, git pushgit checkout, git switch, git reset, git cleangit commit, git merge, git rebase, git cherry-pickgit worktree, git gc, git repack, git prune.git/ filesALLOWED commands (read-only):
git rev-parse, git diff, git show, git log, git remote get-urlIf ref does not exist locally: STOP and report:
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"
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.
# 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:
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) |
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:
#123, JIRA-456)# 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
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 |
Use the appropriate template based on LANGUAGE parameter.
| LANGUAGE | Use Template |
|---|---|
en | English Template |
pt-br | Portuguese Template |
both | Generate BOTH templates as separate files |
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):
Uncertain Info Markers (English):
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):
Uncertain Info Markers (Portuguese):
1) Contextual Narrative (REQUIRED - comes FIRST)
2) What Changed / O que mudou
file:line references (e.g., pkg/mmodel/balance.go:332-335)3) Why It Changed / Por que mudou
4) Client Impact / Impacto para clientes
5) Required Client Action / Ação necessária do cliente
6) Deploy/Upgrade Notes / Notas de deploy/upgrade
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:
8) Rollback
⚠️ 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` |
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:
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.
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:
BASE_REF...TARGET_REF used| 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 |
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 |
The following requirements CANNOT be waived:
| 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 |
| 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" |
| 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 |
Before output, self-validate:
| 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. |
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 skill invocation:
User: Use ring:release-guide with <base-ref> <target-ref>
Assistant: [Executes skill with BASE_REF and TARGET_REF]