publish-pr

name	publish-pr
description	Create or update the implementation, docs, or governance PR after local changes are ready.

Publish PR

Use this skill when local work is complete enough to publish as a branch and pull request.

Goal: turn validated local changes into a truthful branch, commit, pushed head, and PR artifact without mixing publication with implementation logic.

⚠️ CRITICAL: All publication steps (branch creation, staging, commit, push, PR creation) must be executed using explicit git/gh commands. Do not describe these steps—execute them and verify they succeeded. Treat pr-integration as a conditional readiness/repair path, not an automatic immediate handoff.

Canonical workflow position

Docs -> Issue -> Project -> Issue maintenance -> Agent -> Publish PR -> PR integration -> CI -> Verification -> Project/doc closure -> Owner Doc

Entry conditions

• Local changes are already implemented.
• Focused validation has already been run and captured.
• The correct lane is already known:
  • implementation
  • docs authoring
  • governance

Responsibilities

• create or switch to the correct branch
• stage only the intended files
• create an intentional commit
• push the branch
• open or update the PR
• apply the correct PR template lane and linked-Issue metadata

Core rules

• Do not expand implementation scope during publication.
• Do not publish unrelated local changes.
• For implementation lane PRs, the body must include Fixes #<id>, Closes #<id>, or Resolves #<id>.
• For docs-authoring or governance lane PRs, leave the linked Issue blank unless a governing Issue actually exists.
• Default to opening an open PR.
• Use --draft only with an explicit reason that the PR is not yet ready for review or still needs integration/repair.
• Publication does not move work to Done.

Publication workflow (all steps are executable)

Step 1: Confirm File Set

Verify files belong to a single lane and single bounded change:

git status --porcelain

All modified/new files must align with a single lane (implementation, docs-authoring, or governance).

Step 2: Create or Switch Branch

# Option A: Create new branch from main
git fetch origin main
git checkout -b <branch-name> origin/main

# OR Option B: Switch to existing branch
git checkout <branch-name>

# Verify correct branch
git status

Branch naming: Descriptive, hyphenated (e.g., fix-auth-token-expiry, docs-roadmap-update, governance-skill-updates).

Step 3: Stage Intended Files

# Stage specific files (not all changes)
git add <file1> <file2> <file3>

# Verify staging
git status

Do not use git add -A or git add .—stage only intended files.

Step 4: Create Commit

git commit -m "$(cat <<'EOF'
Brief summary of bounded outcome

Optional detailed explanation of why this change is needed.

Co-Authored-By: Claude Haiku 4.5 <[e-mail]>
EOF
)"

Commit message must:

• Start with imperative verb (Fix, Add, Update, Rebuild, etc.)
• Summarize the bounded outcome, not the mechanical changes
• Be truthful about scope

Step 5: Push Branch

git push origin <branch-name>

Verify push succeeded and GitHub suggests PR creation.

Step 6: Create or Update PR

Execute based on lane classification:

Implementation Lane (Fixes an Issue):

gh pr create \
  --title "<bounded outcome>" \
  --body "$(cat <<'EOF'
Fixes #<ISSUE_NUMBER>

## Summary
<1-2 sentence summary of the bounded change>

## Validation
<What validation actually ran>

---
EOF
)"

Docs Authoring Lane:

gh pr create \
  --title "<docs update title>" \
  --body "$(cat <<'EOF'
- [x] Docs authoring lane

## Summary
<Summary of documentation changes>

## Changes
<What surfaces were updated>

## Validation
<Docs validation that ran>

---
EOF
)"

Governance Lane:

gh pr create \
  --title "<governance change title>" \
  --body "$(cat <<'EOF'
- [x] Governance lane

## Summary
<Summary of governance/workflow change>

## Changes
<What surfaces were updated>

## Validation
<Governance validation that ran>

---
EOF
)"

Update Existing PR:

gh pr edit <pr-number> --body "$(cat <<'EOF'
... updated body content ...
EOF
)"

Pre-push PR-body contract gate:

• Before gh pr create or gh pr edit, verify the body includes exactly one lane classifier:
  • implementation lane: Fixes #<id> or Closes #<id> or Resolves #<id>
  • docs lane: - [x] Docs authoring lane
  • governance lane: - [x] Governance lane
• If none is present, stop and repair the PR body before publication.

Step 7: Hand Off to pr-integration

After PR is created/updated, use pr-integration only when the PR still needs readiness/repair work before verification:

# Invoke pr-integration skill to verify, check CI, and prepare for verification
echo "Handing off to pr-integration skill"

Do not force this as an immediate publication step. PR integration resolves merge conflicts, verifies CI, and prepares the PR for verification/merge when the PR needs that readiness path.

PR body requirements

Implementation lane:

• include Fixes #<id>
• summarize the bounded change
• state focused validation that actually ran

Docs authoring lane:

• mark Docs authoring lane
• confirm the change stays within approved docs surfaces

Governance lane:

• mark Governance lane
• confirm the change stays within approved governance surfaces

Capturing learning

Capturing learning: if during this work you notice a divergence from plan — you did something you did not expect to do, or discovered an earlier artifact was wrong — invoke capture-learning before continuing. Do not batch to end of task; context is freshest now. Only log if you can name an upstream artifact that could absorb the fix.

Output format

1. Publication Inputs
2. Branch and Commit Created
3. PR Created or Updated
4. Handoff Target