managing-stacked-changes

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Managing Stacked Changes

Use `wt-stack` to manage dependent review units as branches in sibling
worktrees. Git remains the source of truth for branches and worktrees. GitHub
remains the source of truth for pull requests and the remote Stack.

## Choose a Stack

Use a Stack when the task contains two or more ordered changes that reviewers
could understand and merge independently. Plan the review units from bottom to
top. Each later unit must depend on the branch immediately below it.

Good Stack boundaries include:

- A refactor followed by behavior that uses it.
- An API or schema followed by consumers or migration.
- Infrastructure followed by application adoption.
- A foundation followed by separate integrations.

Keep one branch for one coherent review unit, regardless of its file count. Give
independent changes separate branches based on the trunk branch.

## Verify prerequisites

Start from a task-specific worktree selected through the `using-git-worktrees`
skill. Inspect the repository before changing Stack state:

```console
git status --short --branch
git worktree list
wt-stack --version
wt-stack doctor
```

Treat `wt-stack` as installed and use v0.6.0 or newer. If the shell reports
`command not found`, or the installed version is older, install it from the
prompts repository:

```console
mise trust ~/src/personal/prompts/main/apps/wt-stack/mise.toml
mise -C ~/src/personal/prompts/main/apps/wt-stack install
mise run -C ~/src/personal/prompts/main/apps/wt-stack :install
wt-stack --version
```

Resume the prerequisite checks after installation. If authentication is
unavailable or GitHub Stacks support is disabled for the repository, continue
with the normal single-branch workflow and report that capability as a
consideration.

Treat existing dirty work in any worktree as user-owned. Stack mutations that
rebase require every active worktree to be clean.

## Plan the review units

Choose a short Stack name and one branch name per review unit. Include the
ticket identifier when one exists. Record the intended order before creating
branches:

```text
Stack: EE-1234-delivery
1. EE-1234/api
2. EE-1234/consumer
```

Keep each branch limited to its review unit. A branch should build and test
against the branch directly below it.

## Start a new Stack

Create the bottom branch and task worktree with the `using-git-worktrees` skill.
From that worktree, verify prerequisites and adopt the branch:

```console
wt-stack init --name <stack>
```

`init` discovers the selected remote's default branch. Use `--remote <remote>`
to select another remote or `--base <branch>` for an intentional base override.
If discovery fails, inspect the remote configuration instead of assuming `main`.

Implement and commit the bottom review unit before creating the next branch.
`add` bases the new branch on the current active Stack tip:

```console
wt-stack --stack <stack> add <next-branch>
wt-stack --json --stack <stack> status
```

Change into the worktree reported by `status`, implement the next review unit,
and commit it through the `creating-commits` skill. Repeat `add` from bottom to
top.

To adopt an existing linear chain, ensure each branch is checked out in a
sibling worktree and list the branches from bottom to top:

```console
wt-stack init --name <stack> <bottom-branch> <next-branch>
```

Do not rewrite published history solely to convert existing work into a Stack.
Ask before restructuring branches that other people may already use.

## Commit and publish

Treat publication as a separate phase from implementation. Immediately before
the first or delayed publication, re-read the `creating-commits` and
`creating-pull-requests` skills. Re-read them again when the conversation was
compacted or the user redirected the task after they were last read.

Prepare the final unwrapped pull request title and body for every unpublished
branch before committing or syncing. Check each body against the publication
checklist in `creating-pull-requests`, then derive the branch tip's commit title
and wrapped body from it. `wt-stack` uses the tip commit to initialize a missing
pull request; that generated description is not the final publication step.

Preview the complete mutation, then publish:

```console

From chadxz/prompts, MIT.

More from chadxz/prompts