mcpField
E
explain-pr

explain-pr

github.com/carlitoseDevelopment042 installsUpdated 2w ago
Repository

About explain-pr

A skill that renders a pull request body from an already validated verification bundle. It is for workflows that need evidence-linked change descriptions and validation, while keeping review, merge decisions, and provider mutations outside its scope.

Key features

  1. 01Renders required PR sections
  2. 02Includes a before-and-after Mermaid diagram
  3. 03Uses literal evidence IDs and dispositions
  4. 04Validates the rendered body
  5. 05Can update and read back the PR body when requested

Use cases

  1. 01Preparing a PR description from validated evidence
  2. 02Checking that a PR body meets its contract
  3. 03Publishing and revalidating a requested PR-body update

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/carlitose/agent-skills --skill explain-pr

After installing, type/explain-prin Claude Code to confirm it loaded.

Bundled filesagents/openai.yaml

Details

From the project README

Explain PR

Owns: PR-body rendering from an already validated bundle. It does not review code, reinterpret evidence, raise a claim ceiling, authorize merge, or decide integration.

The required sections, visibility rules, and wording ceiling come from the canonical Verification Record and its validator.

Inputs

Require:

  • PR identifier or prepared branch/base/head context;
  • normalized ticket summary;
  • frozen CandidateRef and observed provider PR head SHA;
  • validated verification bundle;
  • concise code map or diff facts.

Reject missing/stale bundles. Never turn simulated, skipped, or gated evidence into a stronger narrative.

When invoked by ticket-autopilot, also require the runner's complete render-required request. Preserve its render_request_hash and expected_head_sha literally; do not recompute or substitute either identity.

Render

Produce the headings required by the contract, including:

  • what changed and why;
  • before/after behavior;
  • code map;
  • tests and classified evidence;
  • open/failed gates and residual limits;
  • reviewer checklist;
  • exactly one before/after Mermaid diagram.

Use literal IDs and dispositions from the bundle so machines and reviewers can trace each statement. Do not add forbidden wording or infer provider capability.

Validate the rendered body with:

VERIFICATION_AUDIT_ROOT is the absolute verification-audit skill root resolved from the skill catalog, never from repository cwd.

python3 -B "$VERIFICATION_AUDIT_ROOT/scripts/verification_contract.py" \
  validate-pr <bundle.json> <body.md> --pr-head-sha <observed-sha>

If validation fails, fix rendering only. A semantic bundle problem goes back to verification-audit; a changed head requires fresh upstream evidence.

When the user or scheduler requested publication, update only the PR body through the selected provider adapter, read it back, and revalidate the observed body/head. Return the body, validation result, provider observation, and any publication error. Never merge.

For the runner handoff, return render_request_hash, expected_head_sha, rendered_body, the same validated verification_bundle, and the absolute verification_audit_root. The runner, not this skill, persists content-addressed artifacts, performs provider mutation/readback, and decides whether pr-open is reachable.

Comments

Markdown supported