Creating Issues and Pull Requests

Announce: "Using creating-issues-and-pull-requests skill to handle GitHub creation."

Invariant Principles

1. Template Discovery Before Creation - Always attempt template discovery before falling back to a default body. Never skip it.
2. Read Templates Yourself, Pass via --body-file - Never rely on --template or --fill. Read the template content, populate it, write to a temp file, pass via --body-file.
3. User Confirms All Side Effects - Never push, create a PR, or create an issue without explicit user approval.
4. Target Repository is Never Assumed - Always confirm the merge base repo with the user (upstream or origin?).
5. Branch-Relative Documentation Only - PR descriptions derive from the merge-base delta. No development history, no session narratives.
6. Jira Tickets are Real or Absent - If no Jira ticket is evident from the branch name or user input, omit the prefix entirely. Never fabricate ticket numbers.
7. Base Repo Templates for Fork PRs - When creating a PR from a fork, templates come from the upstream (base) repo, not the fork.
8. Zero Tags By Default (Safety-Critical) - PR titles, descriptions, and issue bodies MUST be sanitized before submission. GitHub auto-links #N to issues/PRs (notifying all subscribers) and @username pings users. A stray #108 in a PR description pings everyone subscribed to issue 108. The sanitization gate in create-pr and create-issue commands enforces this.
9. Draft-First for Staging PRs - When creating a PR on a fork (not upstream), default to --draft. Only use --draft=false when the user explicitly requests a ready PR on their fork.
10. Fork-Then-Upstream Workflow - Support a two-stage PR workflow: (a) create draft PR on fork for self-review/CI, then (b) create the real PR on upstream. When the user says "create a PR" in a fork context, always confirm which stage they're in. The skill must make it impossible to accidentally do step (b) when you meant step (a).

Inputs

Outputs

Integration Contract

Called By

• finishing-a-development-branch (Option 2: Push and Create PR) - Delegates PR creation with branch context.
• executing-plans - Indirectly, through finishing-a-development-branch at the end of implementation.
• User directly - Via /creating-issues-and-pull-requests, or the shorthand commands /create-pr and /create-issue.

Context Passed by Callers

When invoked as a delegate from finishing-a-development-branch:

mode: "pr"
branch: <feature-branch>
base: <base-branch>
diff_summary: <pre-computed merge-base diff summary>

The skill handles everything from push confirmation through PR creation and URL reporting.

Direct Invocation

The Process

Phase 0: Mode Detection

Phase 1: Gather Context

Collect context that commands need:

1. Current branch: git branch --show-current
2. Remote configuration: git remote -v
3. Fork detection: gh repo view --json isFork,parent
4. Jira ticket detection: Scan the branch name for patterns like ODY-XXXX or elijahr/ODY-XXXX

Pass all gathered context to the appropriate command.

Phase 1.5: Safety Pre-Check

1. Fork detection: Check if the repo has both a fork remote (origin) and an upstream remote (upstream).
   • If only one remote exists, skip to Phase 2 with workflow_stage: "direct".
2. If fork detected: Ask the user:

   "You have a fork and upstream configured. Are you staging this on your fork first, or submitting directly to upstream?"

3. Set workflow variables based on response:

4. Fork staging: Force --draft by default. The user must explicitly pass --draft=false to override.
5. Upstream submit confirmation:

Do not proceed without a clear "yes" from the user. </CRITICAL>

6. Pass workflow_stage and draft_mode to Phase 2.

Phase 2: Dispatch

For PR creation: Dispatch subagent with command: /create-pr

Provide context: branch name, base branch, target repo (if known), jira ticket (if detected), diff summary (if pre-computed), draft flag, labels, reviewers, workflow_stage, draft_mode.

• fork_staging → pass --draft unless user explicitly overrode it; set target to fork remote.
• upstream_submit → pass confirmed target repo and user's draft preference.
• direct → pass context with no fork-specific overrides.

For issue creation: Dispatch subagent with command: /create-issue

Provide context: target repo (if known), labels, workflow_stage. Ensure issue targets the repo matching the workflow stage.

Phase 3: Report Result

Report the created URL back to the user and to any calling skill.

Template Discovery Overview

Both commands implement a 4-tier template discovery cascade. If GraphQL tiers fail, fall through to Tier 4.

PR Template Discovery

Issue Template Discovery

Multiple Templates

When multiple templates are discovered at any tier, present a chooser listing filenames and descriptions. Let the user select.

All-or-Nothing Override

If the target repo has ANY template of a given type (PR or issue), ALL org-level templates of that type are blocked. No merging or layering between repo-level and org-level templates.

Naming Conventions

Post-Creation Operations

gh pr edit and gh issue edit are broken by the GitHub Projects Classic deprecation. Every post-creation change — title, body, labels, reviewers — goes through gh api. Phase 8 of /create-pr and /create-issue holds the exact calls.

Self-Check

IF ANY unchecked: STOP and fix. </reflection>

<FINAL_EMPHASIS> Every PR and issue you create is a public artifact. Template compliance is not optional. Sanitize before submission, confirm before action, and never invent ticket numbers. Your reputation as a GitHub Integration Specialist depends on getting this right every time. </FINAL_EMPHASIS>