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 tightly written operational guide: dense tool-specific rules (worktree resolution, two config scopes, the approvals security model), copy-paste commands with annotated good/bad examples, workflows with explicit verification steps, and a task-indexed set of one-level-deep references. The only slack is mild repetition inside the hook-approvals section, where the trust rationale is stated three times over.
Suggestions
Trim the repeated trust rationale in 'Hook approvals in non-interactive sessions': 'an untrusted `.config/wt.toml` cannot silently execute anything' and 'neither is a shortcut for an interactive agent to silence an approval prompt' each restate the point of the immediately preceding sentences — state it once and cut the restatements.
Deduplicate the approvals persistence detail: 'Run once per project; the approval persists across invocations until the command template changes or the project moves' repeats the earlier 're-prompted whenever a command template changes or the project moves' — keep one formulation.
In the same section, the opening three sentences ('Worktrunk never runs a project's hooks...' → 'an untrusted `.config/wt.toml` cannot silently execute anything') can be compressed to two: the mechanism (per-command approval on first run) plus the reason (arbitrary shell code from a freshly cloned repo).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and example-driven with no tutoring on concepts Claude already knows (no 'what is a worktree' padding), but the 'Hook approvals in non-interactive sessions' section restates its point several times: "an untrusted `.config/wt.toml` cannot silently execute anything" repeats the section's opening two sentences, "neither is a shortcut for an interactive agent to silence an approval prompt" repeats the preceding sentence, and "Run once per project; the approval persists across invocations until the command template changes or the project moves" duplicates "re-prompted whenever a command template changes". These are minor instances of over-explanation that could be trimmed (anchor 4), not 'every token earns its place' (anchor 5); it is well above anchor 3 ('some unnecessary explanation') since the repetition is confined to one deliberately emphatic security section. | 4 / 5 |
Actionability | Fully executable, copy-paste-ready guidance throughout: `wt step diff --branch beta` / `wt -C ../repo.beta step diff --branch beta` with ✓/✗ annotations for the targeting rules; `which claude codex opencode llm aichat`; `wt step commit --dry-run` as the verification step; complete TOML hook blocks for both pipeline and concurrent forms; `wt switch --create test-hooks`; `wt config approvals add`; `wt switch --create <branch> --no-cd`; and a literal sub-Agent prompt template ("You are working in `/abs/path/to/myproject.<branch>`..."). Specific examples cover the common cases — matching the anchor-5 example rather than anchor 4's 'minor gaps'. | 5 / 5 |
Workflow Clarity | The two core workflows are clearly sequenced with explicit validation checkpoints: commit-message generation runs detect → propose the `[commit.generation]` change → apply after approval → "verify... `wt step commit --dry-run` renders the prompt, runs the LLM, and prints the message without committing"; hook configuration runs pick hook type by timing → derive commands from project files (package.json/Cargo.toml/pyproject.toml) → "verify they run before adding them" → "Test with `wt switch --create test-hooks`". The approvals section is a complete error→diagnosis→resolution loop, showing the literal error output and correctly steering the agent to escalate rather than use either `--yes` path. Checkpoints are present (not merely 'most'), so anchor 5 fits better than anchor 4. | 5 / 5 |
Progressive Disclosure | The body is an overview with well-signaled, one-level-deep references: an "Available documentation" index annotating each file ("reference/config.md: User and project configuration (LLM, hooks, command defaults)" ... "reference/extending.md: Aliases, multi-step pipelines, custom subcommands, and template-expansion gotchas"), plus a "Common tasks reference" mapping tasks to files with section anchors (`reference/extending.md#aliases`, `reference/config.md#worktree-path-template`, `reference/llm-commits.md#prompt-templates`). No nested reference chains; detail is appropriately split out. (No bundle files were present in the review directory to verify the `reference/*.md` files exist, so this is scored on the body's reference structure alone.) This matches the anchor-5 'clear overview with well-signaled one-level-deep references; easy navigation' better than anchor 4's 'minor organization gaps'. | 5 / 5 |
Total | 19 / 20 Passed |