feat: make human-facing output concise

AGENTS.md

@@ -13,6 +13,15 @@ benchmark baseline. Neither is a daemon, queue, general workflow runtime, or
 license to restore the removed runtime experiments. Do not reconstruct other
 runtime machinery from Git history unless the user explicitly requests it.
 
+## Writing style
+
+- Lead with the result and the next action.
+- Use familiar words, active voice, and short sentences and paragraphs.
+- Explain a necessary Darrow term the first time it appears.
+- Remove repetition and unnecessary process narration.
+- Preserve technical meaning, safety rules, evidence, exact commands and
+  identifiers, and required protocol fields while simplifying prose.
+
 Before changing plugin boundaries, the orchestration model, or the relationship
 between capabilities and orchestration, read [`docs/design.md`](docs/design.md).
 

README.md

@@ -7,8 +7,7 @@
 <a id="why-darrow"></a>
 
 Darrow is a marketplace of focused, eval-tested plugins for Codex and Claude
-Code. It is for developers who want repeatable Git, review, planning, and
-implementation skills while choosing what to adopt.
+Code. Choose only the Git, review, planning, or implementation help you need.
 
 Install one plugin at a time. Capabilities match your request; orchestration
 starts only when explicitly invoked and uses a host-native execution owner.

docs/choosing-plugins.md

@@ -1,9 +1,8 @@
 # Choose Darrow plugins
 
-Start with the work you want the agent to do. Install one matching plugin,
-try it on a small request, and add another when a new need appears.
-A plugin is an independently adoptable package; installing one does not require
-the other layers. Its README owns its prerequisites, behavior, and safety rules.
+Start with the work you want done. Install one matching plugin and try it on a
+small request. Add another only when a new need appears. Each plugin stands
+alone; its README owns its prerequisites, behavior, and safety rules.
 
 ## Choose by intent
 

docs/documentation-quality.md

@@ -3,6 +3,22 @@
 Use this contract with the [contributor guidance](../CONTRIBUTING.md). Pages
 serve one primary reader need; the static spine must work without the guide.
 
+## Plain-language standard
+
+Lead with the answer, outcome, or next action. Put supporting detail after it.
+Use familiar words and active voice. Keep sentences and paragraphs short, and
+explain a necessary Darrow term when it first appears.
+
+Remove repetition, throat-clearing, and narration about how the writer reached
+the result. Do not remove technical meaning, safety rules, evidence, exact
+commands and identifiers, prerequisites, recovery steps, or required protocol
+fields. When full evidence is long, summarize the outcome first and retain the
+evidence in later sections or link to its readable source.
+
+Historical research and retained eval results are evidence records. Do not
+rewrite their observations to match current style. Improve their summaries,
+indexes, and links instead.
+
 ## Plugin README contract
 
 Keep local behavior and safety knowledge in the plugin. Each README needs a
@@ -48,6 +64,8 @@ External link checks do not establish that a source's claims are correct.
   and contributing from the landing page without guessing?
 - Does each page answer one reader need in plain language, with short paragraphs
   and terms defined or linked in the glossary?
+- Does it lead with the result or next action, use active voice, and avoid
+  repeated points or unnecessary process narration?
 - Do headings form a meaningful hierarchy, without skipped levels or labels
   that make sense only in context?
 - Do links describe their destination when read alone? Avoid “click here”.
@@ -62,6 +80,8 @@ External link checks do not establish that a source's claims are correct.
   mutation effects, and the actual supported hosts explicit?
 - Did contraction preserve authoritative rules and unique safety knowledge,
   with question mappings and passing cross-host evidence for each removal?
