Prompt file imported from harshanandak/Zwapit (.github/prompts/premerge.prompt.md). Copyright stays with the author.

Prepare the pull request for merge by completing ALL documentation updates on the feature branch, then hand off to the user.

Premerge

Name: premerge
Author: harshanandak

The actual merge is always done by the user in the GitHub UI — never by this command.

This command makes the PR 100% complete: code + tests + docs in one unit. After this, the user merges once and there are no follow-up doc PRs needed.

Usage

/premerge <pr-number>

What This Command Does

Step 1: Verify All CI Checks Pass

gh pr checks <pr-number>

All checks must be green before proceeding. If any fail, run /review <pr-number> first.

Step 2: Warn If Branch Is Behind Master

gh pr view <pr-number> --json baseRefName,headRefName
git fetch origin master
git status

If the feature branch is behind master, tell the user to rebase first:

⚠️  Branch is behind master — rebase before updating docs to avoid conflicts:
    git rebase origin/master
    git push --force-with-lease

Step 3: Update ALL Relevant Documentation (on feature branch)

Check each of the following and update if the feature affects it. Be selective — only update what genuinely changed.

A. CHANGELOG.md (always):

Add entry under ## [Unreleased] heading (create heading if not present)
Use Keep a Changelog categories:
- Added: New features
- Changed: Changes to existing functionality
- Fixed: Bug fixes
- Removed: Removed features
Include: feature name, PR number, Beads ID

Example:

## [Unreleased]

