dirien/stop-building-portals-start-building-conversations/pull-request-msg

Pull Request Message Generator

Generate a PR_MESSAGE.md file summarizing the current session's work. Requires gh CLI authenticated with the target repository.

Prerequisite check

gh --version 2>/dev/null && gh auth status 2>/dev/null

If gh is not installed, stop and report:

• Install from <https://cli.github.com>
• gh cannot be installed via npm
• After install, run gh auth login to authenticate

Do not proceed without a working, authenticated gh CLI.

Workflow

1. Analyze session context — review changes made in the current

session. Explore changed files with git diff and git status to understand the full scope of work, in addition to reviewing conversation history. Both sources inform the PR message.

1. Detect issue number — use the issue detection algorithm below.

If the user indicates there is no associated issue, omit the Closes #<issue-number> footer entirely.

1. Determine commit type — based on the nature of changes (see

references/pr-message-format.md for the list of types)

1. Write PR_MESSAGE.md — using the format in

references/pr-message-format.md

1. Add to .gitignore — add PR_MESSAGE.md if not already present
2. Validate — run commitlint and markdownlint checks

Issue number detection

The issue number MUST be determined by searching GitHub, NOT by extracting numbers from branch names.

Algorithm

# Step 1: Get branch name
BRANCH=$(git branch --show-current)
 
# Step 2: Extract keywords (strip leading numbers and hyphens)
# Example: "125-greenops-equivalencies" → "greenops equivalencies"
KEYWORDS=$(echo "$BRANCH" | sed 's/^[0-9]*-//' | tr '-' ' ')
 
# Step 3: Search GitHub issues
gh issue list --search "$KEYWORDS" --state all \
  --json number,title --limit 5

Evaluation rules

1. Exactly 1 result with title containing most keywords → use it
2. 0 results → ask the user for the issue number
3. 2+ results → show options and ask the user to pick
4. Ambiguous match → ask the user to confirm

Never extract issue numbers from

• Branch name digits (e.g., 125- is NOT issue #125)
• Spec folder names (e.g., specs/125-xyz/)
• Worktree folder names

These are internal identifiers, not GitHub issue numbers.

Critical rules

1. No redundancy — summary must add context beyond the commit subject
2. No `## Commit Message` section — the first line IS the commit

message

1. Never modify `.markdownlint.json` — use CLI flags instead
2. Trailing newline — file must end with a single newline
3. Ask when ambiguous — if issue search returns 0, 2+, or unclear

results, ask the user

Validation

If the commitlint and markdownlint skills are available in the current context, use them to validate PR_MESSAGE.md. Otherwise, run directly:

# Validate commit message format
cat PR_MESSAGE.md | npx commitlint
 
# Validate markdown (MD041 disabled — first line is commit subject,
# not heading)
npx markdownlint --disable MD041 -- PR_MESSAGE.md

If neither the skills nor npx are available, fail hard:

• Install commitlint: `npm install -g @commitlint/cli

@commitlint/config-conventional`

• Install markdownlint: npm install -g markdownlint-cli

Do not silently skip validation.

Fix any issues and re-validate before reporting success.