+- When detail is long, is the outcome easy to find without hiding or dropping
+  the complete evidence?
 
 The [layer explanation](choosing-plugins.md#understand-the-layers) supplies the
 long description for the landing-page diagram. Preserve its SVG title and

docs/getting-started.md

@@ -41,13 +41,14 @@ The readiness gate should return exactly one of these verdicts:
 - `needs-decision`
 - `blocked`
 
-Inspect the report's basis, quality bar, findings, and next action. A `ready`
+Read the verdict and required next action first. Then inspect the report's
+basis, quality bar, and findings. A `ready`
 verdict requires a concrete quality bar and verification evidence. A non-ready
 assessment may leave the quality bar empty when the missing facts prevent it
 from being established; its finding and next action explain what is needed.
 JSON is available only when a caller explicitly requests the versioned machine
-representation. The exact
-verdict can differ between repositories. For example, a repository with no
+representation. The exact verdict can differ between repositories. For
+example, a repository with no
 identifiable CLI entry point may need discovery; that is a successful
 assessment, not a failed tutorial.
 

docs/installing-plugins.md

@@ -229,9 +229,10 @@ For the readiness worked example, select its installed skill explicitly:
 - Claude Code: use `/darrow-readiness-gate:assess-implementation-readiness`.
 
 Supply the request in the [first-workflow tutorial](getting-started.md).
-Expect an assessment with a verdict, inspected basis, quality bar, and next
-action; a non-ready verdict may leave the quality bar empty when required facts
-are missing. No implementation, edits, or tracker writes should occur.
+Expect an assessment that leads with its verdict and next action, followed by
+the inspected basis, quality bar, and findings. A non-ready verdict may leave
+the quality bar empty when required facts are missing. No implementation,
+edits, or tracker writes should occur.
 An installed listing proves package state; the observed assessment proves
 that the skill can be invoked. Neither proves every plugin behavior.
 

docs/specs/code-review.md

@@ -221,8 +221,10 @@ axis and report `not_available`. Do not invent requirements.
     `darrow-review-result-v1`, raw TSV, or machine format returns only the
     validated TSV. A response never contains both presentations.
 16. **CR-C16 — Complete rendering.** Markdown preserves every semantic field
-    from the validated TSV, prioritizes verdict and findings, renders checks
-    compactly, and presents detailed scope and sources later. Renderer
+    from the validated TSV, presents the verdict and next action first, renders
+    findings and checks compactly, and presents detailed scope and sources
+    later. It uses familiar words, active voice, and short sections without
+    repeating conclusions or narrating the review process. Renderer
     mechanics render field values as ordinary Markdown text without HTML code
     wrappers, Markdown code spans, generated links, or terminal hyperlink
     sequences. Conventional `path:line` values remain bare, while hostile field
@@ -508,6 +510,10 @@ the prior-to-current repair delta remains nonempty and exact-target-bound.
     guidance through original and regression handoffs, acceptance of an
     alternative valid repair, and rejection of a suggested repair that leaves
     the original defect. Include the enclosing repair/verification chain.
+16. **CR-E16 — Communication quality.** Focused Markdown cases assess
+    result-first clarity, concision, semantic completeness, activation, and
+    read-only safety. Assertions grade meaning and ordering rather than one
+    preferred prose rendering, while exact machine fields remain deterministic.
 
 Representative issue-32 control/candidate evidence and its N=1 limitations are
 recorded in

docs/specs/discovery.md

@@ -318,6 +318,13 @@ skill.
     and external state; later persistence, decision capture, ticketing,
     readiness assessment, orchestration, and implementation require separate
     intent and authority.
+12. **DC-C2 — Clear conversation output.** Questions lead with the requested
+    decision. Briefs and plans lead with their outcome; their required
+    confirmation request remains the final substantive element. All three use
+    familiar words, active voice, and short sentences and paragraphs, explain
+    necessary Darrow terms, and omit repeated points and process narration.
+    They still preserve material choices, provenance, constraints, acceptance
+    evidence, and confirmation boundaries.
 
 ## Packaging and portability
 
@@ -385,6 +392,10 @@ skill.
 8. **DC-E8 — Cross-harness behavior.** Representative direct, composed,
    negative, and pressure cases run on Claude Code and Codex with matched
    prompts, fixtures, model class, effort, and trial count.
+9. **DC-E9 — Communication quality.** Focused cases assess whether each skill
+   is clear and concise while preserving every material decision, evidence
+   source, safety boundary, and next action. Semantic assertions grade meaning,
+   not one preferred wording.
 
 ## Non-goals
 

docs/specs/implementation-readiness.md

@@ -116,11 +116,11 @@ Produce one semantic readiness result with these fields:
 
 The result contract is serialization-neutral. Every presentation identifies
 the same field meanings and enum values. The default standalone presentation
-is concise human-readable Markdown with an explicit verdict, basis, quality
-bar, findings, and required next action. Every material observation belongs in
-one of those sections. A consumer applies the field semantics rather than
-depending on punctuation, heading depth, or another provider-specific
-serialization detail.
+is concise human-readable Markdown. It leads with the verdict and required next
+action, then presents basis, quality bar, and findings. Every material
+observation belongs in one of those sections. A consumer applies the field
+semantics rather than depending on punctuation, heading depth, or another
+provider-specific serialization detail.
 
 When the caller explicitly requests JSON for an automated consumer, or an
 enclosing contract explicitly requires the versioned JSON representation,
@@ -241,8 +241,12 @@ unavailable.
    human-readable and preserves every semantic field. The v1 JSON
    representation is used only when the caller or enclosing contract
    explicitly requires JSON; composition alone never selects it. A standalone
-   human-readable result ends with the required-next-action description and
-   appends no second summary, disclaimer, or commentary.
+   human-readable result presents the verdict and required next action before
+   detailed evidence and appends no second summary, disclaimer, or commentary.
+10. **IRG-C10 — Clear presentation.** Human-readable results use familiar
+    words, active voice, and short sentences and paragraphs. They explain
+    necessary terms and omit repetition and process narration without dropping
+    semantic fields, evidence, enum values, or safety boundaries.
 
 ## Packaging and portability
 
@@ -294,6 +298,9 @@ unavailable.
    later terminal reporting belongs to the enclosing goal's contract. Distinct
    explicit-machine requests exercise ready and non-ready schema-valid v1
    objects without changing verdict semantics.
+10. **IRG-E10 — Communication quality.** Focused human-output cases assess
+    result-first clarity, concision, completeness, activation, and read-only
+    safety by meaning rather than exact prose.
 
 ## Non-goals
 

docs/specs/skill-authoring.md

@@ -45,6 +45,8 @@ input.
 One focused skill with valid discovery metadata, a bounded workflow, only the
 colocated resources it needs, deterministic validation where mechanics are
 checkable, and recorded evidence for trigger behavior and workflow quality.
+Its human-facing output leads with the result and next action in concise,
+understandable language while preserving required evidence and protocol data.
 
 ## Invariants
 
@@ -137,6 +139,15 @@ checkable, and recorded evidence for trigger behavior and workflow quality.
   outcomes, evaluation limitations, and residual risks. Authoring does not
   imply commit, push, pull request, publication, release, or deployment
   authority.
+- **SA-C11 — Clear human-facing output.** New and revised skills lead with the
+  result and next action when their public contract permits it. They use
+  familiar words, active voice, and short sentences and paragraphs; explain
+  necessary domain terms; and remove repetition and unnecessary process
+  narration. Progressive disclosure never removes technical meaning, safety
+  rules, complete evidence, exact commands or identifiers, or required
+  protocol fields. Behavior evals assess clarity, concision, completeness,
+  activation, and safety by meaning rather than exact prose unless wording is
+  itself the public contract.
 
 ## Non-goals
 

docs/specs/verification.md

@@ -60,7 +60,10 @@ delivery under #155. It does not execute QA or create reviewer-facing evidence p
   repair-caused regressions. Missing history blocks instead of starting a new
   comprehensive review. Advisories remain visible and nonblocking.
 - **VF-C6 — Honest conclusion.** Return clear, progress, no-progress or blocked
-  with the provider's original outcome and its meaning preserved. Clear requires
+  with the provider's original outcome and its meaning preserved. Put the
+  conclusion and smallest next action before detailed evidence in the
+  human-readable result. Use familiar words, active voice, and short sections;
+  omit repetition and process narration. Clear requires
   current successful required checks, sufficient evidence for every material
   criterion, and no unresolved eligible blocker or direct regression. In an
   initial result, actionable evidenced blockers are progress (assessment is
@@ -104,10 +107,10 @@ This is a semantic contract, not a mandatory object schema. Preserve the
 provider's normal public report and references rather than requesting its
 private record format. A caller supplies a bounded initial request or a closed
 follow-up, and receives candidate identity, selected/absent/unavailable
-assessments, complete provider results, criterion-level evidence, combined
-findings with dispositions, limitations, conclusion and the smallest needed
-next action. Provider-specific artifacts can travel opaquely with provenance;
-only the provider interprets its own mechanical records.
+assessments, conclusion and the smallest needed next action first, followed by
+complete provider results, criterion-level evidence, combined findings with
+dispositions, and limitations. Provider-specific artifacts can travel opaquely
+with provenance; only the provider interprets its own mechanical records.
 
 Adaptive delivery binds this capability in preflight and the
 existing owner contract, preserving routine omission and high-risk review
@@ -132,5 +135,7 @@ compatible replacement; missing/incompatible/stale required evidence; absent
 unselected optional capabilities; criterion gaps; clear/progress/no-progress/
 blocked follow-up; advisory disposition and direct-regression lineage; and
 pressure to repair or bypass missing evidence. Supported hosts require native
-live evidence. Coverage, dry preparation, activation, outcomes and matched
-no-skill observations are reported separately.
+live evidence. Focused human-output checks assess result-first clarity,
+concision, completeness, activation, and safety by meaning rather than exact
+prose. Coverage, dry preparation, activation, outcomes and matched no-skill
+observations are reported separately.

docs/specs/visual-explanation.md

@@ -139,6 +139,11 @@ compression.
    smaller text representation.
 7. **VE-C7 — Read-only conversation output.** The capability changes neither
    repository nor external state and creates no visual artifact files.
+8. **VE-C8 — Clear framing.** The explanation leads with the answer the visual
+   provides, then gives only the framing and caveats needed to understand it.
+   It uses familiar words, active voice, and short prose, explains necessary
+   terms, and omits repeated points and process narration without hiding
+   evidence status, material boundaries, or uncertainty.
 
 ## Request matrix
 
@@ -192,6 +197,8 @@ prose is implemented:
    negative, and pressure cases compare the skill with an uncontaminated
    no-skill condition on Claude Code and Codex using matched prompts, fixtures,
    model class, effort, and trial count.
+9. **VE-E9 — Communication quality.** Focused cases assess clarity, concision,
+   completeness, activation, and safety by meaning rather than exact prose.
 
 ## Non-goals
 

docs/troubleshooting.md

@@ -37,7 +37,8 @@ That can be a successful result. The
 [readiness tutorial](getting-started.md#3-inspect-the-result) deliberately
 leaves repository details to inspection. A missing CLI entrypoint or unclear
 behavior can require discovery or a decision. Read the assessment's missing
-fact and clarify it; do not ask the guide to invent a ready verdict.
+fact and required next action, then clarify it. Do not ask the guide to invent
+a ready verdict.
 
 ## A capability refuses an operation
 

evals/runner/discovery-eval-checks.test.ts

@@ -68,7 +68,7 @@ describe("discovery eval loopholes", () => {
       [name],
     );
     expect(canonical?.passed).toBe(true);
-  });
+  }, 20_000);
 
   test("unresolved planning keeps prose judgment in semantic checks", async () => {
     const evalCase = await loadCase(
@@ -90,17 +90,19 @@ describe("discovery eval loopholes", () => {
     );
   });
 
-  test("planning transfer does not turn missing repository policy into authority", async () => {
-    const [check] = await messageChecks(
+  test("planning transfer keeps missing-policy authority in semantic checks", async () => {
+    const evalCase = await loadCase(
       "plugins/capability/darrow-discovery/skills/plan-implementation/evals/dependency-frontier-transfer.yaml",
-      [
-        "Evidence: No encryption or partitioning code exists. This is effectively a greenfield build.",
-        "Q1 — Storage topology: shared archive or tenant-isolated stores?",
-        "Recommendation: Choose shared archive because no repository evidence indicates a regulatory isolation requirement.",
-        "Deferred: encryption-key ownership, partition format, migration strategy. I will recompute the next frontier.",
-      ].join("\n"),
-      ["repository absence is not promoted to greenfield authority"],
     );
-    expect(check?.passed).toBe(false);
+    const name = "repository absence is not promoted to greenfield authority";
+    const semanticCheck = evalCase.semantic_output_checks?.find(
+      (check) => check.name === name,
+    );
+
+    expect(evalCase.checks.some((check) => check.name === name)).toBe(false);
+    expect(semanticCheck?.proposition).toContain(
+      "sparse or missing implementation",
+    );
+    expect(semanticCheck?.proposition).toContain("greenfield");
   });
 });

plugins/capability/darrow-discovery/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "darrow-discovery",
   "description": "Explicit grilling, feature discovery, and implementation planning",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "license": "BUSL-1.1",
   "author": {
     "name": "Björn Rochel",

plugins/capability/darrow-discovery/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "darrow-discovery",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Explicit grilling, feature discovery, and implementation planning",
   "author": {
     "name": "Björn Rochel",

plugins/capability/darrow-discovery/README.md

@@ -82,7 +82,9 @@ or use `/darrow-discovery:discover-feature` in Claude Code, followed by your req
 
 ## Expected result
 
-A read-only discussion and confirmed discovery brief or implementation plan, without writing artifacts, tickets, or code.
+A focused read-only discussion leads with the current decision or outcome. A
+confirmed brief or plan keeps its evidence, constraints, and verification
+without writing artifacts, tickets, or code.
 
 ## Troubleshooting