pr-ship

name	pr-ship
description	Pre-ship risk report for OpenClaw PRs. Dynamically explores the codebase to assess module risk, blast radius, and version-specific gotchas. Scores each finding by severity (🟢/🟡/🔴). Updated frequently with the latest OpenClaw version context — run `clawhub update pr-ship` regularly to stay current.

pr-ship

Overview

Pre-ship risk report for OpenClaw pull requests.

This skill is updated frequently to track OpenClaw releases. The version-specific context (gotchas, behavioral changes, active risk areas) is refreshed with each upstream release. Run clawhub update pr-ship periodically to get the latest context.

What it does:

• Diffs your current branch against main in the OpenClaw repository.
• Dynamically investigates each changed module using grep/find/git on the codebase itself.
• Produces a structured risk report with evidence-backed findings scored by severity (🟢/🟡/🔴).
• No approve/reject gate -- just information for you to decide what to fix before publishing.

Reference Layers

Load these files from the references/ directory. Each serves a distinct purpose:

1. STABLE-PRINCIPLES.md -- Timeless OpenClaw coding standards: testing guide, file naming, safety invariants, common pitfalls, PR practices.

2. ARCHITECTURE-MAP.md -- OpenClaw structural context: module hierarchy, risk tier definitions with calibrated thresholds, critical path patterns, cross-module coupling, change impact matrix.

3. CURRENT-CONTEXT.md (optional) -- Version-specific gotchas, recent behavioral changes, and active risk areas. If this file exists, load it. It tracks the current OpenClaw release.

4. EXPLORATION-PLAYBOOK.md -- Dynamic investigation procedures. Read-only commands (grep, find, ls, git) that discover the current state of the OpenClaw codebase.

STABLE-PRINCIPLES, ARCHITECTURE-MAP, and EXPLORATION-PLAYBOOK should always be present. CURRENT-CONTEXT is optional -- if missing, the skill still works but without version-specific gotcha awareness.

Workflow

1. Load reference layers

• Read the four reference files listed above.

2. Collect diff against main

• Get current branch: git branch --show-current
• Gather file list: git diff --name-only main...HEAD
• Gather patch content: git diff main...HEAD

3. Classify changed modules

• For each changed file, identify its src/<module>/ path.
• Look up the module's risk tier in ARCHITECTURE-MAP.md.
• If the module isn't listed or you want to verify, run the dynamic consumer count from EXPLORATION-PLAYBOOK.md "Dynamic Risk Classification" section.

4. Run dynamic exploration per changed module

• Follow EXPLORATION-PLAYBOOK.md "Blast Radius Discovery" for each changed file.
• Follow "Module-Specific Investigation Strategies" for each changed module type.
• Follow "Test Discovery" to identify relevant tests.
• Check "Red Flags Table" against the diff.

5. Evaluate findings

• Compare exploration evidence against:
  • Safety invariants and common pitfalls from STABLE-PRINCIPLES.md
  • Version-specific gotchas from CURRENT-CONTEXT.md (if loaded)
  • Architecture coupling patterns from ARCHITECTURE-MAP.md
• Every finding must include:
  • Evidence from the diff (file + snippet)
  • Exploration evidence (command output showing blast radius, consumers, or pattern match)
  • Reference to the specific principle, gotcha, or coupling pattern it relates to

6. Produce report

• Use the report format below.
• Do not output "approved/rejected".

Severity and Alert Scoring

• 🟢 Low Risk (score 1-2) Minor observation, style preference, or informational note. Safe to ship as-is.

• 🟡 Attention Needed (score 3-6) Partial mismatch, ambiguity, missing hardening, or non-blocking inconsistency. Worth reviewing but unlikely to cause breakage.

• 🔴 High Risk (score 7-10) Clear conflict with OpenClaw coding standards, architecture patterns, or version-specific constraints. Likely to cause bugs, regressions, or policy violations.

Scoring:

• Score each finding individually (1-10).
• final_alert_score = max(per_finding_scores). If no findings, final_alert_score = 0.

Report Format

## pr-ship report

- Branch: `<current-branch>`
- Base: `main`
- Files changed: `<N>`
- Modules touched: `<list with risk tiers>`
- Findings: `<N>`
- Final alert score: `<0-10>`

### Module Risk Summary

| Module | Risk Tier | Consumers | Files Changed |
| --- | --- | --- | --- |
| <module> | CRITICAL/HIGH/MEDIUM/LOW | <N> | <N> |

### Findings

1. 🟢/🟡/🔴 Title
   - Alert: `<1-10>`
   - Reference: `<principle, gotcha, or pattern from reference docs>`
   - Evidence in diff: `<file + short snippet/description>`
   - Exploration evidence: `<what dynamic investigation revealed>`
   - Why this matters: `<1-2 lines>`
   - Suggested fix: `<1-2 concrete actions>`

(repeat)

### Executive summary
- `<short practical summary for decision>`
- `<top 1-3 actions before publishing PR>`

Constraints

• This skill is for the OpenClaw repository only. Do not use it on other projects.
• Review only the current branch diff against main.
• Do not review unrelated repository history.
• Do not auto-edit code unless explicitly asked.
• Do not convert the report into an approve/reject decision unless explicitly requested.
• Exploration commands are read-only (grep, find, ls, git diff). Never execute build, test, or code generation commands -- recommend them to the user in findings instead.

Credits

Original DEVELOPER-REFERENCE.md format and approach adapted from mudrii's developer reference methodology. The dynamic exploration approach was designed based on feedback from the OpenClaw maintainer community.