fix: use global branch numbering instead of per-short-name detection#1757
fix: use global branch numbering instead of per-short-name detection#1757fsilvaortiz wants to merge 2 commits 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 <[email protected]>
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.
templates/commands/specify.md
Outdated
| 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
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?
- Rephrased step 2 to mention both --short-name and --json flags - Added explicit note to always include the JSON flag for reliable output parsing Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
@mnriem Applied the Copilot suggestion in b6bccdd — clarified that Regarding PowerShell: the bug is not in the scripts — both 🤖 Generated with Claude Code |
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