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
19 changes: 18 additions & 1 deletion evals/productivity/write-naturally/tests/general-writing.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,21 @@
# Fictional nontechnical cases exercise the shared writing guidance.
# Fictional cases exercise the shared writing and reader guidance.
- description: '[C14] software explanation starts with a concrete user example'
vars:
surface: Product support reply
request: Explain why saving a shared document failed and what the fix changes. The reader uses the app but does not know its implementation.
draft: The authorization preflight selected the first matching membership record. A revoked personal membership shadowed an active team membership for the same document, causing fail-closed rejection before the active grant was evaluated. The repair continues membership selection after a revoked candidate, accepts the active team grant, and still denies writes when no active grant remains. No content was lost and this fix does not restore revoked access.
pass_criterion: >-
Starts with a recognizable user action and result, such as trying to save a document shared with their team and being refused.
Carries the same example through the cause and corrected behavior: an old revoked personal permission was checked first,
the valid team permission was never reached, and the fix checks the remaining permissions.
Preserves that saving remains denied without active permission, no content was lost, and revoked access is not restored.
fails_if: Leads with authorization preflight, membership selection, shadowing or fail-closed terminology that the reader must decode; gives only an abstract summary without a concrete user action; invents a product workflow or verification; implies all saves now succeed or revoked access is restored; or omits the supplied limits.
metadata:
id: C14
dataset_version: v1-public-fictional
group: general-writing
surface: support-reply
fixture_origin: Original fictional scenario; no real people or private provenance.
- description: '[C11] casual scheduling message stays short and factual'
vars:
surface: Team chat
Expand Down
12 changes: 8 additions & 4 deletions plugins/productivity/skills/write-naturally/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: write-naturally
description: Write or rewrite messages, reviews, pull-request descriptions, design notes, and technical prose in a direct, evidence-led, natural style. Use when the user asks to "write naturally", "write like a human", "write in my style", polish a comment, or make prose sound natural.
description: Write or rewrite messages, reviews, pull-request descriptions, design notes, and technical prose in a direct, evidence-led, natural style. Use when the user asks to "write naturally", "write like a human", "write in my style", polish a comment, make prose sound natural, or explain software behavior to a non-specialist.
metadata:
source: https://github.com/allagentsdev/agent-plugins/tree/main/plugins/productivity/skills/write-naturally
---
Expand All @@ -14,7 +14,7 @@ The voice is direct, technically precise, and proportionate to the medium. It ca
## The shape

Lead with the point. Then give only the context needed to support it.
When the user asks for plain English, preserve the contract rather than the source's compressed wording. Do not carry unexplained shorthand into the rewrite. Replace it with the responsible actor, observable action and relevant condition; keep the specialist term only after that explanation and only when the reader still needs it.
Make the behavior understandable at the reader's level without waiting for a plain-English request. Replace unexplained shorthand with the responsible actor, observable action and relevant condition; keep the specialist term only after that explanation and only when the reader still needs it.

For technical writing, prefer this order:

Expand Down Expand Up @@ -73,7 +73,11 @@ Ordinary messages and other prose use the shared guidance here.

Write for the person receiving the text. After a discussion, use the latest agreed position and the evidence that still supports it. Include only history the recipient needs to understand or act; keep explanations of the drafting process in the conversation with the requester.

Make abstract concerns concrete with a short example when it helps. Show the person affected, the triggering condition, what happens and why it matters. Use supplied evidence for factual examples, label hypothetical illustrations, and claim verification only when it was provided.
For explanations of software behavior and user-facing bugs, start with a concrete situation the reader recognizes: what they do and what happens. Carry the same example through the cause and the proposed or verified change. Introduce internal names where they explain that behavior. Keep this sequence short, and adapt it when the reader already knows the example or explicitly needs implementation detail.

For example: "You select Claude and install a plugin. The installer opens a description file for another tool first and rejects the plugin before reading its valid Claude file. The fix skips that unsupported description and continues to the Claude file."

The reader should be able to follow that sequence without translating internal terminology or asking for a second explanation. Use supplied evidence for factual examples, label hypothetical illustrations, and claim verification only when it was provided. Keep causal reasoning in connected prose; a brief factual example needs no invented characters or narrative padding.

Frame recommendations as shared decisions: `We should …` for a requested change or `We can …` for a concrete proposal. Keep the boundary or limit firm; collaborative wording need not make it tentative. These are examples, not required openings. Classify force from the user's description and surrounding context, not grammatical mood alone. When the request identifies the source as a recommendation or proposal, turn a bare imperative into a collaborative statement. Politeness still does not determine force: a sentence beginning `Please keep …` may instead express a command, requirement, or acceptance criterion. Preserve those as obligations rather than recasting them as optional or tentative language.

Expand Down Expand Up @@ -106,7 +110,7 @@ Use certainty deliberately:
7. Build a private checklist of source guarantees expressed with `must`, `never`, `only`, `prevents`, `cannot` or equivalent language. Confirm the rewrite preserves the same actor, action and object for each one. A related mechanism does not count as the same guarantee. Compare exact identifiers, numbers and link destinations character for character when they remain in scope.
8. Read the result once for voice and once for level of detail. It should sound like a colleague explaining the subject.
9. Check boundary words separately: `all`, `any`, `before`, `after`, `exactly`, `at most`, units, and scope such as one attempt versus the whole request. Smoother wording is wrong if it changes the threshold. `Uses the remaining allowance` does not preserve `uses all the remaining allowance`.
10. When plain English is requested, inspect the result for source shorthand such as `I/O`, `invariant`, `surface`, `pre-call` or an unexplained accounting label. Replace it with behavior or define it through a concrete example. A polished label still fails if the reader must decode it.
10. Inspect the result for shorthand the intended reader would have to decode, such as `I/O`, `invariant`, `surface`, `pre-call` or an unexplained accounting label. Replace it with behavior or define it through the example. For a software explanation, check that the reader can follow the user action, result, cause and change without knowing the implementation first.
11. Read it from the recipient's position: can they understand the point, evidence and next action without the drafting conversation?

## Guardrails
Expand Down
Loading