agentleFS
TalonT-OrgTalonT-Org/AutoSkillit/.claude/skills/review-promotion/SKILL.md

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.

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
  1. Distinctive:

    Before approving a promotion PR

    line 30
  2. Distinctive:

    When you need a structured risk assessment across all changed domains

    line 31
  3. Distinctive:

    When you want an automated reviewer's guide with a go/no-go verdict

    line 32
  4. Very specific:

    Create files outside .autoskillit/temp/review-promotion/

    line 37
  5. Very specific:

    Use gh pr comment --body inline — always use --body-file

    line 39
  6. Distinctive:

    If the git merge-base or git diff command exits non-zero (e.g., unknown branch name), emit a clear error and exit 1:

    line 68
  7. Very specific:

    If changed_files is empty after a successful git diff, emit:

    line 76
  8. Distinctive:

    Commit one-liners for the domain

    line 147
  9. Distinctive:

    Do recipe schema changes require corresponding server tool updates?

    line 170
  10. Distinctive:

    Do core type changes propagate correctly to all consumers?

    line 171
  11. Distinctive:

    Do skill changes reflect new tools/features added in other domains?

    line 173
  12. Distinctive:

    Always emit these structured output tokens as the final lines:

    line 400

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 to develop.
  • base_branch (optional) — target branch. Defaults to main.
  • --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 --body inline — always use --body-file
  • Fail silently if gh is unavailable when --post-to-pr — output verdict = review_ready and 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 empty
  • base_branch — default "main" if absent or empty
  • post_to_pr — true if --post-to-pr present 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 1

Store 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/null

Store 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:

  1. Count test files added, modified, and deleted
  2. For each new source file in new_files, check if a corresponding test file exists in new_files or modified_files (using the project's tests/ mirror convention)
  3. Identify source files with significant changes but no test coverage
  4. 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:

  1. Removed public functions or classes (check git diff --diff-filter=M for deleted def and class lines in non-test files)
  2. Changed function signatures (parameter additions/removals/renames)
  3. Modified Protocol or ABC definitions (interface contracts)
  4. Changed config keys in defaults.yaml
  5. Removed or renamed MCP tools
  6. Changed recipe schema fields
  7. 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:

  1. Conflict hotspots — files modified by multiple PRs (cross-reference PR file lists)
  2. Rectify chains — commits that fix issues introduced by earlier commits in this same batch (pattern: PR #N introduces something, PR #M rectifies it)
  3. High-risk domains — domains scored "high" risk in Step 1.5
  4. 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 with severity: high, or overall_risk == "high"
  • needs_attention — any domain with risk_score: medium, or total breaking changes > 0
  • review_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-promotion

Write 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}.md

Continue 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}

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.