fix: use global branch numbering instead of per-short-name detection#1757
Open
fsilvaortiz wants to merge 1 commit intogithub:mainfrom
Open
fix: use global branch numbering instead of per-short-name detection#1757fsilvaortiz wants to merge 1 commit intogithub:mainfrom
fsilvaortiz wants to merge 1 commit intogithub:mainfrom
Conversation
The specify.md prompt instructed the AI to search for existing branches filtered by the exact short-name, causing every new feature to start at 001 since no branches matched the new short-name. The underlying create-new-feature.sh script already has correct global numbering logic via check_existing_branches() that searches ALL branches and spec directories. The fix removes the AI's flawed number-detection steps and tells it to NOT pass --number, letting the script auto-detect the next globally available number. Closes github#1744 Closes github#1468 🤖 Generated with [Claude Code](https://claude.com/code) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the /speckit.specify command prompt to rely on the existing create-new-feature scripts’ global branch/spec numbering logic, avoiding accidental resets to 001 caused by short-name–scoped detection.
Changes:
- Removes the prompt’s manual branch-number detection steps (remote/local/spec-dir scanning).
- Instructs running the feature creation script without
--number, letting it auto-select the next global number. - Simplifies the “IMPORTANT” guidance to prevent AI-driven overrides of numbering.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+42
to
+45
| 2. **Create the feature branch** by running the script with only `--short-name` (do NOT pass `--number` — the script auto-detects the next globally available number across all branches and spec directories): | ||
|
|
||
| a. First, fetch all remote branches to ensure we have the latest information: | ||
|
|
||
| ```bash | ||
| git fetch --all --prune | ||
| ``` | ||
|
|
||
| b. Find the highest feature number across all sources for the short-name: | ||
| - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'` | ||
| - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'` | ||
| - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>` | ||
|
|
||
| c. Determine the next available number: | ||
| - Extract all numbers from all three sources | ||
| - Find the highest number N | ||
| - Use N+1 for the new branch number | ||
|
|
||
| d. Run the script `{SCRIPT}` with the calculated number and short-name: | ||
| - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description | ||
| - Bash example: `{SCRIPT} --json --number 5 --short-name "user-auth" "Add user authentication"` | ||
| - PowerShell example: `{SCRIPT} -Json -Number 5 -ShortName "user-auth" "Add user authentication"` | ||
| - Bash example: `{SCRIPT} --json --short-name "user-auth" "Add user authentication"` | ||
| - PowerShell example: `{SCRIPT} -Json -ShortName "user-auth" "Add user authentication"` |
There was a problem hiding this comment.
Line 42 says to run the script with "only --short-name", but the workflow also depends on running with --json (and the positional feature description) so the agent can reliably parse BRANCH_NAME/SPEC_FILE. Consider rephrasing to “run with --short-name (and --json), and do not pass --number” to avoid the instruction being interpreted as omitting --json.
See below for a potential fix:
2. **Create the feature branch** by running the script with `--short-name` (and `--json`), and do NOT pass `--number` (the script auto-detects the next globally available number across all branches and spec directories):
- Bash example: `{SCRIPT} --json --short-name "user-auth" "Add user authentication"`
- PowerShell example: `{SCRIPT} -Json -ShortName "user-auth" "Add user authentication"`
**IMPORTANT**:
- Do NOT pass `--number` — the script determines the correct next number automatically
- Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
mnriem
requested changes
Mar 4, 2026
Collaborator
There was a problem hiding this comment.
@fsilvaortiz Can you address the Copilot suggestions where applicable. And what about the PowerShell variant of the script?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
specify.mdprompt instructed the AI to search for existing branches filtered by exact short-name, so every new feature started at001since no branches matched the new short-namecreate-new-feature.shalready has correct global numbering logic viacheck_existing_branches()that searches ALL branches and spec directories--number, letting the script auto-detect the next globally available numberCloses #1744
Closes #1468
Root cause
The prompt at step 2b told the AI to grep for branches matching the exact short-name:
And step 2c said: "If no existing branches/directories found with this short-name, start with number 1". Since each new feature has a unique short-name, the search always returned empty and numbering reset to 001.
Test plan
001,002,003to 3 different features when--numberis NOT passed--number 1manually causes duplicate001prefixes (confirming the AI override was the problem)🤖 Generated with Claude Code