Repository navigation
Conversation
added 9 commits
November 14, 2026 14:17
Agents handling remote ambiguity could select the wrong recovery when told to expect exit 6. The remote picker returns an ordinary error in non-interactive ambiguity, and its push caller returns the exit-1 sentinel; the complete caller census follows the same mapping. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/utils.go#L1955-L1972 https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/push.go#L82-L88 Stack ambiguity remains an exit-6 condition; this does not remove any remote-selection prerequisite. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/utils.go#L451-L456
Readers starting from the README could avoid the supported editor-based staging flow because it incorrectly requires an inline message. The command explicitly supports omitting the message with the all-files flag. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L27-L42 The removed message prerequisite does not apply. The independent all-files/tracked-only mutual exclusion still applies in flag validation. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L49-L68
README readers could mistake an inline message for a prerequisite to staging tracked files. Tracked-only staging independently requests a commit, and an empty message selects the editor. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L57-L68 https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L368-L406 The removed message prerequisite does not apply; mutual exclusion with all-files staging and the requirement for staged content remain in these same checks.
Agents consulting the CLI reference could reject the supported all-file staging flow without an inline message. The command's own help identifies the editor fallback, so the reference should not forbid that choice. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L27-L42 The removed message prerequisite does not apply; the separate staging-flag exclusion still applies. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L57-L68
Readers of the CLI reference could unnecessarily rule out tracked-only staging with an editor-written message. The tracked flag requests a commit on its own, and an empty message is supported by the commit helper. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L57-L68 https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L368-L406 The removed message prerequisite does not apply; staging-flag mutual exclusion and the staged-content check remain at those definitions.
An unattended agent could treat a successful divergence stop as proof that local fetch state is unchanged. Sync fetches before reconciling divergence, and that fetch can update remote-tracking refs. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/sync.go#L127-L158 https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/internal/git/gitops.go#L196-L211 There is no blanket no-change guarantee to retain. The successful early stop still bypasses later pushing, and the separate conflict rollback warning remains in the command reference. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/skills/gh-stack/references/commands.md#L103-L120
The agent command reference could rule out a supported staging workflow by making an inline message mandatory. Either staging flag independently requests a commit, and the commit helper opens the editor when no message is supplied. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L57-L68 https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/add.go#L399-L406 The removed message prerequisite does not apply. Flag mutual exclusion remains in this reference, and the required stack-design procedure still directs agents to stage and commit deliberately. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/skills/gh-stack/references/stack-design.md#L50-L57
Agents preparing commit prose could assume automatic submission will use it even when a repository template overrides the description. The automatic creation path passes template content to the body generator, whose override requires nonempty content. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/submit.go#L503-L525 https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/submit.go#L546-L563 Keeping that condition with the body-source claim avoids relying on the wrong description source without changing title generation or the existing follow-up editing advice.
An agent following divergence recovery could assume a successful stop undoes earlier fetch effects. Fetching precedes the successful non-interactive divergence return, so remote-tracking refs may already differ. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/cmd/sync.go#L127-L158 https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/internal/git/gitops.go#L196-L211 There is no blanket no-change guarantee to retain. The warning that zero does not establish synchronization, the comparison step, and both recovery routes remain; separate cascade rollback limits remain in the command reference. https://github.com/github/gh-stack/blob/b1bfce9e51d0cd92fc23efd6ecb37ff68139e7db/skills/gh-stack/references/commands.md#L118-L120
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The documentation omits that -A or -u without -m creates a commit via the Git editor, which can block or fail unattended runs.
1 open issue
What changed in this PR
Updates gh-stack’s public and agent-facing documentation to match existing CLI behavior, without changing runtime code.
Changes:
- Corrects exit-code guidance for multiple-stack ambiguity.
- Removes the false
-mrequirement fromaddstaging-flag descriptions. - Removes divergence-stop no-change guarantees and clarifies PR-template precedence during automatic submission.
| File | Description |
|---|---|
skills/gh-stack/SKILL.md |
Removes the no-change guarantee for divergent syncs. |
skills/gh-stack/references/troubleshooting.md |
Corrects divergence-stop wording while retaining the exit-status warning. |
skills/gh-stack/references/commands.md |
Updates staging requirements and nonempty PR-template precedence. |
README.md |
Removes incorrect staging-flag message requirements. |
docs/src/content/docs/reference/cli.md |
Aligns staging-flag descriptions with supported behavior. |
AGENTS.md |
Limits exit-code 6 guidance to multiple-stack ambiguity. |
Review effort: Max
| immediately after `init` — instead of creating a branch. This is deliberate: the first layer | ||
| usually needs its content before a second layer exists. | ||
| - `-A` and `-u` are mutually exclusive, and both require `-m`. | ||
| - `-A` and `-u` are mutually exclusive. |
This branch has not been deployed
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.

🧠 How this helps Copilot
Copilot could choose the wrong recovery for ambiguous remotes or rule out supported staging workflows because the guidance assigns the wrong exit code and requires an inline commit message. Correcting those expectations and removing the false message requirement across the command references avoids those mistaken choices.
An unattended agent could also mistake a successful divergence stop for unchanged local fetch state, or assume automatic submission will use commit prose despite an overriding PR template. Removing the no-change guarantees and describing the nonempty-template condition makes those outcomes clearer without changing runtime behavior.
Review commit by commit for each change's rationale and evidence.
Note
Copilot Dreaming curates this repository's Copilot instructions and skills in the background, proposing updates to help agents work here. Learn more about Copilot Dreaming.
Automated details
Source:
curate-memoriesDream, analyzingmainatb1bfce9.Discarded guidance: Existing test-style guidance remains unchanged because the conflicting prescriptions could not be resolved. Navigation and rerere changes are withheld rather than repeat earlier wording challenged for transient queued state and conditional configuration; their current text is unchanged.