Skip to content

docs(skill): four corrections for non-interactive agent guidance in SKILL.md #69

@dgolombek

Description

@dgolombek

Four small corrections to skills/gh-stack/SKILL.md (v0.0.2) for agents running non-interactively (i.e. always with --auto). Surfaced while reviewing the skill before installing it in a downstream agents repo.

I tried to open this as a PR from a fork but the repo's interaction settings restrict PR creation to collaborators. The full patch is at the bottom of this issue and also lives on a branch in my fork: https://github.com/dgolombek/gh-stack/tree/skill-doc-corrections-non-interactive. Happy to re-open as a PR if access is granted, or a maintainer can apply the patch directly.

The four corrections

1. gh stack unstackgh stack unstack --local in conflict-recovery paths (lines 72 & 781)

The agent rules section and the checkout command's agent warning both tell the agent to run gh stack unstack to clear local tracking state before retrying gh stack checkout <pr-number>. The intent in that scenario is to wipe local state only — but plain unstack also removes the stack grouping on GitHub. Net effect: the agent silently un-groups the PRs, and unless it remembers to follow up with gh stack submit --auto, the stack stays ungrouped on GitHub. --local does what the recovery path actually wants.

2. Exit code 9: add non-interactive fallback (line 836)

The current row says submit offers a regular-PR fallback "in interactive mode," but agents always run --auto. With the existing wording an agent hitting code 9 has no prescribed action and stalls. Updated to specify a non-interactive recovery path (gh stack push + per-branch gh pr create, or surface to the user).

3. Restructure workflow comment (line 383)

# Remove the stack (locally and on GitHub) can read as "deletes the PRs on GitHub." Conservative agents may halt before a safe operation. Clarified that only the stack grouping is removed; the PRs survive.

Patch

diff --git a/skills/gh-stack/SKILL.md b/skills/gh-stack/SKILL.md
index 0717dde..550102f 100644
--- a/skills/gh-stack/SKILL.md
+++ b/skills/gh-stack/SKILL.md
@@ -69,7 +69,7 @@ git config remote.pushDefault origin     # if multiple remotes exist (skips remo
 - ❌ `gh stack init` without branch arguments — always provide branch names
 - ❌ `gh stack add` without a branch name — always provide a branch name
 - ❌ `gh stack checkout` without an argument — always provide a PR number or branch name
-- ❌ `gh stack checkout <pr-number>` when a different local stack already exists on those branches — this triggers an unbypassable conflict resolution prompt; use `gh stack unstack` first to remove the local stack, then retry the checkout
+- ❌ `gh stack checkout <pr-number>` when a different local stack already exists on those branches — this triggers an unbypassable conflict resolution prompt; use `gh stack unstack --local` first to remove the local tracking state, then retry the checkout
 
 ## Thinking about stack structure
 
@@ -380,7 +380,7 @@ echo "$output" | jq '[.branches[] | .isMerged] | all'
 Use `unstack` to tear down the stack, make structural changes, then re-init:
 
 ```bash
-# 1. Remove the stack (locally and on GitHub)
+# 1. Remove the local stack tracking and the GitHub stack grouping (PRs are NOT deleted)
 gh stack unstack
 
 # 2. Make structural changes — e.g. delete a branch, reorder, rename
@@ -778,7 +778,7 @@ gh stack checkout feature-auth
 
 When a PR number is provided (e.g. `123`), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch.
 
-> **⚠️ Agent warning:** If the local and remote stacks have different branch compositions, this command triggers an interactive conflict-resolution prompt that cannot be bypassed with a flag. To avoid this: run `gh stack unstack` first to remove the conflicting local stack, then retry `gh stack checkout <pr-number>`.
+> **⚠️ Agent warning:** If the local and remote stacks have different branch compositions, this command triggers an interactive conflict-resolution prompt that cannot be bypassed with a flag. To avoid this: run `gh stack unstack --local` first to remove the conflicting local tracking state, then retry `gh stack checkout <pr-number>`.
 
 When a branch name is provided, the command resolves it against locally tracked stacks only. This is always safe for non-interactive use.
 
@@ -833,7 +833,7 @@ gh stack unstack feature-auth
 | 6 | Disambiguation required | A branch belongs to multiple stacks. Run `gh stack checkout <specific-branch>` to switch to a non-shared branch first |
 | 7 | Rebase already in progress | Run `gh stack rebase --continue` (after resolving conflicts) or `gh stack rebase --abort` to start over |
 | 8 | Stack is locked | Another `gh stack` process is writing the stack file. Wait and retry — the lock times out after 5 seconds |
-| 9 | Stacked PRs unavailable | The repository does not have stacked PRs enabled. `submit` will offer to create regular (unstacked) PRs in interactive mode |
+| 9 | Stacked PRs unavailable | The repository does not have stacked PRs enabled. `submit` will offer to create regular (unstacked) PRs in interactive mode. In non-interactive mode: fall back to `gh stack push` to push branches, then `gh pr create` per branch to open individual (non-stacked) PRs, or inform the user that stacks must be enabled on the repository first. |
 
 ## Known limitations

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions