@staff0rd/assist 0.416.0 → 0.418.0

package/README.md

@@ -100,7 +100,7 @@ After installation, the `assist` command will be available globally. You can als
 - `assist commit <message> [files...]` - Stage files and create a git commit with validation
 - `assist branch <slug> [--jira <key>]` - Create and switch to a new branch off the fresh remote default branch. Assembles the name as `[<prefix>/][<JIRA>-]<slug>` (prefix from the optional `branch.prefix` config, Jira key used verbatim), fetches and branches from `origin/<default>` (resolved live from the remote, falling back to `main`, overridable via `branch.defaultBranch`), and rejects slugs whose numeric tokens look like backlog IDs. A long free-text slug is first shortened to a concise, LLM-assisted kebab-case name (falling back to a word-boundary trim if the model is unavailable) so branch names stay brief
 - `assist prs` - List pull requests for the current repository
-- `assist prs raise --title <title> --what <what> --why <why> [--how <how>] [--resolves <key>] [--force]` - Raise a pull request, assembling the body from `## What`, `## Why` (with `--resolves` Jira URLs appended inline), and an optional `## How`; errors if a PR already exists unless `--force` overwrites its title and body
+- `assist prs raise --title <title> --what <what> --why <why> [--how <how>] [--resolves <key>] [--force]` - Raise a pull request, assembling the body from `## What`, `## Why` (with `--resolves` Jira URLs appended inline), and an optional `## How`. When run inside an assist web session, the drafted title and body are shown in a 50/50 preview pane beside the terminal for approve/reject before the PR is created or updated (the command blocks until you decide; rejecting exits non-zero); in a plain terminal it places the PR directly, erroring if one already exists unless `--force` overwrites its title and body. Run `assist prs raise --help` for full authoring guidance (which itself adapts to the terminal-vs-web context)
 - `assist prs edit [--title <title>] [--what <what>] [--why <why>] [--how <how>] [--resolves <key>]` - Update only the supplied sections of the current branch's pull request, preserving every other section of its body
 - `assist prs list-comments` - List all comments on the current branch's pull request
 - `assist prs fixed <comment-id> <sha>` - Reply with commit link and resolve thread

package/claude/commands/pr.md

@@ -2,70 +2,4 @@
 description: Raise a PR with a concise description
 ---
 
-Raise a pull request for the current branch. Use a concise description with no headers. Do not reference Claude or any AI assistance in the title or body.
-
-Use `assist prs raise` to create the PR — do not use `gh pr create` directly. The body is assembled from discrete section options; supply at minimum `--title`, `--what`, and `--why`:
-
-- `--title <title>` — short PR title.
-- `--what <what>` — what the change does (rendered as `## What`).
-- `--why <why>` — why the change is needed (rendered as `## Why`).
-- `--how <how>` — optional; how the change works (rendered as `## How`). Omit it unless the approach genuinely needs explaining.
-- `--resolves <key>` — Jira issue key resolved by this PR; repeatable. Each key's browse URL is appended inline to the `## Why` section. Unless a Jira key is already known from the session (e.g. mentioned by the user or present on the branch), ask the user whether this PR resolves a Jira issue and for the key before raising; omit `--resolves` only if they say there isn't one.
-
-Wrap symbols, file paths, function names, class names, variable names, config keys, CLI commands, and flag names in backticks.
-
-One section, one question. Each section answers exactly one thing, and implementation detail lives only in `## How`:
-
-- `## What` — what is observably different for someone using or calling this, and nothing else. Not how it's built, not which functions/files changed.
-- `## Why` — the problem or motivation that made the change worth doing. Not how the solution works.
-- `## How` — only the non-obvious decisions the diff alone won't explain: a deliberate trade-off, a workaround, a reason the obvious approach was rejected. Omit it entirely by default. Never restate `## What` as mechanism, and never walk through the diff.
-
-The most common failure is altitude bleed: the author has an implementation detail they want to include, so they spray it into whichever section they're writing — `## What` narrates the diff, `## How` restates `## What`, `## Why` smuggles in mechanism. Don't. If a sentence describes a mechanism, it belongs in `## How` — and probably shouldn't exist at all unless it's a genuine non-obvious decision.
-
-Litmus — a sentence is almost certainly mechanism (so `## How`, or cut it) if it contains "by …ing", "so that it can", "because the X filters/needs/uses", or names an internal component, property, function, or file.
-
-Brevity budget — keep each section within these limits:
-
-- `## What` — a few sentences (2–3).
-- `## Why` — 1–2 sentences.
-- `## How` — omit by default; a sentence or two, only for non-obvious decisions, not a diff walkthrough.
-
-Write prose. A short paragraph of a few sentences is the natural form for `## What` and `## Why` — bullets in `## What` are a smell, usually a sign the change is being narrated point-by-point like a diff. Use bullets only when there are genuinely several independent, parallel items (3+) that don't read as a paragraph; a single bullet is never right — make it a sentence. Don't pack multiple points into one long running paragraph either: a single non-list paragraph over ~600 characters or ~4 sentences is a wall of text and `assist prs raise`/`assist prs edit` will reject it.
-
-Worked example — altitude bleed across every section.
-
-Bad — mechanism leaks everywhere:
-
-> ## What
->
-> Adds a `RetryPolicy` wrapper that catches transient errors and re-invokes the handler with exponential backoff so callers don't see intermittent failures.
->
-> ## Why
->
-> Intermittent failures were surfacing to users. The handler also needs to distinguish transient from permanent errors, which the new `isTransient` check does by inspecting the status code.
->
-> ## How
->
-> The wrapper retries with exponential backoff on transient errors.
-
-`## What` describes the implementation (a wrapper, backoff) rather than the observable change. `## Why`'s second sentence is mechanism dressed as motivation. `## How` just restates `## What` at a lower altitude. Good — each section stays at its own altitude:
-
-> ## What
->
-> Intermittent failures are now retried automatically instead of surfacing to the user.
->
-> ## Why
->
-> Transient errors were failing requests that would have succeeded on a second attempt.
->
-> ## How
->
-> Only errors flagged transient are retried; permanent failures still fail fast, to avoid masking real bugs behind retries.
-
-Only the genuinely non-obvious decision survives in `## How`; everything that merely paraphrased `## What` is gone.
-
-`assist prs raise` errors if a pull request already exists for the branch. Pass `--force` to fully overwrite the existing PR's title and body.
-
-To update an existing PR, use `assist prs edit` with the same section options (`--title`/`--what`/`--why`/`--how`/`--resolves`). Only the sections you pass are replaced; every other section of the existing body is preserved. Passing `--resolves` without `--why` keeps the existing `## Why` text and refreshes its appended Jira URLs; passing `--why` without `--resolves` replaces the prose but keeps the existing `Resolves` links.
-
-Before creating the PR, the user must see the full proposed title and body — do not assume they can see your reasoning or earlier tool output. Write the complete title and body verbatim in your visible reply, then use the AskUserQuestion tool to ask whether to create the PR, putting the full title and body in the approve option's `preview` field so the dialog itself displays them. This confirmation is mandatory in every permission mode, including auto-accept and bypass-permissions — never run `assist prs raise` until the user has explicitly approved the title and body through AskUserQuestion. If the user requests changes, revise and confirm again before creating.
+Run `assist prs raise --help` and follow its guidance exactly to compose and raise the pull request for the current branch. The help text is authoritative — it covers the section options, how to pitch each section, and whether to confirm the title and body in the terminal or leave that to the web UI. Do not use `gh pr create` directly.