Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion packages/agents/content/guidance/shared/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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.

Expand Down
2 changes: 2 additions & 0 deletions packages/agents/content/skills/_data/artifact-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion packages/agents/content/skills/_data/comment-discipline.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
23 changes: 23 additions & 0 deletions packages/agents/content/skills/_data/concision.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 2 additions & 0 deletions packages/agents/content/skills/_data/lede-voice.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
7 changes: 7 additions & 0 deletions packages/agents/content/skills/_partials/ticket-concision.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
4 changes: 4 additions & 0 deletions packages/agents/content/skills/review-criteria/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading