Content
92%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A dense, highly actionable reference for a complex CLI tool: executable commands, explicit error-recovery paths, and well-signaled one-level-deep references with task-matched triggers. The only weakness is a handful of convoluted sentences in the Constraints section that read like compressed release notes and could be untangled.
Suggestions
Rewrite the Constraints bullet on `modify` into shorter sentences with named subjects (e.g. separate 'running actions', 'preserved branches/worktrees', and 'recovery' into distinct bullets), since the current phrasing ('Recovery flags may run from any worktree and use recorded native operation owners') requires multiple rereads.
Clarify the worktree bullet in Non-interactive use by stating concretely what `--print-path` returns and what 'a foreign-owned branch' means in practice, or by moving the worktree-catalog details into references/commands.md and keeping only the safe pattern inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and tool-specific throughout — the TTY-branching rules, always-run/never-run table, and exit-code semantics are facts Claude cannot know, with no padding or explanation of known concepts. A few sentences, mainly the Constraints bullets on modify/worktrees ("Recovery flags may run from any worktree and use recorded native operation owners..."), are convoluted and could be tightened. | 4 / 5 |
Actionability | Fully executable guidance throughout: copy-paste setup commands, the init/add/submit core loop, merge invocations, and a per-exit-code recovery column with exact commands (`gh stack rebase --continue`, `gh stack unstack --local`) covering the common cases. | 5 / 5 |
Workflow Clarity | Multi-step workflows are explicitly sequenced (core loop, edit workflow: down → edit → rebase --upstack → top → push) with a validation checkpoint (`gh stack view --json # confirm`) and explicit error-recovery feedback loops (exit-code table, Exit 3 resolve→continue/abort procedure). Destructive/batch operations (merge, sync --prune) are covered by all-or-nothing semantics, --yes flagging, and exit-code handling. | 5 / 5 |
Progressive Disclosure | The body is a genuine overview and all three references (stack-design.md, commands.md, troubleshooting.md) exist, are one level deep, and each carries a clear task-matched trigger ("read before creating a stack", "read when a command fails unexpectedly", "read on a rebase conflict"), with explicit guidance not to preload them. | 5 / 5 |
Total | 19 / 20 Passed |