create-github-pr

Create GitHub PR (from staged changes → new branch → PR into main)

Takes the current staged changes (git add'd files), creates a new feature branch, commits the work, pushes, and opens a PR into main — always linked to a Linear ticket (existing or freshly created) so the two are navigable from each other.

⚠️ MANUAL ONLY — This skill runs ONLY when you explicitly ask to open a PR. It will never auto-trigger.

Arguments

Arg	Required	Description
ticket number	No	An existing Linear ticket ID (e.g. DEV-123) to link. If omitted, the ticket is resolved or created (step 2).
context	No	Extra context about the change — e.g. the reason, motivation, or any details to weave into the PR title/body.

Note: The branch name is always asked interactively (type one or let the skill auto-generate it).

Workflow

CRITICAL: Plan first, execute only after approval. Steps 1–5 are READ-ONLY planning. Do NOT create branches, commits, tickets, or PRs until the user explicitly approves the plan in step 5. The only action allowed before approval is reading the staged diff and asking questions.

---

Phase 1: Planning (NO side effects — no branches, commits, tickets, or PRs)

1. Verify staged changes exist

• Run git diff --cached --stat to confirm there are staged changes.
• If nothing is staged, stop and tell the user to git add the files they want in the PR.
• If there are also unstaged changes, note them but proceed with only what's staged.
• Review the staged diff (git diff --cached) to understand the scope of changes.

2. Resolve the Linear ticket

The PR must be linked to a Linear ticket. Resolve one in this priority order:

1. Ticket argument — if a ticket ID was passed, validate it with mcp__linear__get_issue and use it.

If a ticket is found, confirm it with mcp__linear__get_issue (title + state) and reuse it.

If no ticket is found, ask the user:

1. Enter an existing ticket — provide a Linear ticket ID to link.
2. Create a new ticket — indicate they want one created (will be created in the execution phase).

Do NOT create the ticket yet. Just note the decision.

3. Check PR size

• Count lines in the staged diff excluding test and lock files: git diff --cached --stat -- . ':!*.spec.*' ':!*.test.*' ':!pnpm-lock.yaml' ':!package-lock.json' ':!yarn.lock'
• If the total exceeds 400 lines, warn the user and suggest splitting. Ask whether to proceed or abort.

4. Craft the PR title and body

Title — conventional-commit form, prefixed with the ticket:

[DEV-123] <type>: <concise description>

• Types: feat, fix, refactor, docs, test, chore, perf, ci.

Body — the established repo format (literal newlines, not \n):

Summary
<One-sentence overview of what the PR adds / changes / removes.>

<Bullet points expanding on the specific changes — what was added, removed, or restructured.
Capture intent and scope, not line-by-line implementation detail.
If a **context** argument was provided, incorporate the motivation/reason naturally into the
summary and bullets.>

Test plan

- [ ] <Verification step 1>
- [ ] <Verification step 2 (if needed)>

5. Choose branch name

Ask the user: "What should the branch be?" and present two options:

1. Type a name — the user provides a branch name directly
2. Auto-generate — derive a branch name from the ticket and a slug of the change: <date>_<ticket-lower>_<slug> e.g. 06-03_dev-621_fix-drizzle-journal

6. Present full plan for approval

Show the user a clear summary of everything that will happen and wait for explicit approval before taking ANY action:

📋 PR PLAN (nothing created yet)
─────────────────────────────────────────
Ticket: DEV-621  (existing) / "will create: <title>"
Branch: 06-03_dev-621_fix-drizzle-journal  (will be created off main)
Type:   fix
Title:  [DEV-621] fix: register migrations 0023/0024 in drizzle journal

Staged: 3 files, +48 -2

Body:
  Summary
  Registers the missing 0023/0024 migrations in the drizzle journal so
  db:migrate applies them in order.

  ...

  Test plan
  - [ ] ...

Actions that will be taken on approval:
  1. Create Linear ticket (if needed)
  2. Stash staged changes
  3. Checkout main, pull latest
  4. Create branch: 06-03_dev-621_fix-drizzle-journal
  5. Pop stash, commit, push
  6. Open PR into main
  7. Link PR ↔ Linear ticket

Ready to execute? (yes/no)

If the user declines, ask what to change (title, body, ticket, scope) and revise the plan. Do NOT proceed until the user says yes.

---

Phase 2: Execution (ONLY after explicit user approval)

7. Create Linear ticket (if needed)

• If step 2 determined a new ticket is needed, invoke linear-ticket-create now.
• Capture the ticket identifier and url.

8. Stash staged changes, switch to main, create branch, commit, and push

This step ensures the PR branch always forks directly off main, regardless of the current branch state:

• Stash the staged changes: git stash push --staged -m "pr-staged-changes"
• Switch to main and pull latest: git checkout main && git pull --ff-only
• Use the branch name chosen in step 5 (user-provided or auto-generated)
• Create and switch to the new branch off main: git checkout -b <branch-name>
• Pop the stash: git stash pop
• Stage the changes again (the pop unstages): git add -A (or re-add the specific files)
• Commit with a conventional-commit message prefixed with the ticket: git commit -m "[DEV-123] <type>: <concise description>"
• Push the branch: git push -u origin HEAD

9. Open the PR

• Always targets main:

  gh pr create \
    --base "main" \
    --title "[DEV-123] <type>: <description>" \
    --body "$(cat <<'EOF'
  Summary
  ...
  
  Test plan
  
  - [ ] ...
  EOF
  )"
  

