Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

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

Copy link
Copy link
@dgolombek

Description

@dgolombek
Issue body actions

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
Reactions are currently unavailable

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

      Morty Proxy This is a proxified and sanitized view of the page, visit original site.