review-promotion
Skill5 starsChanged 6 months agoMITView on GitHub
Reviewer-facing deep analysis of an integration-to-main promotion. Performs domain risk scoring, breaking change audit, regression risk assessment, test coverage delta, and cross-domain dependency analysis. Use when you want a reviewer's guide before approving a promotion PR.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- audit-archSkill
- audit-bugsSkill
- audit-cohesionSkill
- audit-defense-standardsSkill
- audit-testsSkill
- chart-courseSkill
- check-bearingSkill
- design-guardsSkill
- elaborate-phaseSkill
- id-slopSkill
- make-arch-diagSkill
- make-reqSkill
- make-scenariosSkill
- promote-to-mainSkill
- render-recipeSkill
- update-architectureSkill
- update-reqsSkill
- update-specsSkill
- validate-auditSkill
- verify-diagSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 9 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Before approving a promotion PR
- Distinctive: line 31
When you need a structured risk assessment across all changed domains
- Distinctive: line 32
When you want an automated reviewer's guide with a go/no-go verdict
- Very specific: line 37
Create files outside .autoskillit/temp/review-promotion/
- Very specific: line 39
Use gh pr comment --body inline — always use --body-file
- Distinctive: line 68
If the git merge-base or git diff command exits non-zero (e.g., unknown branch name), emit a clear error and exit 1:
- Very specific: line 76
If changed_files is empty after a successful git diff, emit:
- Distinctive: line 147
Commit one-liners for the domain
- Distinctive: line 170
Do recipe schema changes require corresponding server tool updates?
- Distinctive: line 171
Do core type changes propagate correctly to all consumers?
- Distinctive: line 173
Do skill changes reflect new tools/features added in other domains?
- Distinctive: line 400
Always emit these structured output tokens as the final lines:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review Promotion
Perform deep reviewer-facing analysis of an integration-to-main promotion. This skill partitions all changed files by domain, runs parallel domain risk analysis, assesses test coverage and breaking changes, synthesizes a reviewer verdict, and optionally posts the review report as a PR comment.
Arguments
/autoskillit:review-promotion [batch_branch] [base_branch] [--post-to-pr]batch_branch(optional) — source branch to analyze. Defaults todevelop.base_branch(optional) — target branch. Defaults tomain.--post-to-pr— if present, post the review report as a comment on the open promotion PR.
When to Use
- Before approving a promotion PR
- When you need a structured risk assessment across all changed domains
- When you want an automated reviewer's guide with a go/no-go verdict
Critical Constraints
NEVER:
- Create files outside
.autoskillit/temp/review-promotion/ - Modify any source code — this skill is read-only analysis
- Use
gh pr comment --bodyinline — always use--body-file - Fail silently if
ghis unavailable when--post-to-pr— outputverdict = review_readyand exit 0
ALWAYS:
- Output
report_path = <absolute path>as a structured token (absolute path, prepend CWD) - Output
verdict = <value>as a structured token
Workflow
Phase 0: Setup
Step 0.1: Parse Arguments
Parse optional positional arguments and flags:
batch_branch— default"develop"if absent or emptybase_branch— default"main"if absent or emptypost_to_pr—trueif--post-to-prpresent in ARGUMENTS
Step 0.2: Compute Divergence Point
git merge-base {base_branch} {batch_branch}
git diff --name-only {base_branch}..{batch_branch}
git diff --name-only --diff-filter=A {base_branch}..{batch_branch}
git diff --name-only --diff-filter=M {base_branch}..{batch_branch}Store as merge_base_sha, changed_files, new_files (added files), and
modified_files (modified files).
If the git merge-base or git diff command exits non-zero (e.g., unknown branch name),
emit a clear error and exit 1:
Error: could not compute divergence point between '{base_branch}' and '{batch_branch}'.
Check that both branches exist locally or are fetchable.If changed_files is empty after a successful git diff, emit:
Error: no changed files found between '{base_branch}' and '{batch_branch}'.
Verify the branches are not identical and that the correct branch names were supplied.Then exit 1.
Step 0.3: Find PR (only if --post-to-pr)
gh pr list --base {base_branch} --head {batch_branch} --state open --json number,url --limit 1Store pr_number and pr_url. If none found, warn and continue — the review report will
still be written.
Phase 1: Domain Analysis
Step 1.1: Partition Files by Domain
python3 -c "
from autoskillit.execution.pr_analysis import partition_files_by_domain
import json, sys
files = json.loads(sys.argv[1])
result = partition_files_by_domain(files)
print(json.dumps(result))
" '{changed_files_as_json_array}'Store as domain_partitions. Skip if changed_files is empty.
Step 1.2: Fetch Domain Diffs (parallel)
For each domain D in domain_partitions with a non-empty file list, run in parallel:
git diff {base_branch}..{batch_branch} -- {space-separated files in domain D}Truncate diffs exceeding 12,000 characters. Drop domains with empty diffs.
Step 1.3: Fetch Domain Commits (parallel)
For each domain in domain_diffs, run in parallel:
git log {base_branch}..{batch_branch} --oneline -- {space-separated files in domain D}Step 1.4: Identify PRs per Domain
For each domain, cross-reference the PR list. For each PR, fetch its files if needed:
gh pr view {number} --json files -q '.files[].path' 2>/dev/nullStore as domain_pr_numbers.
Step 1.5: Parallel Domain Analysis Subagents
For each domain D in domain_diffs, spawn a Task subagent (model: sonnet) in a
single parallel message.
Each subagent receives:
- Domain name and file list
- Diff content (truncated to 12k chars)
- PR numbers and titles touching this domain
- Commit one-liners for the domain
Each subagent returns ONLY a JSON object:
{
"domain": "Server/MCP Tools",
"summary": "3-5 sentence description of what changed and why it matters",
"key_changes": ["concise change 1", "concise change 2"],
"breaking_changes": ["description of breaking change, or empty array"],
"risk_score": "low|medium|high",
"risk_rationale": "Why this risk level — what could go wrong",
"review_guidance": "What a reviewer should focus on when reviewing this domain",
"pr_numbers": [491, 493],
"commit_count": 5
}Step 1.6: Cross-Domain Dependency Analysis
Spawn one Task subagent (model: sonnet) with ALL domain summaries from Step 1.5.
Analyze cross-domain dependencies:
- Do recipe schema changes require corresponding server tool updates?
- Do core type changes propagate correctly to all consumers?
- Are test changes aligned with source changes in the same domain?
- Do skill changes reflect new tools/features added in other domains?
Return JSON:
{
"cross_domain_risks": ["Recipe schema added field X but server tools don't validate it"],
"alignment_notes": ["Tests cover all new server tools"],
"integration_confidence": "high|medium|low"
}Phase 2: Quality Assessment (parallel subagents)
Spawn three parallel Task subagents (model: sonnet).
Subagent 2A: Test Coverage Delta
Analyze:
- Count test files added, modified, and deleted
- For each new source file in
new_files, check if a corresponding test file exists innew_filesormodified_files(using the project'stests/mirror convention) - Identify source files with significant changes but no test coverage
- Compute a test-to-source ratio for new files
Return JSON:
{
"test_files_added": 5,
"test_files_modified": 12,
"test_files_deleted": 0,
"source_files_without_tests": ["src/autoskillit/new_module.py"],
"test_ratio": "17 test files for 23 source files",
"coverage_assessment": "Good — most new modules have corresponding tests"
}Subagent 2B: Breaking Change Audit
Receive the full diff content for each domain and the PR list.
Scan for:
- Removed public functions or classes (check
git diff --diff-filter=Mfor deleteddefandclasslines in non-test files) - Changed function signatures (parameter additions/removals/renames)
- Modified Protocol or ABC definitions (interface contracts)
- Changed config keys in
defaults.yaml - Removed or renamed MCP tools
- Changed recipe schema fields
- Modified hook registrations
For each finding, assess severity and affected downstream consumers.
Return JSON:
{
"breaking_changes": [
{
"description": "Removed function X from module Y",
"file": "src/autoskillit/core/types.py",
"severity": "high|medium|low",
"affected_domains": ["Server/MCP Tools", "Pipeline/Execution"],
"pr_number": 485
}
],
"total": 2,
"assessment": "Two medium-severity signature changes, both internal"
}Subagent 2C: Regression Risk Assessment
Receive the domain summaries from Phase 1.
Analyze:
- Conflict hotspots — files modified by multiple PRs (cross-reference PR file lists)
- Rectify chains — commits that fix issues introduced by earlier commits in this same batch (pattern: PR #N introduces something, PR #M rectifies it)
- High-risk domains — domains scored "high" risk in Step 1.5
- Churn indicators — files with unusually high insertion+deletion counts relative to their size
Return JSON:
{
"hotspot_files": [{"file": "src/autoskillit/server/tools_execution.py", "touched_by_prs": [491, 493, 495]}],
"rectify_chains": [{"original_pr": 465, "rectify_pr": 484, "description": "Structured output fix then hardening"}],
"high_risk_domains": ["Pipeline/Execution"],
"churn_indicators": [],
"overall_risk": "medium",
"risk_narrative": "Most risk concentrated in pipeline execution changes with multiple overlapping rectify commits"
}Phase 3: Review Summary Synthesis
Spawn one Task subagent (model: sonnet) with ALL results from Phases 1–2.
The subagent synthesizes a reviewer-focused verdict based on:
- Domain risk scores from Phase 1
- Quality assessment results from Phase 2
Verdict rules:
blocking_issues— any breaking_change withseverity: high, oroverall_risk == "high"needs_attention— any domain withrisk_score: medium, ortotalbreaking changes > 0review_ready— all domains low risk, no breaking changes, regression risk low
Return JSON:
{
"verdict": "review_ready|needs_attention|blocking_issues",
"verdict_rationale": "1-2 sentence explanation",
"priority_review_areas": [
{"area": "Domain name", "risk": "high|medium", "focus": "What reviewer should check"}
],
"review_checklist": [
"Verify X before approving",
"Confirm breaking change Y is intentional"
],
"blocking_items": ["Must-fix before merge, if any"]
}Phase 4: Write Review Report
mkdir -p .autoskillit/temp/review-promotionWrite to .autoskillit/temp/review-promotion/review_report_{YYYY-MM-DD_HHMMSS}.md
(relative to the current working directory):
# Promotion Review: {batch_branch} → {base_branch}
## Verdict: {verdict}
{verdict_rationale}
## Priority Review Areas
{For each item in priority_review_areas:}
### {area} (Risk: {risk})
**Focus:** {focus}
## Review Checklist
{For each item in review_checklist:}
- [ ] {item}
{If blocking_items is non-empty:}
## Blocking Items
{For each item in blocking_items:}
- **BLOCKING:** {item}
## Domain Analysis
{For each entry in domain_summaries ordered by risk_score desc:}
### {domain} (Risk: {risk_score})
{summary}
**Review focus:** {review_guidance}
**Key changes:**
{key_changes bullet list}
{If breaking_changes non-empty:}
**Breaking changes:**
{breaking_changes bullet list}
**Contributing PRs:** {comma-separated links}
{If cross_domain_risks non-empty:}
### Cross-Domain Dependencies
{For each risk:}
- {risk}
**Integration confidence:** {integration_confidence}
## Quality Assessment
### Test Coverage
{coverage_assessment}
{If source_files_without_tests non-empty:}
**Source files without test coverage:**
{bullet list}
### Breaking Changes
{If total > 0:}
| Description | File | Severity | Affected Domains |
|---|---|---|---|
{rows}
{If total == 0:}
No breaking changes detected.
### Regression Risk
**Overall:** {overall_risk}
{risk_narrative}
{If hotspot_files non-empty:}
**Conflict hotspots:**
{bullet list}
{If rectify_chains non-empty:}
**Rectify chains:**
{bullet list}
---
<sub>Generated with Claude Code via AutoSkillit | review-promotion</sub>Phase 5: Post to PR (only if --post-to-pr AND pr_number found)
gh pr comment {pr_number} --body-file .autoskillit/temp/review-promotion/review_report_{timestamp}.mdContinue if this fails — graceful degradation. Log the failure.
Output
Always emit these structured output tokens as the final lines:
report_path = {absolute path to .autoskillit/temp/review-promotion/review_report_{timestamp}.md}
verdict = {review_ready|needs_attention|blocking_issues}Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

