/quick-issue

<objective> Create a GitHub issue and working branch in a single step, enabling developers to quickly start work on bug fixes, small enhancements, and maintenance tasks without going through the full PRD workflow. The command creates the issue, labels it with standard GitHub labels based on the work type, creates and checks out a feature branch, and optionally adds the issue to a GitHub Project. </objective> <prerequisites> - `gh` CLI installed and authenticated (`gh auth status`) - Working directory is a git repository with GitHub remote - User has write access to repository issues - Git working directory is clean (no uncommitted changes) - Optional: `GHPM_PROJECT` environment variable set for project association </prerequisites> <arguments> **Required:** - Issue description/title (captured from user input via $ARGUMENTS)

Optional flags (in $ARGUMENTS):

• --label <name> - Add a label (can be used multiple times)
• --no-branch - Create issue only, skip branch creation
• --type <fix|feat|chore> - Set work type (default: fix)
  • fix → adds bug label, creates fix/ branch
  • feat → adds enhancement label, creates feat/ branch
  • chore → no automatic label, creates chore/ branch

Optional environment variables:

• GHPM_PROJECT - GitHub Project number to add issue to (e.g., export GHPM_PROJECT=7) </arguments>

<usage_examples> Bug fix (default):

/ghpm:quick-issue Fix the login redirect loop when session expires

Output:

✓ Issue #42 created: "Fix the login redirect loop when session expires"
  https://github.com/owner/repo/issues/42
  Labels: bug
✓ Branch created: fix/issue-42-login-redirect-loop
✓ Switched to branch fix/issue-42-login-redirect-loop

Ready to work on issue #42. What would you like me to do first?

New feature:

/ghpm:quick-issue Add dark mode toggle --type feat

→ Labels: enhancement → Branch: feat/issue-43-dark-mode-toggle

Maintenance/chore:

/ghpm:quick-issue Update dependencies to latest versions --type chore

→ Labels: (none by default) → Branch: chore/issue-44-update-dependencies

With additional labels:

/ghpm:quick-issue Fix slow dashboard loading --label performance --label high-priority

→ Labels: bug, performance, high-priority

Issue only (no branch):

/ghpm:quick-issue Update README with new API docs --type chore --no-branch

With project association:

export GHPM_PROJECT=7
/ghpm:quick-issue Fix broken date formatting in reports

→ Issue added to project #7

</usage_examples>

<operating_rules>

• Do not ask clarifying questions. Create the issue immediately with the provided description.
• The issue description becomes both the issue title and the summary in the body.
• Labels are determined by the --type flag using standard GitHub labels:
  • fix (default) → bug label
  • feat → enhancement label
  • chore → no automatic label
• Additional labels can be added with --label flag.
• Branch names are sanitized: lowercase, special characters removed, truncated to 50 chars.
• Default type is fix (assumes most quick issues are bug fixes).
• If --no-branch is specified, skip branch creation entirely.
• On any error, provide actionable guidance for resolution. </operating_rules>

<workflow>

Step 1: Validate Environment

# 1. Verify gh CLI authentication
gh auth status || { echo "ERROR: Not authenticated. Run 'gh auth login'"; exit 1; }

# 2. Verify in git repository
git rev-parse --git-dir > /dev/null 2>&1 || { echo "ERROR: Not in a git repository"; exit 1; }

# 3. Verify GitHub remote exists
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner) || { echo "ERROR: No GitHub remote found"; exit 1; }
OWNER=$(gh repo view --json owner -q '.owner.login')

Step 2: Parse Arguments

Extract from $ARGUMENTS:

• Issue description (everything that's not a flag)
• --label <name> if present (can appear multiple times)
• --no-branch flag
• --type <fix|feat|chore> if present (default: fix)

# Example parsing
DESCRIPTION="<extracted description>"
EXTRA_LABELS=()  # array of additional labels from --label flags
NO_BRANCH=false  # or true if --no-branch present
WORK_TYPE="fix"  # or feat/chore if --type specified

Validate:

• Description must not be empty
• If --type provided, must be one of: fix, feat, chore

Step 3: Determine Labels Based on Type

# Map work type to standard GitHub label
case "$WORK_TYPE" in
  fix)
    TYPE_LABEL="bug"
    BRANCH_PREFIX="fix"
    ;;
  feat)
    TYPE_LABEL="enhancement"
    BRANCH_PREFIX="feat"
    ;;
  chore)
    TYPE_LABEL=""  # No automatic label for chores
    BRANCH_PREFIX="chore"
    ;;
esac

# Build label list
LABELS=""
if [ -n "$TYPE_LABEL" ]; then
  LABELS="$TYPE_LABEL"
fi

# Add any extra labels from --label flags
for label in "${EXTRA_LABELS[@]}"; do
  if [ -n "$LABELS" ]; then
    LABELS="$LABELS,$label"
  else
    LABELS="$label"
  fi
done

Step 4: Create GitHub Issue