### Added
- Authentication refresh tokens (PR #89, forge-a3f8)

B. README.md (if user-facing changes):

Features list, configuration options, usage examples

C. docs/reference/API_REFERENCE.md (if API changes):

New endpoints, request/response schemas, authentication

D. Architecture docs (if structural changes):

docs/architecture/ diagrams, decision records (ADRs)

E. CLAUDE.md — USER section only (if project conventions changed):

<!-- USER:START - Add project-specific learnings here as you work -->
...update only between these markers...
<!-- USER:END -->

⚠️ NEVER touch other managed blocks (e.g., ).

F. AGENTS.md (if agent config, skills, or cross-agent workflow changed):

Update relevant sections describing agent capabilities or workflow

Commit doc updates to feature branch:

git add CHANGELOG.md README.md docs/ AGENTS.md CLAUDE.md
git commit -m "docs: update documentation for <feature-name>

- Updated: [list files changed]
- Reason: [brief explanation]"

git push

⚠️ After pushing: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to /premerge <pr-number> later. If new Greptile comments appear on the doc changes, run /review <pr-number> again.

Step 4: Sync Beads

bd sync

Step 5: Hand Off — STOP HERE

DO NOT run gh pr merge. Present the PR and wait for the user to merge.

Output:

✅ PR #<number> is ready to merge

  All checks: ✓ passing
  Documentation: ✓ updated on feature branch
  Beads: ✓ synced

  👉 Please merge in the GitHub UI:
     https://github.com/<owner>/<repo>/pull/<number>

  Recommended: Squash and merge (keeps main history clean)

After you merge, run /verify to confirm everything landed correctly.

Step 6: Validate Context and Record Stage Transition

bash scripts/beads-context.sh validate <id>
bash scripts/beads-context.sh stage-transition <id> premerge verify \
  --summary "<docs updated, CI green, PR ready>" \
  --artifacts "<updated doc files, PR URL>" \
  --next "<merge instructions for user>"

<HARD-GATE: /premerge exit>
Do NOT run gh pr merge.
Do NOT suggest merging.
/premerge ends here. Output the PR URL and status. Wait for user.

"After you merge, run /verify to confirm everything landed correctly."
</HARD-GATE>

Example Output

✓ CI checks: All passing
✓ Branch: Up to date with master
✓ Documentation updated:
  - CHANGELOG.md: Entry added under [Unreleased]
  - README.md: Features list updated
  - CLAUDE.md: USER section updated with new pattern
  - Committed: docs: update documentation for auth-refresh
✓ CI re-triggered after doc push — checks passed within the 60 second poll window
✓ Beads synced

✅ PR #89 is ready to merge

  👉 Please merge in the GitHub UI:
     https://github.com/harshanandak/forge/pull/89

After you merge, run /verify

Rules

NEVER run gh pr merge — blocked by PreToolUse hook in .claude/settings.json
CLAUDE.md USER section only — never touch other managed blocks
Warn if branch is behind — tell user to rebase before doc updates
Re-check CI after doc push — doc commits re-trigger full CI pipeline
One PR, complete — code + tests + docs merged together, no follow-up doc PRs

Integration with Workflow

Utility: /status     → Understand current context before starting
Stage 1: /plan       → Design intent → research → branch + worktree + task list
Stage 2: /dev        → Implement each task with subagent-driven TDD
Stage 3: /validate      → Type check, lint, tests, security — all fresh output
Stage 4: /ship       → Push + create PR
Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
Stage 6: /premerge   → Update docs, hand off PR to user (you are here)
Stage 7: /verify     → Post-merge CI check on main

Prepare the pull request for merge by completing ALL documentation updates on the feature branch, then hand off to the user. # Premerge **The actual merge is always done by the user in the GitHub UI — never by this command.** This command makes the PR 100% complete: code + tests + docs in one unit. After this, the user merges once and there are no follow-up doc PRs needed. ## Usage ```bash /premerge <pr-number> ``` ## What This Command Does ### Step 1: Verify All CI Checks Pass ```bash gh pr checks <pr-number> ``` All checks must be green before proceeding. If any fail, run `/review <pr-number>` first. ### Step 2: Warn If Branch Is Behind Master ```bash gh pr view <pr-number> --json baseRefName,headRefName git fetch origin master git status ``` If the feature branch is behind `master`, tell the user to rebase first: ``` ⚠️ Branch is behind master — rebase before updating docs to avoid conflicts: git rebase origin/master git push --force-with-lease ``` ### Step 3: Update ALL Relevant Documentation (on feature branch) Check each of the following and update if the feature affects it. Be selective — only update what genuinely changed. **A. `CHANGELOG.md`** (always): - Add entry under `## [Unreleased]` heading (create heading if not present) - Use [Keep a Changelog](https://keepachangelog.com/) categories: - **Added**: New features - **Changed**: Changes to existing functionality - **Fixed**: Bug fixes - **Removed**: Removed features - Include: feature name, PR number, Beads ID - Example: ```markdown ## [Unreleased] ### Added - Authentication refresh tokens (PR #89, forge-a3f8) ``` **B. `README.md`** (if user-facing changes): - Features list, configuration options, usage examples **C. `docs/reference/API_REFERENCE.md`** (if API changes): - New endpoints, request/response schemas, authentication **D. Architecture docs** (if structural changes): - `docs/architecture/` diagrams, decision records (ADRs) **E. `CLAUDE.md` — USER section only** (if project conventions changed): ```  ...update only between these markers...  ``` ⚠️ NEVER touch other managed blocks (e.g., ``). **F. `AGENTS.md`** (if agent config, skills, or cross-agent workflow changed): - Update relevant sections describing agent capabilities or workflow **Commit doc updates to feature branch**: ```bash git add CHANGELOG.md README.md docs/ AGENTS.md CLAUDE.md git commit -m "docs: update documentation for <feature-name> - Updated: [list files changed] - Reason: [brief explanation]" git push ``` ⚠️ **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again. ### Step 4: Sync Beads ```bash bd sync ``` ### Step 5: Hand Off — STOP HERE **DO NOT run `gh pr merge`.** Present the PR and wait for the user to merge. Output: ``` ✅ PR #<number> is ready to merge All checks: ✓ passing Documentation: ✓ updated on feature branch Beads: ✓ synced 👉 Please merge in the GitHub UI: https://github.com/<owner>/<repo>/pull/<number> Recommended: Squash and merge (keeps main history clean) After you merge, run /verify to confirm everything landed correctly. ``` ### Step 6: Validate Context and Record Stage Transition ```bash bash scripts/beads-context.sh validate <id> bash scripts/beads-context.sh stage-transition <id> premerge verify \ --summary "<docs updated, CI green, PR ready>" \ --artifacts "<updated doc files, PR URL>" \ --next "<merge instructions for user>" ``` ``` <HARD-GATE: /premerge exit> Do NOT run gh pr merge. Do NOT suggest merging. /premerge ends here. Output the PR URL and status. Wait for user. "After you merge, run /verify to confirm everything landed correctly." </HARD-GATE> ``` ## Example Output ``` ✓ CI checks: All passing ✓ Branch: Up to date with master ✓ Documentation updated: - CHANGELOG.md: Entry added under [Unreleased] - README.md: Features list updated - CLAUDE.md: USER section updated with new pattern - Committed: docs: update documentation for auth-refresh ✓ CI re-triggered after doc push — checks passed within the 60 second poll window ✓ Beads synced ✅ PR #89 is ready to merge 👉 Please merge in the GitHub UI: https://github.com/harshanandak/forge/pull/89 After you merge, run /verify ``` ## Rules - **NEVER run `gh pr merge`** — blocked by PreToolUse hook in `.claude/settings.json` - **CLAUDE.md USER section only** — never touch other managed blocks - **Warn if branch is behind** — tell user to rebase before doc updates - **Re-check CI after doc push** — doc commits re-trigger full CI pipeline - **One PR, complete** — code + tests + docs merged together, no follow-up doc PRs ## Integration with Workflow ``` Utility: /status → Understand current context before starting Stage 1: /plan → Design intent → research → branch + worktree + task list Stage 2: /dev → Implement each task with subagent-driven TDD Stage 3: /validate → Type check, lint, tests, security — all fresh output Stage 4: /ship → Push + create PR Stage 5: /review → Address GitHub Actions, Greptile, SonarCloud Stage 6: /premerge → Update docs, hand off PR to user (you are here) Stage 7: /verify → Post-merge CI check on main ```

{ "prompt": "Prepare the pull request for merge by completing ALL documentation updates on the feature branch, then hand off to the user.\n\n# Premerge\n\n**The actual merge is always done by the user in the GitHub UI — never by this command.**\n\nThis command makes the PR 100% complete: code + tests + docs in one unit. After this, the user merges once and there are no follow-up doc PRs needed.\n\n## Usage\n\n```bash\n/premerge <pr-number>\n```\n\n## What This Command Does\n\n### Step 1: Verify All CI Checks Pass\n\n```bash\ngh pr checks <pr-number>\n```\n\nAll checks must be green before proceeding. If any fail, run `/review <pr-number>` first.\n\n### Step 2: Warn If Branch Is Behind Master\n\n```bash\ngh pr view <pr-number> --json baseRefName,headRefName\ngit fetch origin master\ngit status\n```\n\nIf the feature branch is behind `master`, tell the user to rebase first:\n\n```\n⚠️ Branch is behind master — rebase before updating docs to avoid conflicts:\n git rebase origin/master\n git push --force-with-lease\n```\n\n### Step 3: Update ALL Relevant Documentation (on feature branch)\n\nCheck each of the following and update if the feature affects it. Be selective — only update what genuinely changed.\n\n**A. `CHANGELOG.md`** (always):\n- Add entry under `## [Unreleased]` heading (create heading if not present)\n- Use [Keep a Changelog](https://keepachangelog.com/) categories:\n - **Added**: New features\n - **Changed**: Changes to existing functionality\n - **Fixed**: Bug fixes\n - **Removed**: Removed features\n- Include: feature name, PR number, Beads ID\n- Example:\n ```markdown\n ## [Unreleased]\n\n ### Added\n - Authentication refresh tokens (PR #89, forge-a3f8)\n ```\n\n**B. `README.md`** (if user-facing changes):\n- Features list, configuration options, usage examples\n\n**C. `docs/reference/API_REFERENCE.md`** (if API changes):\n- New endpoints, request/response schemas, authentication\n\n**D. Architecture docs** (if structural changes):\n- `docs/architecture/` diagrams, decision records (ADRs)\n\n**E. `CLAUDE.md` — USER section only** (if project conventions changed):\n```\n\n...update only between these markers...\n\n```\n⚠️ NEVER touch other managed blocks (e.g., ``).\n\n**F. `AGENTS.md`** (if agent config, skills, or cross-agent workflow changed):\n- Update relevant sections describing agent capabilities or workflow\n\n**Commit doc updates to feature branch**:\n\n```bash\ngit add CHANGELOG.md README.md docs/ AGENTS.md CLAUDE.md\ngit commit -m \"docs: update documentation for <feature-name>\n\n- Updated: [list files changed]\n- Reason: [brief explanation]\"\n\ngit push\n```\n\n⚠️ **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.\n\n### Step 4: Sync Beads\n\n```bash\nbd sync\n```\n\n### Step 5: Hand Off — STOP HERE\n\n**DO NOT run `gh pr merge`.** Present the PR and wait for the user to merge.\n\nOutput:\n\n```\n✅ PR #<number> is ready to merge\n\n All checks: ✓ passing\n Documentation: ✓ updated on feature branch\n Beads: ✓ synced\n\n 👉 Please merge in the GitHub UI:\n https://github.com/<owner>/<repo>/pull/<number>\n\n Recommended: Squash and merge (keeps main history clean)\n\nAfter you merge, run /verify to confirm everything landed correctly.\n```\n\n### Step 6: Validate Context and Record Stage Transition\n\n```bash\nbash scripts/beads-context.sh validate <id>\nbash scripts/beads-context.sh stage-transition <id> premerge verify \\\n --summary \"<docs updated, CI green, PR ready>\" \\\n --artifacts \"<updated doc files, PR URL>\" \\\n --next \"<merge instructions for user>\"\n```\n\n```\n<HARD-GATE: /premerge exit>\nDo NOT run gh pr merge.\nDo NOT suggest merging.\n/premerge ends here. Output the PR URL and status. Wait for user.\n\n\"After you merge, run /verify to confirm everything landed correctly.\"\n</HARD-GATE>\n```\n\n## Example Output\n\n```\n✓ CI checks: All passing\n✓ Branch: Up to date with master\n✓ Documentation updated:\n - CHANGELOG.md: Entry added under [Unreleased]\n - README.md: Features list updated\n - CLAUDE.md: USER section updated with new pattern\n - Committed: docs: update documentation for auth-refresh\n✓ CI re-triggered after doc push — checks passed within the 60 second poll window\n✓ Beads synced\n\n✅ PR #89 is ready to merge\n\n 👉 Please merge in the GitHub UI:\n https://github.com/harshanandak/forge/pull/89\n\nAfter you merge, run /verify\n```\n\n## Rules\n\n- **NEVER run `gh pr merge`** — blocked by PreToolUse hook in `.claude/settings.json`\n- **CLAUDE.md USER section only** — never touch other managed blocks\n- **Warn if branch is behind** — tell user to rebase before doc updates\n- **Re-check CI after doc push** — doc commits re-trigger full CI pipeline\n- **One PR, complete** — code + tests + docs merged together, no follow-up doc PRs\n\n## Integration with Workflow\n\n```\nUtility: /status → Understand current context before starting\nStage 1: /plan → Design intent → research → branch + worktree + task list\nStage 2: /dev → Implement each task with subagent-driven TDD\nStage 3: /validate → Type check, lint, tests, security — all fresh output\nStage 4: /ship → Push + create PR\nStage 5: /review → Address GitHub Actions, Greptile, SonarCloud\nStage 6: /premerge → Update docs, hand off PR to user (you are here)\nStage 7: /verify → Post-merge CI check on main\n```", "variables": [], "notes": "Prepare the pull request for merge by completing ALL documentation updates on the feature branch, then hand off to the user.", "metadata": { "source": { "provider": "github-prompts", "repository": "https://github.com/harshanandak/Zwapit", "path": ".github/prompts/premerge.prompt.md", "ref": "802bc31c2dbb3007b9a26cdda9124a69a0841fd8", "url": "https://github.com/harshanandak/Zwapit/blob/802bc31c2dbb3007b9a26cdda9124a69a0841fd8/.github/prompts/premerge.prompt.md", "key": "harshanandak/Zwapit/.github/prompts/premerge.prompt.md" } } }

premerge

About