From 98e7cb68da90cea4008e26ba923030ca7156831e Mon Sep 17 00:00:00 2001 From: William Thorsen Date: Wed, 1 Jul 2026 05:32:45 -0700 Subject: [PATCH] agents|feat: Add the concision spine and wire ticket and review gates Introduces a single canonical concision principle that agents apply while composing any reader-facing text. The principle that detail adds value up to a point, then taxes the reader, now reaches the always-loaded ambient guidance in short form; the doctrine governing code comments, changelog ledes, tickets, review findings, and review comments each points to it. Ticket and review-comment authoring now default to the tight altitude at compose time: ticket guidance leads with a minimal skeleton whose non-essential sections are opt-in, and review findings carry a compose-time concision gate that reaches both the interactive and orchestrated review paths. --- .../agents/content/guidance/shared/AGENTS.md | 6 ++++- .../skills/_data/artifact-conventions.md | 2 ++ .../skills/_data/comment-discipline.md | 2 +- .../agents/content/skills/_data/concision.md | 23 +++++++++++++++++++ .../agents/content/skills/_data/lede-voice.md | 2 ++ .../skills/_partials/ticket-concision.md | 7 ++++++ .../content/skills/review-criteria/SKILL.md | 4 ++++ 7 files changed, 44 insertions(+), 2 deletions(-) create mode 100644 packages/agents/content/skills/_data/concision.md diff --git a/packages/agents/content/guidance/shared/AGENTS.md b/packages/agents/content/guidance/shared/AGENTS.md index 16b40e8f..b1878b04 100644 --- a/packages/agents/content/guidance/shared/AGENTS.md +++ b/packages/agents/content/guidance/shared/AGENTS.md @@ -36,6 +36,10 @@ Examples: Capitalize the first word after a colon, unless the colon falls mid-sentence and introduces a fragment or list. +## Concision + +Detail adds value up to a peak, then taxes the reader and buries the signal. Compose tight from the start: Lead with the minimal skeleton and add a sentence only when it changes what the reader does. Never drop a decision, constraint, or actionable fact for brevity. If you find yourself trimming, you started too loose. Full principle: `_data/concision.md` in the agents skills tree. + ## Prompt formatting When prompting the user for input, never use interactive UI controls (pop-up, arrow-key, or structured-choice selectors); use plain text, with options as a numbered list. Use visual markers to make prompts more noticeable: @@ -59,7 +63,7 @@ Examples: ## Code descriptions -- Every non-trivial function, method, class, and component gets a brief description. Favor concision, but prioritize communicating the essential information. +- Every non-trivial function, method, class, and component gets a brief description. - Do not repeat information the signature already provides (parameter names, types, return types). In languages with doc-tag conventions (`@param`, `@returns`, `:param`, `Args:`, etc.), omit them — the description alone is sufficient. - Trivial code (simple getters, one-line helpers whose name fully describes their behavior) may omit the description. diff --git a/packages/agents/content/skills/_data/artifact-conventions.md b/packages/agents/content/skills/_data/artifact-conventions.md index 4008e814..08c85d60 100644 --- a/packages/agents/content/skills/_data/artifact-conventions.md +++ b/packages/agents/content/skills/_data/artifact-conventions.md @@ -761,6 +761,8 @@ Every finding (F/W/T/R/S) must hand the author a concrete decision they can act A finding's cost is a cascade, not a line: the reader's time, the tokens spent asking you to reconsider it, the author's triage, and every later reader who reads both the finding and its rejection. Treat emitting any finding as carrying a burden of proof, weighed against that full cost, never against its line length. +This gate is the [concision principle](./concision.md) applied to findings: A finding, like any detail, taxes every reader once its cost outweighs the decision it enables. + **Hedging language is a delete trigger, not a softening device.** If a finding's own body qualifies it out of relevance, it does not belong. Drop it. If the condition genuinely holds now, drop the qualifier instead and state the finding plainly. Disqualifying tells include: - "No action this PR / no action required / not actionable here" diff --git a/packages/agents/content/skills/_data/comment-discipline.md b/packages/agents/content/skills/_data/comment-discipline.md index 44718bde..fa0a7260 100644 --- a/packages/agents/content/skills/_data/comment-discipline.md +++ b/packages/agents/content/skills/_data/comment-discipline.md @@ -8,7 +8,7 @@ The reader is the engineer six months later who has no chat transcript, no sessi ## The principle -Comments are written for the future reader, not the recent conversation. +Comments are written for the future reader, not the recent conversation. This is the [concision principle](./concision.md) applied to code comments; the deletion rules below are its comment-specific cut-list. Detail is routed, not omitted: diff --git a/packages/agents/content/skills/_data/concision.md b/packages/agents/content/skills/_data/concision.md new file mode 100644 index 00000000..61049a0c --- /dev/null +++ b/packages/agents/content/skills/_data/concision.md @@ -0,0 +1,23 @@ +# Concision + +Detail adds value up to a peak, then taxes the reader: Past the peak, added detail buries the signal it was meant to carry. Add detail only while it adds signal. Weigh each sentence by the signal it carries, not its length. + +## Compose tight the first time + +Compose from a skeleton, not a full draft you trim later. Start with the one sentence the reader cannot act without, then add only what changes what they do next. If you find yourself trimming, you started too loose. + +## Proportionality + +A load-bearing decision earns elaboration; a routine one earns a clause. A decision is load-bearing if the reader could act differently depending on it. + +## What to cut + +Intros, hedging, restated context, exhaustive enumeration. Process narration (how the work or decision was reached) when only the conclusion serves the reader. + +## Self-test + +For each sentence, ask: Would removing it change what the reader does, or must know to act? If not, cut it. Run this before presenting, not after a reader complains. + +## Cut noise, never signal + +This overrides the cut-list and self-test: Never drop a decision, constraint, or actionable fact for brevity, even when they would remove it. Detail is routed, not omitted: Each artifact's doctrine names where cut detail belongs. diff --git a/packages/agents/content/skills/_data/lede-voice.md b/packages/agents/content/skills/_data/lede-voice.md index d68673e3..e959b5af 100644 --- a/packages/agents/content/skills/_data/lede-voice.md +++ b/packages/agents/content/skills/_data/lede-voice.md @@ -19,6 +19,8 @@ The tier shifts the register; it does not lower the bar. The glancing-reader fra ## The principle +This is the [concision principle](./concision.md) applied to changelog and release-notes entries; the routing and rules below are its lede-specific form. + **Detail is routed, not omitted.** The PR is one click away and carries the full story (ticket, diff, `## Details`). Putting implementation detail in the entry isn't thoroughness — it's information in the wrong channel, and it makes the entry less likely to be read at all. Cutting a sentence from the entry doesn't lose the information; it puts the information where it belongs: - Mechanism, internal naming, and refactor mechanics → `## Details` (the PR carries this). diff --git a/packages/agents/content/skills/_partials/ticket-concision.md b/packages/agents/content/skills/_partials/ticket-concision.md index 5ebc7274..38056cb1 100644 --- a/packages/agents/content/skills/_partials/ticket-concision.md +++ b/packages/agents/content/skills/_partials/ticket-concision.md @@ -1,3 +1,10 @@ +Start from this skeleton. Add a section only when it carries signal the reader must act on. + +- **Problem** and **Acceptance criteria (Must have)**: always present. +- **Context**, **Proposed solution** (including "X, not Y"), and **Should have / Nice to have**: opt-in, added only when they earn their place. Omit empty tiers. + +This applies the [concision principle](../_data/concision.md) to tickets. + **Write the tightened ticket, not a draft to be tightened later.** A ticket is the minimal contract a reader needs, not a transcript of the design session. Compose the maximally tight version that still carries the full meaning; length is earned by content, not by a completeness instinct. (Producing the tight version up front spares the reader, and spares everyone the tighten-on-request round trip.) State conclusions, not the journey to them. Naming a chosen approach — including "X, not Y" — is a durable decision and belongs in the ticket. The _story_ of how the decision was reached does not: drop the design back-and-forth, the false starts, restated context, and motivating episodes. diff --git a/packages/agents/content/skills/review-criteria/SKILL.md b/packages/agents/content/skills/review-criteria/SKILL.md index c12e1b65..150e2ece 100644 --- a/packages/agents/content/skills/review-criteria/SKILL.md +++ b/packages/agents/content/skills/review-criteria/SKILL.md @@ -44,6 +44,10 @@ Findings use the canonical [finding scheme](../_data/artifact-conventions.md#fin Before emitting any F/W/T/R/S finding, confirm it hands the author a concrete decision they can act on **in this change**: fix, defer with a ticket, or explicitly accept. Hedging language inside a finding ("no action this PR", "not actionable here", "just capturing a thought", "call it out only if X", "would matter once Y") is your own signal that it does not belong; drop it, don't soften it. A finding that endorses the current state and then proposes a change anyway is incoherent; drop it. Self-test: _would I make this exact change right now if it were my code?_ If no, it is not a finding. Apply this hardest to R and S. Full treatment, including where dropped content goes: [finding scheme § Actionability gate](../_data/artifact-conventions.md#actionability-gate). +## Finding concision + +Compose each finding at the tight altitude ([concision principle](../_data/concision.md)): State the defect, its location, and the decision the author must make, then stop. Cut code the author can already see, hedged narration, and rationale for why you looked. Every reader pays for each line, so weigh each sentence against the decision it enables, not its completeness. + ## Finding references Conventions for how findings reference files and code locations.