# Build gh issue create command
if [ -n "$LABELS" ]; then
  ISSUE_URL=$(gh issue create \
    --repo "$REPO" \
    --title "$DESCRIPTION" \
    --label "$LABELS" \
    --body "$(cat <<EOF
$DESCRIPTION

---
*Created via \`/ghpm:quick-issue\`*
EOF
)")
else
  # No labels
  ISSUE_URL=$(gh issue create \
    --repo "$REPO" \
    --title "$DESCRIPTION" \
    --body "$(cat <<EOF
$DESCRIPTION

---
*Created via \`/ghpm:quick-issue\`*
EOF
)")
fi

# Extract issue number from URL
ISSUE_NUM=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')

Step 5: Add to GitHub Project (if configured)

if [ -n "$GHPM_PROJECT" ]; then
  gh project item-add "$GHPM_PROJECT" --owner "$OWNER" --url "$ISSUE_URL" 2>/dev/null && \
    echo "✓ Added to project #$GHPM_PROJECT" || \
    echo "WARNING: Could not add to project #$GHPM_PROJECT"
fi

Step 6: Create and Checkout Branch (unless --no-branch)

if [ "$NO_BRANCH" = false ]; then
  # Generate branch name slug from description
  # 1. Convert to lowercase
  # 2. Replace spaces and special chars with hyphens
  # 3. Remove consecutive hyphens
  # 4. Truncate to 50 chars
  # 5. Remove trailing hyphens
  SLUG=$(echo "$DESCRIPTION" | \
    tr '[:upper:]' '[:lower:]' | \
    sed 's/[^a-z0-9]/-/g' | \
    sed 's/-\+/-/g' | \
    cut -c1-50 | \
    sed 's/-$//')

  BRANCH_NAME="$BRANCH_PREFIX/issue-$ISSUE_NUM-$SLUG"

  # Check for uncommitted changes
  if ! git diff-index --quiet HEAD -- 2>/dev/null; then
    echo "WARNING: Uncommitted changes detected. Branch created but not checked out."
    echo "Run: git stash && git checkout $BRANCH_NAME"
  else
    # Create and checkout branch
    git checkout -b "$BRANCH_NAME" || {
      echo "ERROR: Failed to create branch. You may need to create it manually:"
      echo "  git checkout -b $BRANCH_NAME"
    }
  fi

  # Update issue body with branch link
  gh issue edit "$ISSUE_NUM" --repo "$REPO" --body "$(cat <<EOF
$DESCRIPTION

**Branch:** \`$BRANCH_NAME\`

---
*Created via \`/ghpm:quick-issue\`*
EOF
)"
fi

Step 7: Output Success Message

echo ""
echo "✓ Issue #$ISSUE_NUM created: \"$DESCRIPTION\""
echo "  $ISSUE_URL"
if [ -n "$LABELS" ]; then
  echo "  Labels: $LABELS"
fi

if [ "$NO_BRANCH" = false ]; then
  echo "✓ Branch created: $BRANCH_NAME"
  echo "✓ Switched to branch $BRANCH_NAME"
fi

if [ -n "$GHPM_PROJECT" ]; then
  echo "✓ Added to project #$GHPM_PROJECT"
fi

echo ""
echo "Ready to work on issue #$ISSUE_NUM. What would you like me to do first?"

</workflow>

<error_handling> If gh CLI not authenticated:

ERROR: Not authenticated. Run 'gh auth login'

If not in git repository:

ERROR: Not in a git repository. Navigate to your project directory.

If no GitHub remote:

ERROR: No GitHub remote found. Add one with: git remote add origin <url>

If description is empty:

ERROR: Issue description required.
Usage: /ghpm:quick-issue <description> [--type <fix|feat|chore>] [--label <name>] [--no-branch]

If issue creation fails:

ERROR: Failed to create issue. Check:
- gh auth status (authentication)
- Repository permissions (write access to issues)
- Rate limits: gh api rate_limit

If branch creation fails:

WARNING: Issue #N created, but branch creation failed.
Create branch manually: git checkout -b <branch-name>

If uncommitted changes exist:

WARNING: Uncommitted changes detected. Branch created but not checked out.
Run: git stash && git checkout <branch-name>

</error_handling>

<success_criteria> Command completes successfully when:

1. GitHub issue is created with appropriate label(s) based on type
2. Issue body contains description and branch link (if branch created)
3. Branch is created with correct naming convention (unless --no-branch)
4. Branch is checked out (unless uncommitted changes or --no-branch)
5. Issue is added to project (if GHPM_PROJECT set)
6. Success message displays issue URL, labels, and branch name

Verification:

# View the created issue
gh issue view <issue_number>

# Check current branch
git branch --show-current

# Verify issue labels
gh issue view <issue_number> --json labels -q '.labels[].name'

</success_criteria>

<output> After completion, display:

✓ Issue #<number> created: "<description>"
  <issue_url>
  Labels: <label1>, <label2>
✓ Branch created: <branch_prefix>/issue-<number>-<slug>
✓ Switched to branch <branch_prefix>/issue-<number>-<slug>
[✓ Added to project #<project_number>]  (if GHPM_PROJECT set)

Ready to work on issue #<number>. What would you like me to do first?

If --no-branch was specified:

✓ Issue #<number> created: "<description>"
  <issue_url>
  Labels: <label1>, <label2>
[✓ Added to project #<project_number>]  (if GHPM_PROJECT set)

Issue created. Run `/ghpm:tdd-task task=#<number>` to start implementation.

</output>

<related_commands> After creating a quick issue:

• /ghpm:tdd-task task=#N - Implement the issue using TDD
• /ghpm:execute task=#N - Execute the issue (auto-routes to TDD or non-TDD)

Full GHPM workflow (for larger features):

1. /ghpm:create-prd - Create PRD from user input
2. /ghpm:create-epics - Break PRD into Epics
3. /ghpm:create-tasks - Break Epics into Tasks
4. /ghpm:tdd-task - Implement Tasks with TDD </related_commands>

Proceed now: parse $ARGUMENTS, validate environment, create issue and branch.