# Review Promotion

> >

- **Type:** Skill
- **Install:** `agentstack add skill-talont-org-autoskillit-review-promotion`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TalonT-Org](https://agentstack.voostack.com/s/talont-org)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TalonT-Org](https://github.com/TalonT-Org)
- **Source:** https://github.com/TalonT-Org/AutoSkillit/tree/main/.claude/skills/review-promotion

## Install

```sh
agentstack add skill-talont-org-autoskillit-review-promotion
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 = ` as a structured token (absolute path, prepend CWD)
- Output `verdict = ` 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

```bash
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)

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```json
{
  "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:
```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:
```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:
```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:
```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:
```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

```bash
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):

```markdown
# 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}

---
Generated with Claude Code via AutoSkillit | review-promotion
```

### Phase 5: Post to PR (only if --post-to-pr AND pr_number found)

```bash
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}
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TalonT-Org](https://github.com/TalonT-Org)
- **Source:** [TalonT-Org/AutoSkillit](https://github.com/TalonT-Org/AutoSkillit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-talont-org-autoskillit-review-promotion
- Seller: https://agentstack.voostack.com/s/talont-org
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.