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

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

# 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 NEXTNUMBER=$(cat .next-issue-number) else NEXTNUMBER=$(scripts/next-issue-number.sh) fi ``

1. Update and switch to main:

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

1. Create the feature branch with the determined number:

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

1. IMMEDIATELY push the branch to reserve the number:

``bash git push -u origin HEAD ``

1. 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 NEXTNUMBER=$(cat .next-issue-number) else NEXTNUMBER=$(scripts/next-issue-number.sh) fi ``

1. Update and switch to main:

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

1. Create the fix branch with the determined number:

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

1. IMMEDIATELY push the branch to reserve the number:

``bash git push -u origin HEAD ``

1. 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 NEXTNUMBER=$(cat .next-issue-number) else NEXTNUMBER=$(scripts/next-issue-number.sh) fi ``

1. Update and switch to main:

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

1. Create the workflow branch with the determined number:

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

1. IMMEDIATELY push the branch to reserve the number:

``bash git push -u origin HEAD ``

1. 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)