What is close-progress-pr?

This Claude skill automates the end-to-end lifecycle of closing a GitHub Pull Request while maintaining rigorous documentation standards. It solves the problem of fragmented project tracking by automatically archiving progress files, updating README indexes, and patching PR links to ensure they remain functional after branch deletion, effectively bridging the gap between code merging and project status reporting.

When should I use close-progress-pr?

close-progress-pr is useful in the following scenarios: • Finalizing feature development by automatically moving progress logs from active to archived status and updating the project's central README. • Ensuring documentation link integrity by repointing PR body links to the base branch (e.g., main) so that references don't break when the head branch is deleted post-merge. • Maintaining traceability between planning and execution by automatically linking implementation PRs back to their original planning documents or PRs. • Streamlining repository maintenance by combining git merge operations with automated documentation cleanup in a single, error-proof workflow.

name	close-progress-pr
description	"Finalize and archive a progress file for a GitHub PR: locate the related docs/progress file (prefer PR body Progress link), set Status to DONE, move it to docs/progress/archived/, update docs/progress/README.md, merge the PR with gh, patch the PR body Progress link to point to the base branch so it survives branch deletion, and (when present) patch the planning PR body to include an Implementation PR link. Use when a feature PR is ready to be closed and its progress tracking should be marked DONE."

Close Progress PR

Contract

Prereqs:

Run inside the target git repo with a clean working tree.
git and gh available on PATH, and gh auth status succeeds.
Target PR has a ## Progress link in its body (preferred) or the progress file contains the PR URL.

Inputs:

PR number (or current-branch PR).
Progress file under docs/progress/ referenced by the PR.

Outputs:

Progress file finalized (Status: DONE), moved to docs/progress/archived/, and indexed in docs/progress/README.md.
PR merged (default merge commit) and branch deleted.
PR body ## Progress link patched to point to base branch (survives branch deletion).

Exit codes:

0: success
non-zero: missing progress link/file, validation failures, or git/gh command failures

Failure modes:

Unchecked checklist items missing Reason: (fail-fast).
Progress file cannot be located or moved (path mismatch, conflicts).
PR merge blocked (draft/checks failing/permissions).

Setup

Ensure gh auth status succeeds.
Load local helper commands (optional): source $AGENT_KIT_HOME/scripts/kit-tools.sh

Key rule: Progress links must survive branch deletion

After merge, GitHub often deletes the head branch. Any PR body link like:

https://github.com/<owner>/<repo>/blob/<head-branch>/docs/progress/...

will break.

Patch the PR body ## Progress link to point to the base branch (usually main) after merge:

https://github.com/<owner>/<repo>/blob/<base-branch>/docs/progress/archived/<file>.md

Key rule: Planning PRs should link to the implementation PR

If the progress file includes a Links -> Planning PR entry, ensure that planning PR body includes an ## Implementation section linking to the implementation PR (this PR).

Workflow

Identify the PR number
- Prefer current branch PR: gh pr view --json number -q .number
Preflight
- Ensure working tree is clean: git status --porcelain=v1 should be empty
- Ensure checks pass (optional but recommended): gh pr checks <pr>
- If PR body includes Open Questions and/or Next Steps and they are not already - None, update them to the latest status before merge (resolve questions or confirm with the user, check off completed steps, link follow-ups).
Locate the progress file
- Prefer parsing the PR body ## Progress link and extracting docs/progress/...
- If missing, fallback: search by PR URL inside docs/progress/:
  - pr_url="$(gh pr view <pr> --json url -q .url)"
  - rg -n --fixed-string "$pr_url" docs/progress -S
Finalize progress
- Update the progress file:
  - Fail-fast if any unchecked checklist item under ## Steps (Checklist) lacks a Reason: (excluding Step 4 “Release / wrap-up”)
  - For intentionally deferred / not-do items (Steps 0–3), prefer marking the item text with Markdown strikethrough (~~like this~~) while keeping the checkbox unchecked, and include an explicit Reason:
  - Set Status to DONE
  - Update the Updated date to today
  - Set Links -> PR to the PR URL
  - Ensure Links -> Docs and Links -> Glossary are Markdown links (not backticks) that resolve to existing files
  - If there are no related docs for this PR, set Links -> Docs to None (do not guess a random file)
- Move it to docs/progress/archived/<file>.md if not already archived
- Update docs/progress/README.md (move row to Archived; keep Archived sorted newest-first by Date; set PR link to [#<number>](<url>); best-effort if table format differs)
Commit and push these changes to the PR branch
Merge and delete branch
- Default merge method: merge commit
- gh pr merge <pr> --merge --delete-branch
Post-merge: patch PR body links to base branch
- Get base branch: gh pr view <pr> --json baseRefName -q .baseRefName
- Update ## Progress to:
  - https://github.com/<owner>/<repo>/blob/<baseRefName>/docs/progress/archived/<file>.md
Post-merge: patch planning PR (when present)
- Extract planning PR from the progress file Links -> Planning PR
- Ensure the planning PR body contains:
  - ## Implementation
    - - [PR #<feature_pr_number>: <feature_pr_title>](<feature_pr_url>)

Optional helper script

Use scripts/close_progress_pr.sh in this skill folder to run a deterministic version of steps 3–8.
If scripts/close_progress_pr.sh fails, attempt to fix the underlying cause (prefer fixing the script when it's a script bug, otherwise fix the documented prerequisites/workflow), re-run it, and explicitly report whether the fix succeeded.

close-progress-pr

When & Why to Use This Skill

Use Cases