Skip to content
Closed
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
2 changes: 2 additions & 0 deletions plugins/productivity/skills/write-naturally/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Write naturally

Plain language is the default for PR comments and short technical discussion, even when the request is only for a concise comment. Keep necessary technical detail and the agreed review status.

## Practical gotchas

- **Long conversations:** an agent can read the skill early and later drift from it. Before the final version, check which guidance it is applying. If the answer is vague or the prose has drifted, ask it to reread the skill and the relevant reference. A claim that it remembers the skill is weaker evidence than a fresh read.
Expand Down
2 changes: 1 addition & 1 deletion plugins/productivity/skills/write-naturally/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
For PR comments and short technical discussion, use plain language by default, even when it was not requested. Name who acts, what happens and, where relevant, where it happens; include the triggering condition and observable consequence instead of relying on compressed labels. 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. Keep a specialist term only after explaining it, and only when the reader still needs it.

For technical writing, prefer this order:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Open with the conclusion. Name the contract boundary or risk. Use bullets only f

Make review status explicit and proportionate to the supplied evidence. A reproduced edge case establishes behavior; its impact and the applicable requirement determine whether it blocks approval. When an unresolved policy determines the recommendation, ask the policy question directly and explain how its answer changes the action. Preserve an agreed blocker or follow-up when rewriting, and keep approval language consistent with that status. Writing alone cannot settle a missing review decision.

For a technical concern, show the affected caller or user, the triggering input or condition, what the system actually does, and the consequence. Group observations that share one cause and fix, including the same defect in multiple repositories, into one concern.
For a technical concern, state plainly who or what is affected, the triggering input or condition, what the system actually does, and the consequence. Name what runs and where when that helps the recipient follow the behavior; do not leave these details compressed into labels they must decode. Group observations that share one cause and fix, including the same defect in multiple repositories, into one concern.

Close with the present constraint and the practical consequence: what can be done now, who must act, or which workaround remains.

Expand Down Expand Up @@ -34,4 +34,4 @@ Example of a final review comment, given a verified JSON Schema dialect mismatch
>
> We should support one dialect or validate each schema using its declared dialect.

Before returning a review comment, check that the recipient can understand the issue, example, review status and next action without the drafting conversation. One underlying issue should stay one concern, and the status should match the current decision.
Before returning a review comment, check that the recipient can understand the issue, example, agreed review status and next action without needing to unpack jargon or know the drafting conversation. One underlying issue should stay one concern, and the status should match the current decision.
Loading