Non-negotiable rules:

1. Verify the branch is a feature branch and actually has commits relative to base.
2. Compute metrics from git data, never by estimation.
3. Form the verdict only after the full metric and self-review pass is complete.
4. Stay read-only with respect to code and git state; the only allowed write is the JSON snapshot.
5. Keep the heavy metric tables, scan patterns, and JSON schema in references, not inline in every invocation.

PR Retro

Inputs

• $request: Optional flags or guidance such as --quick or --base <branch>

Goal

Produce a credible branch retrospective that:

• measures the actual branch diff
• identifies contributors and hotspots
• scans for common pre-PR artifacts
• evaluates merge readiness with explicit signals
• optionally saves a JSON snapshot under .history/pr-retros/

Step 0: Resolve mode and branch scope

Determine:

• whether the request is standard mode or --quick
• whether a custom base branch was specified
• current branch name
• whether the branch is a feature branch
• whether commits exist relative to base

Stop early if:

• on main, master, or develop
• no commits exist relative to base

Use references/retro-metrics.md for base-branch resolution rules and mode behavior.

Success criteria: The retro mode and review base are explicit, and there is real branch data to analyze.

Step 1: Gather raw branch data

Collect the raw git data needed for the retro:

• commit list with author and timestamps
• per-commit stats
• machine-readable numstat
• aggregate diff stat
• branch divergence info

Rules:

• prefer raw git output over prose or inference
• if a metric cannot be derived from the collected data, say so explicitly
• do not skip this step and jump directly to a verdict

Success criteria: All downstream metrics can be derived from collected branch data.

Step 2: Compute branch metrics

Compute the core branch metrics from raw data:

• total commits
• contributors
• files changed
• insertions
• deletions
• net LOC
• test LOC ratio
• PR size class
• branch age
• base drift
• focus score
• session count and timeline

If in --quick mode, stop after computing the dashboard-grade metrics and verdict inputs.

Load references/retro-metrics.md for:

• metric formulas
• PR size buckets
• focus score rules
• session detection rules

Success criteria: Every displayed metric is derived from concrete git data.

Step 3: Analyze contributors, hotspots, and hygiene

Build the branch-health view:

• contributor breakdown
• commit type distribution
• hotspot files
• hygiene signals such as WIP/fixup or weak commit messages

Rules:

• attribute commits per author from commit data, not local git config
• treat conventional-commit compliance as a metric, not a moral judgment
• use hotspot analysis to explain risk concentration, not to imply a bug by itself

Success criteria: The retro explains who changed what and where the branch is concentrated.

Step 4: Run the self-review scan

Use references/retro-metrics.md to scan the branch diff for:

• hardcoded secrets
• .only test markers
• conflict markers
• debug statements
• TODO or FIXME artifacts
• commented-out code
• large file additions
• binary files
• notable config changes

Rules:

• never include actual secret values in output
• distinguish between BLOCK, WARN, and INFO
• this is not a full security audit; use it as merge-readiness evidence

Success criteria: The retro captures branch hygiene issues that affect merge readiness.

Step 5: Determine merge-readiness verdict

Evaluate the configured signals:

• hygiene
• size
• test ratio
• focus
• self-review findings
• drift

Then produce:

• GREEN
• YELLOW
• RED

Generate recommendations for every non-green signal.

Load references/retro-metrics.md for the verdict rules and signal thresholds.

Success criteria: The verdict follows the documented signal rules and is explainable from the metrics.

Step 6: Render output and save snapshot

Always render the dashboard summary.

In standard mode, also render:

• contributors
• commit type breakdown
• hotspots
• self-review findings
• time distribution
• recommendations

In standard mode, save the JSON snapshot to:

• .history/pr-retros/<branch-slug>.json

Skip the snapshot in --quick mode.

Use references/retro-metrics.md for:

• output sections
• JSON schema
• branch slugging rules

Success criteria: The retro output is internally consistent, and the snapshot is written only when appropriate.

Guardrails

• Do not fabricate metrics.
• Do not change code or git state.
• Do not add disable-model-invocation; this skill should remain callable when the user asks for branch analysis.
• Do not add paths:; this is a generic workflow skill.
• Do not keep the metric tables, signal thresholds, and JSON schema inline in SKILL.md.
• Do not report a GREEN verdict when blocking findings exist.

When To Load References

• references/retro-metrics.md Use for metric formulas, signal thresholds, self-review scan patterns, output layout, and JSON snapshot schema.

Output Contract

Report:

1. branch and base
2. key dashboard metrics
3. overall verdict and per-signal status
4. notable findings and recommendations
5. snapshot path when written, or explicit quick-mode skip