Skip to content

Commit 80c212e

Browse files
author
Promptless Agent
committed
Add style guidance on avoiding 'should' and unnecessary parentheses
Based on feedback from lennessyy on PR #4029: - Added guidance to avoid 'should' in user instructions; use imperative mood instead - Added guidance to avoid unnecessary parentheses; prefer commas for clarifying information - Provided examples of correct/incorrect usage for both patterns - Clarified when parentheses are still appropriate (abbreviations, technical specs, etc.)
1 parent 8302d25 commit 80c212e

File tree

1 file changed

+26
-0
lines changed

1 file changed

+26
-0
lines changed

.long_term_context/style/client_style_guide.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,32 @@ In most cases when providing direct instruction, the imperative works better.
9898
- Correct: Next, add the following code:
9999
- Incorrect: Next, we add the following code:
100100

101+
### Avoid "should" in user instructions
102+
103+
When giving instructions to users, use the imperative mood directly rather than saying users "should" do something. This makes instructions clearer and more direct.
104+
105+
- Correct: "Provide a reason when resetting, as it will be recorded in the Event History."
106+
- Incorrect: "You should provide a reason when resetting."
107+
108+
Note: It's acceptable to use "should" when describing general best practices, system behavior, or outcomes (e.g., "the reader should have a usable environment").
109+
110+
### Avoid unnecessary parentheses
111+
112+
When adding clarifying or supplementary information, prefer using commas instead of parentheses. This keeps the text flow more natural and readable.
113+
114+
- Correct: "Reset only works if you've fixed the underlying issue, such as removing non-deterministic code."
115+
- Incorrect: "Reset only works if you've fixed the underlying issue (such as removing non-deterministic code)."
116+
117+
Remove parenthetical clarifications entirely if they're not essential to understanding the instruction.
118+
119+
- Correct: "Select the Event ID to reset to"
120+
- Incorrect: "Select the Event ID to reset to (typically a `WorkflowTaskCompleted` event before the failure)"
121+
122+
Parentheses are still appropriate for:
123+
- Abbreviations on first use: "Transport Layer Security (TLS)"
124+
- Technical specifications: "at least 2048-bit RSA"
125+
- Aside notes that are truly supplementary and would break sentence flow otherwise
126+
101127
### Focus on specific outcomes rather than "Learn to/Learn how to" language.
102128

103129
Focus on the skill the learner will gain rather than the act of gaining the skill. Look for "learn to/learn how to" and remove them and you'll have tighter sentences.

0 commit comments

Comments
 (0)