# Next Issue Number

> Determine the next available issue number across all change types (feature, fix, workflow, website) by checking both local docs and remote branches, then reserve it by pushing an empty branch.

- Skill: `oocx/next-issue-number` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add oocx/next-issue-number`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oocx/next-issue-number/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: oocx (https://skillmd.com/u/oocx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oocx/next-issue-number

---


# Skill Instructions

## Purpose

Ensure unique issue numbering across all change types (feature, fix, workflow, website) by:

1. Finding the highest number used in local docs folders (docs/features/, docs/issues/, docs/workflow/)
2. Finding the highest number used in remote branches on GitHub (feature/NNN-*, fix/NNN-*, workflow/NNN-*)
3. Finding the highest number used in recent `copilot/*` remote branches (less than one week old)
4. Calculating the next available number (max + 1)
5. Immediately pushing the new branch to GitHub to reserve the number for other agents

This prevents duplicate issue numbers when multiple agents work concurrently or when work-in-progress exists on remote branches but not yet in main.

## Session Start Hook

A `SessionStart` hook (declared in `.agents/claude-settings.json`) automatically runs `scripts/next-issue-number.sh` when a new agent session begins and writes the result to `.next-issue-number`. This means the next issue number is pre-calculated for you at session start.

**Read the pre-calculated value first** (fast, no network call required):

```bash
if [ -f .next-issue-number ]; then
    NEXT_NUMBER=$(cat .next-issue-number)
else
    NEXT_NUMBER=$(scripts/next-issue-number.sh)
fi
echo "Next issue number: $NEXT_NUMBER"
```

The `.next-issue-number` file is gitignored and refreshed each session. If it is missing or stale, fall back to running the script directly.

## Hard Rules

### Must

- [ ] Check ALL change types (feature, fix, workflow), not just one type
- [ ] Check both local docs folders AND remote GitHub branches (including recent copilot/* branches)
- [ ] Use the helper script `scripts/next-issue-number.sh` which handles all lookups
- [ ] Push the new branch immediately after creation (before making any changes) to reserve the number
- [ ] Format the number as 3 digits with leading zeros (e.g., 033, 034, 035)
- [ ] Minimize Maintainer approvals by using a single stable wrapper script

### Must Not

- [ ] Only check one change type (e.g., only features)
- [ ] Skip checking remote branches
- [ ] Delay pushing the branch until after making changes
- [ ] Assume the next number based on local state alone

## Golden Example

```bash
# Step 1: Determine the next issue number (prefer pre-calculated value from session hook)
if [ -f .next-issue-number ]; then
    NEXT_NUMBER=$(cat .next-issue-number)
else
    NEXT_NUMBER=$(scripts/next-issue-number.sh)
fi
echo "Next issue number: $NEXT_NUMBER"

# Step 2: Create the branch with the determined number
git fetch origin && git switch main && git pull --ff-only origin main
git switch -c feature/${NEXT_NUMBER}-my-feature-name

# Step 3: IMMEDIATELY push to reserve the number
git push -u origin HEAD

# Now proceed with your work...
```

## Actions

### For Requirements Engineer (New Features)

1. **Before creating a feature branch**, get the next number:

   ```bash
   if [ -f .next-issue-number ]; then
       NEXT_NUMBER=$(cat .next-issue-number)
   else
       NEXT_NUMBER=$(scripts/next-issue-number.sh)
   fi
   ```

2. Update and switch to main:

   ```bash
   git fetch origin && git switch main && git pull --ff-only origin main
   ```

3. Create the feature branch with the determined number:

   ```bash
   git switch -c feature/${NEXT_NUMBER}-<short-description>
   ```

4. **IMMEDIATELY push the branch** to reserve the number:

   ```bash
   git push -u origin HEAD
   ```

5. Proceed with gathering requirements and creating the specification

### For Issue Analyst (Bug Fixes)

1. **Before creating a fix branch**, get the next number:

   ```bash
   if [ -f .next-issue-number ]; then
       NEXT_NUMBER=$(cat .next-issue-number)
   else
       NEXT_NUMBER=$(scripts/next-issue-number.sh)
   fi
   ```

2. Update and switch to main:

   ```bash
   git fetch origin && git switch main && git pull --ff-only origin main
   ```

3. Create the fix branch with the determined number:

   ```bash
   git switch -c fix/${NEXT_NUMBER}-<short-description>
   ```

4. **IMMEDIATELY push the branch** to reserve the number:

   ```bash
   git push -u origin HEAD
   ```

5. Proceed with issue investigation and analysis

### For Workflow Engineer (Workflow Improvements)

1. **Before creating a workflow branch**, get the next number:

   ```bash
   if [ -f .next-issue-number ]; then
       NEXT_NUMBER=$(cat .next-issue-number)
   else
       NEXT_NUMBER=$(scripts/next-issue-number.sh)
   fi
   ```

2. Update and switch to main:

   ```bash
   git fetch origin && git switch main && git pull --ff-only origin main
   ```

3. Create the workflow branch with the determined number:

   ```bash
   git switch -c workflow/${NEXT_NUMBER}-<short-description>
   ```

4. **IMMEDIATELY push the branch** to reserve the number:

   ```bash
   git push -u origin HEAD
   ```

5. Proceed with workflow improvements

## Troubleshooting

### If GitHub authentication fails

The script will fall back to checking only local docs folders and warn you:

```
Warning: Could not fetch from GitHub. Using local data only.
Next available number based on local docs: 033
```

In this case, manually verify on GitHub that no higher numbers exist in remote branches.

### If the calculated number already exists

The script checks local docs, named branches, and recent copilot/* branches. If it still returns a number that exists:

1. Verify the script ran correctly: `scripts/next-issue-number.sh`
2. Check if someone pushed a new branch since you ran the script
3. Delete your branch and re-run the script to get a fresh number

## Verification

After running the script and pushing your branch:

1. Verify the branch exists on GitHub: `git ls-remote origin | grep "refs/heads/\(feature\|fix\|workflow\)/${NEXT_NUMBER}-"`
2. Confirm no docs folder exists yet: `ls -d docs/{features,issues,workflow}/${NEXT_NUMBER}-* 2>/dev/null` (should be empty)