gh-stack checkout: incorrect --remote usage and unsafe unstack recovery (v0.8) #312

Summary

Codex found two issues in the official gh-stack skill (v0.8) related to the checkout handler and its recovery instructions.

Details

• Line 58: The instructions say to use --remote, but gh stack checkout does not support a --remote flag. This is misleading and will cause errors for users following the guidance.

• Line 71: When checkout encounters a local/remote composition mismatch, the recovery runs gh stack unstack. The skill's own docs define gh stack unstack (without flags) as unstacking on GitHub and removing local tracking, whereas gh stack unstack --local preserves the GitHub stack and only clears local state. Running the bare gh stack unstack to recover from a local-state conflict can therefore dissolve collaborators' remote PR stack. The recovery should use --local (or explicitly instruct preserving the GitHub stack) before retrying checkout.

Steps to reproduce

1. Use gh-stack v0.8 and create a stack where local branch composition differs from the remote stack.
2. Run gh stack checkout and trigger the described local/remote composition mismatch.
3. Observe the recovery suggestion/behavior that runs gh stack unstack and how it affects the remote PR stack.

Suggested fix

• Remove or correct the --remote suggestion on Line 58 so it matches the CLI's supported flags.
• Change the recovery instruction on Line 71 to run gh stack unstack --local (or otherwise explicitly preserve the GitHub stack) so recovering local state does not delete collaborators' remote PR stack.

Impact

Following the current instructions can unintentionally remove collaborators' remote PR stack when attempting to clear local state, causing disruption and potential data loss.

Environment

• gh-stack skill v0.8 (as reported by Codex)

View original Slack conversation