Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: document --yes scope and non-interactive hint patterns (#1668)

Maximilian Roosae40ea230ca7
diff --git a/.claude/skills/writing-user-outputs/SKILL.md b/.claude/skills/writing-user-outputs/SKILL.md
index 9aaedc245..373bbaf70 100644
--- a/.claude/skills/writing-user-outputs/SKILL.md
+++ b/.claude/skills/writing-user-outputs/SKILL.md
@@ -459,6 +459,44 @@ Use `suggest_command()` from `worktrunk::styling` for proper shell escaping.
**Section titles:** For sectioned output (`wt hook show`, `wt config show`), use
`format_heading()` from `worktrunk::styling` (documented above).
+## Interactive Prompts vs Non-Interactive Hints
+
+Prompts and hints serve different purposes and have different `--yes` behavior.
+
+**Prompts** are expected steps in a workflow — the user ran a command knowing
+it would ask for confirmation. Hook approval during `wt merge`, config update
+confirmation, shell install confirmation. `--yes` bypasses these because the
+user anticipated the question and wants to pre-answer it (e.g., in CI).
+
+**Setup prompts** are unexpected — the user ran `wt merge` and got asked about
+LLM config or shell integration they didn't know about. `--yes` must NOT
+bypass these. A user passing `--yes` to skip hook approval did not consent to
+auto-configuring their shell. In non-interactive mode (no TTY), these should
+degrade to a hint or be skipped silently — never error.
+
+| Type | Example | `--yes` | Non-TTY behavior |
+|------|---------|---------|------------------|
+| Workflow prompt | Hook approval, config update | Bypasses | Error (`NotInteractive`) |
+| Setup prompt | LLM config, shell integration | No effect | Hint or silent skip |
+
+**Non-TTY degradation patterns:**
+
+- **Hint** — when the user benefits from knowing about the option on every run.
+ Shell integration hint: `↳ To enable automatic cd, run wt config shell install`
+- **Silent skip** — when a hint would be noise. Commit generation setup prompt
+ skips silently because a separate fallback hint (`emit_hint_if_needed`)
+ already covers the unconfigured case on every commit.
+- **Error** — only for workflow prompts where proceeding without consent is
+ unsafe (hook approval). The error includes a hint for the fix:
+ `↳ To skip prompts in CI/CD, add --yes`
+
+**Key invariants:**
+
+- Hints shown in non-TTY mode must NOT set skip flags — hints are not prompts,
+ and should repeat on every non-TTY run
+- `--yes` means "I anticipated this prompt" — it applies to workflow prompts
+ the user chose to invoke, not to setup/config discovery prompts
+
## Blank Line Principles
**Core principle:** When presenting the user with text to read and consider, add