@staff0rd/assist 0.293.0 → 0.294.1

package/claude/commands/pr.md

@@ -12,9 +12,57 @@ Use `assist prs raise` to create the PR — do not use `gh pr create` directly.
 - `--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.
 
-Keep each section to a brief plain-text summary. Wrap symbols, file paths, function names, class names, variable names, config keys, CLI commands, and flag names in backticks.
+Wrap symbols, file paths, function names, class names, variable names, config keys, CLI commands, and flag names in backticks.
 
-Write the description in terms of behaviour and user-facing impact: what the change does, what's different for someone using it, and why. Keep technical detail to a minimum — do not walk through the implementation approach step by step, and do not restate what is already obvious from the diff or changelog (which files changed, which functions were added). The reviewer can read the code; the description should tell them what to expect from the change, not narrate how it was built.
+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.
 

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@staff0rd/assist",
-  version: "0.293.0",
+  version: "0.294.1",
   type: "module",
   main: "dist/index.js",
   bin: {
@@ -11327,6 +11327,45 @@ ${resolves}` : baseWhy);
 }
 
 // src/commands/prs/validatePrContent.ts
+var MAX_PARAGRAPH_CHARS = 600;
+var MAX_PARAGRAPH_SENTENCES = 4;
+function isListLine(line) {
+  return /^\s*([-*+]|\d+[.)])\s/.test(line);
+}
+function countSentences(paragraph) {
+  return paragraph.match(/[.!?]+(\s|$)/g)?.length ?? 0;
+}
+function splitParagraphs(body) {
+  const paragraphs = [];
+  let section2 = "(intro)";
+  let lines = [];
+  const flush = () => {
+    if (lines.length > 0) {
+      paragraphs.push({ section: section2, lines });
+      lines = [];
+    }
+  };
+  for (const line of body.split("\n")) {
+    const heading = line.match(/^#{1,6}\s+(.*)$/);
+    if (heading) {
+      flush();
+      section2 = heading[1].trim();
+    } else if (line.trim() === "") {
+      flush();
+    } else {
+      lines.push(line);
+    }
+  }
+  flush();
+  return paragraphs;
+}
+function isWallOfText(lines) {
+  if (lines.some(isListLine)) {
+    return false;
+  }
+  const text3 = lines.join(" ").trim();
+  return text3.length > MAX_PARAGRAPH_CHARS || countSentences(text3) > MAX_PARAGRAPH_SENTENCES;
+}
 function validatePrContent(title, body) {
   if (title.toLowerCase().includes("claude")) {
     console.error("Error: PR title must not reference Claude");
@@ -11336,6 +11375,14 @@ function validatePrContent(title, body) {
     console.error("Error: PR body must not reference Claude");
     process.exit(1);
   }
+  const wall = splitParagraphs(body).find((p) => isWallOfText(p.lines));
+  if (wall) {
+    const chars = wall.lines.join(" ").trim().length;
+    console.error(
+      `Error: the "${wall.section}" section contains a wall-of-text paragraph (${chars} chars). Be concise \u2014 split it into bullet points or trim it.`
+    );
+    process.exit(1);
+  }
 }
 
 // src/commands/prs/edit.ts
@@ -14969,9 +15016,11 @@ function printReviewerFailures(results) {
 import { existsSync as existsSync38, unlinkSync as unlinkSync14 } from "fs";
 
 // src/commands/review/buildReviewerStdin.ts
-var REVIEW_PROMPT = `You are acting as a reviewer for a proposed code change made by another engineer. The full review request \u2014 branch, base, changed files, and unified diff \u2014 is in request.md in the current working directory.
+var REVIEW_PROMPT = `You are acting as a reviewer for a proposed code change made by another engineer. The full review request \u2014 branch, base, changed files, and unified diff \u2014 is in the request file whose absolute path is given below.
+
+Your working directory is the repository under review, so you can read any file in it for context beyond the diff.
 
-Read request.md, then produce a thorough code review in Markdown.
+Read the request file, then produce a thorough code review in Markdown.
 
 ## When to flag a finding
 
@@ -15007,7 +15056,7 @@ List every finding that the original author would want to know about and fix. Do
 
 For each finding include:
 - Severity (blocker, major, minor, nit) \u2014 see rubric below
-- File and line (e.g. \`src/foo.ts:42\`) when the finding is tied to a specific location. Take the line number from the diff's left gutter (its line in the new file); never count lines in request.md.
+- File and line (e.g. \`src/foo.ts:42\`) when the finding is tied to a specific location. Take the line number from the diff's left gutter (its line in the new file); never count lines in the request file.
 - Impact: what could go wrong, including the conditions under which it manifests
 - Recommendation: a concrete change
 
@@ -15411,11 +15460,9 @@ function parseCodexEvent(line) {
 }
 
 // src/commands/review/runCodexReviewer.ts
-function codexArgs(reviewDir, outputPath) {
+function codexArgs(outputPath) {
   return [
     "exec",
-    "--cd",
-    reviewDir,
     "--sandbox",
     "read-only",
     "--json",
@@ -15429,7 +15476,7 @@ async function runCodexReviewer(spec) {
   const result = await runStreamingChild({
     name: spec.name,
     command,
-    args: codexArgs(spec.reviewDir, spec.outputPath),
+    args: codexArgs(spec.outputPath),
     stdin: spec.stdin,
     quiet: Boolean(spinner),
     onLine: (line) => {
@@ -15453,7 +15500,6 @@ function resolveCodex(args) {
   const spinner = args.multi?.create("codex \u2014 starting");
   return runCodexReviewer({
     name: "codex",
-    reviewDir: args.reviewDir,
     stdin: args.stdin,
     outputPath: args.codexPath,
     spinner
@@ -15470,7 +15516,6 @@ async function runReviewers(reviewDir, claudePath, codexPath, stdinPrompt, optio
     multi: options2.multi
   });
   const codexPromise = resolveCodex({
-    reviewDir,
     codexPath,
     stdin: stdinPrompt,
     plan: options2.codexPlan,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@staff0rd/assist",
-	"version": "0.293.0",
+	"version": "0.294.1",
 	"type": "module",
 	"main": "dist/index.js",
 	"bin": {