Creating Issues And Pull Requests

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) - All 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 single stray #108 in a PR description pings everyone subscribed to issue 108. This is treated as a SAFETY-CRITICAL concern, not a nice-to-have. The sanitization gate in the 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. Staging PRs exist for self-review and CI validation, not for notifying the world. 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) when ready, create the real PR on upstream. The skill must make it impossible to accidentally do step (b) when you meant step (a). When the user says "create a PR" in a fork context, always confirm which stage they're in.

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

Before dispatching, collect the 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

Before dispatching, determine the workflow stage and draft mode:

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 behavior:

   • Force --draft by default. The user must explicitly pass --draft=false to override.
   • Set the target to the fork remote.

5. Upstream submit confirmation:

Do not proceed without a clear "yes" from the user.

6. Pass forward: Provide 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.

• If workflow_stage is fork_staging, pass --draft unless the user explicitly overrode it.
• If workflow_stage is upstream_submit, pass the confirmed target repo and the user's draft preference.
• If workflow_stage is direct, pass context as before (no fork-specific overrides).

For issue creation:

Dispatch subagent with command: /create-issue

Provide context: target repo (if known), labels, workflow_stage.

• If workflow_stage is fork_staging or upstream_submit, ensure the issue is created on the correct target 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. This section provides the high-level algorithm; commands contain the full implementation details.

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. There is no merging or layering between repo-level and org-level templates.

Naming Conventions

Post-Creation Operations

Since gh pr edit is broken (GitHub Projects Classic deprecation), use the REST API for any post-creation modifications:

# Update PR title or body
gh api repos/OWNER/REPO/pulls/NUMBER --method PATCH \
  -f title="New title" -f body="New body"

# Add labels
gh api repos/OWNER/REPO/issues/NUMBER/labels --method POST \
  -f 'labels[]=label1'

# Request reviewers
gh api repos/OWNER/REPO/pulls/NUMBER/requested_reviewers --method POST \
  -f 'reviewers[]=username'

Self-Check

IF ANY unchecked: STOP and fix.