• Capture the PR number and URL from the command output (or gh pr view --json number,url).

10. Link the PR to the Linear ticket (both directions)

• Attach the PR to the Linear issue so the link is bidirectional: mcp__linear__create_attachment with issueId (the ticket), url = the PR URL, and a title like PR #<number>: <pr title>.
• The [DEV-123] prefix on the PR title is the other half of the link — confirm it's present.
• Do not silently move the ticket's state. If the user wants it advanced (e.g. to In Review), do it on request via mcp__linear__save_issue.

11. Report back

• Give the user the PR number and clickable PR url.
• Give the linked ticket identifier, title, and Linear url.
• Confirm the branch name and that it targets main.

Conventional PR Examples

Feature

[DEV-510] feat: make sub-deal rows clickable with actions column

Summary
Makes each sub-deal row navigate to its detail view and adds an actions column.

Wrap sub-deal reference cells in a link to the sub-deal route.
Add an actions column with per-row controls.
Keep row click and action buttons from conflicting.

Test plan

- [ ] Click a sub-deal row and confirm it opens the correct sub-deal
- [ ] Use an action button and confirm the row does not also navigate

Bug Fix

[DEV-621] fix: register migrations 0023/0024 in drizzle journal

Summary
Registers the missing 0023/0024 migrations in the drizzle journal so db:migrate
applies them in order.

Add the 0023 and 0024 entries to drizzle/meta/_journal.json.
Regenerate the matching snapshot files.

Test plan

- [ ] Run npm run db:migrate on a clean DB and confirm 0023/0024 apply
- [ ] Confirm drizzle-kit reports no pending or out-of-order migrations

Refactor

[DEV-507] refactor: extract parseDateParam helper and thread settlement date through PDF endpoints

Summary
Extracts a shared parseDateParam helper and threads the settlement date through the PDF
export endpoints.

Add parseDateParam to centralise query-date parsing and validation.
Pass the parsed settlement date into each PDF export route.
Remove the duplicated inline date parsing.

Test plan

- [ ] Export a PDF with a settlement date query param and confirm it renders
- [ ] Omit the param and confirm the endpoint falls back correctly

Key Principles

• Plan first, act only after approval — steps 1–5 are read-only planning. No branches, commits, tickets, or PRs are created until the user explicitly approves the plan.
• Staged changes are the input — the skill works from whatever is in the git index (git diff --cached). Stage your files first, then invoke this skill.
• Always forks off main — regardless of the current branch, the new PR branch is always created directly off the latest main.
• Always targets main — PRs created by this skill always merge into main.
• Always linked to Linear — a PR is never opened without a ticket. Resolve from the argument or create one (after approval). There is no skip.
• Link both ways — attach the PR to the ticket and prefix the PR title with [DEV-123], so each is reachable from the other.
• Title captures intent, bullets capture scope — the one-line summary explains why; the bullets list what was added / removed / changed.
• Keep PRs reviewable — warn past 400 non-test/non-lock lines and offer to split.
• User approval required — always show the summary and wait for confirmation before gh pr create.

When to Use

ONLY when you explicitly ask to open a PR. This skill is manual and does not auto-trigger. Examples of explicit requests:

• "open a PR"
• "create a github pr"
• "raise a pull request"
• "PR this into main"
• "commit and PR these changes"

It will NEVER run unless you explicitly invoke it or ask to create a PR.

Related skills

• linear-ticket-create — turn loose input into a Triage-ready ticket; used by step 2 when no ticket exists yet.
• pr-to-linear-ticket — the reverse/repair flow: back-fill a ticket for an already-open PR and stamp its title.