From 6c3a90645ae2ee97429e82f65dbc510d0b007cb8 Mon Sep 17 00:00:00 2001 From: Mark McLaughlin Date: Fri, 6 Mar 2026 14:46:11 -0800 Subject: [PATCH] feat(skills): refine string-reviewer guidelines and description (#20368) --- .gemini/skills/string-reviewer/SKILL.md | 99 +++++++++++++++++++ .../string-reviewer/references/settings.md | 28 ++++++ .../string-reviewer/references/word-list.md | 61 ++++++++++++ 3 files changed, 188 insertions(+) create mode 100644 .gemini/skills/string-reviewer/SKILL.md create mode 100644 .gemini/skills/string-reviewer/references/settings.md create mode 100644 .gemini/skills/string-reviewer/references/word-list.md diff --git a/.gemini/skills/string-reviewer/SKILL.md b/.gemini/skills/string-reviewer/SKILL.md new file mode 100644 index 0000000000..f37d83b4ad --- /dev/null +++ b/.gemini/skills/string-reviewer/SKILL.md @@ -0,0 +1,99 @@ +--- +name: string-reviewer +description: > + Use this skill when asked to review text and user-facing strings within the codebase. It ensures that these strings follow rules on clarity, + usefulness, brevity and style. +--- + +# String Reviewer + +## Instructions + +Act as a Senior UX Writer. Look for user-facing strings that are too long, +unclear, or inconsistent. This includes inline text, error messages, and other +user-facing text. + +Do NOT automatically change strings without user approval. You must only suggest +changes and do not attempt to rewrite them directly unless the user explicitly +asks you to do so. + +## Core voice principles + +The system prioritizes deterministic clarity over conversational fluff. We +provide telemetry, not etiquette, ensuring the user retains absolute agency.. + +1. **Deterministic clarity:** Distinguish between certain system/service states + (Cloud Billing, IAM, the System) and probabilistic AI analysis (Gemini). +2. **System transparency:** Replace "Loading..." with active technical telemetry + (e.g., Tracing stack traces...). Keep status updates under 5 words. +3. **Front-loaded actionability:** Always use the [Goal] + [Action] pattern. + Lead with intent so users can scan left-to-right. +4. **Agentic error recovery:** Every error must be a pivot point. Pair failures + with one-click recovery commands or suggested prompts. +5. **Contextual humility:** Reserve disclaimers and "be careful" warnings for P0 + (destructive/irreversible) tasks only. Stop warning-fatigue. + +## The writing checklist + +Use this checklist to audit UI strings and AI responses. + +### Identity and voice +- **Eliminate the "I":** Remove all first-person pronouns (I, me, my, mine). +- **Subject attribution:** Refer to the AI as Gemini and the infrastructure as + the - system or the CLI. +- **Active voice:** Ensure the subject (Gemini or the system) is clearly + performing the action. +- **Ownership rule:** Use the system for execution (doing) and Gemini for + analysis (thinking) + +### Structural scannability +- **The skip test:** Do the first 3 words describe the user’s intent? If not, + rewrite. +- **Goal-first sequence:** Use the template: [To Accomplish X] + [Do Y]. +- **The 5-word rule:** Keep status updates and loading states under 5 words. +- **Telemetry over etiquette:** Remove polite filler (Please wait, Thank you, + Certainly). Replace with raw data or progress indicators. +- **Micro-state cycles:** For tasks $> 3$ seconds, cycle through specific + sub-states (e.g., Parsing logs... ➔ Identifying patterns...) to show momentum. + + +### Technical accuracy and humility +- **Verb signal check:** Use deterministic verbs (is, will, must) for system + state/infrastructure. + - Use probabilistic verbs (suggests, appears, may, identifies) for AI output. +- **No 100% certainty:** Never attribute absolute certainty to model-generated + content. +- **Precision over fuzziness:** Use technical metrics (latency, tokens, compute) instead of "speed" or "cost." +- **Instructional warnings:** Every warning must include a specific corrective action (e.g., "Perform a dry-run first" or "Review line 42"). + +### Agentic error recovery +- **The one-step rule:** Pair every error message with exactly one immediate + path to a fix (command, link, or prompt). +- **Human-first:** Provide a human-readable explanation before machine error + codes (e.g., 404, 500). +- **Suggested prompts:** Offer specific text for the user to copy/click like + “Ask Gemini: 'Explain this port error.'” + +### Use consistent terminology + +Ensure all terminology aligns with the project [word +list](./references/word-list.md). + +If a string uses a term marked "do not use" or "use with caution," provide a +correction based on the preferred terms. + +## Ensure consistent style for settings + +If `packages/cli/src/config/settingsSchema.ts` is modified, confirm labels and +descriptions specifically follow the unique [Settings +guidelines](./references/settings.md). + +## Output format +When suggesting changes, always present your review using the following list +format. Do not provide suggestions outside of this list.. + +``` +1. **{Rationale/Principle Violated}** + - ❌ "{incorrect phrase}" + - ✅ `"{corrected phrase}"` +``` \ No newline at end of file diff --git a/.gemini/skills/string-reviewer/references/settings.md b/.gemini/skills/string-reviewer/references/settings.md new file mode 100644 index 0000000000..df054127a8 --- /dev/null +++ b/.gemini/skills/string-reviewer/references/settings.md @@ -0,0 +1,28 @@ +# Settings + +## Noun-First Labeling (Scannability) + +Labels must start with the subject of the setting, not the action. This allows +users to scan for the feature they want to change. + +- **Rule:** `[Noun]` `[Attribute/Action]` +- **Example:** `Show line numbers` becomes simply `Line numbers` + +## Positive Boolean Logic (Cognitive Ease) + +Eliminate "double negatives." Booleans should represent the presence of a +feature, not its absence. + +- **Rule:** Replace `Disable {feature}` or `Hide {Feature}` with + `{Feature} enabled` or simply `{Feature}`. +- **Example:** Change "Disable auto update" to "Auto update". +- **Implementation:** Invert the boolean value in your config loader so true + always equals `On` + +## Verb Stripping (Brevity) + +Remove redundant leading verbs like "Enable," "Use," "Display," or "Show" unless +they are part of a specific technical term. + +- **Rule**: If the label works without the verb, remove it +- **Example**: Change `Enable prompt completion` to `Prompt completion` diff --git a/.gemini/skills/string-reviewer/references/word-list.md b/.gemini/skills/string-reviewer/references/word-list.md new file mode 100644 index 0000000000..1bb04b9817 --- /dev/null +++ b/.gemini/skills/string-reviewer/references/word-list.md @@ -0,0 +1,61 @@ +## Terms + +### Preferred + +- Use **create** when a user is creating or setting up something. +- Use **allow** instead of **may** to indicate that permission has been granted + to perform some action. +- Use **canceled**, not **cancelled**. +- Use **configure** to refer to the process of changing the attributes of a + feature, even if that includes turning on or off the feature. +- Use **delete** when the action being performed is destructive. +- Use **enable** for binary operations that turn a feature or API on. Use "turn + on" and "turn off" instead of "enable" and "disable" for other situations. +- Use **key combination** to refer to pressing multiple keys simultaneously. +- Use **key sequence** to refer to pressing multiple keys separately in order. +- Use **modify** to refer to something that has changed vs obtaining the latest + version of something. +- Use **remove** when the action being performed takes an item out of a larger + whole, but doesn't destroy the item itself. +- Use **set up** as a verb. Use **setup** as a noun or adjective. +- Use **show**. In general, use paired with **hide**. +- Use **sign in**, **sign out** as a verb. Use **sign-in** or **sign-out** as a + noun or adjective. +- Use **update** when you mean to obtain the latest version of something. +- Use **want** instead of **like** or **would like**. + +#### Don't use + +- Don't use **etc.** It's redundant. To convey that a series is incomplete, + introduce it with "such as" instead. +- Don't use **hostname**, use "host name" instead. +- Don't use **in order to**. It's too formal. "Before you can" is usually better + in UI text. +- Don't use **one or more**. Specify the quantity where possible. Use "at least + one" when the quantity is 1+ but you can't be sure of the number. Likewise, + use "at least one" when the user must choose a quantity of 1+. +- Don't use the terms **log in**, **log on**, **login**, **logout** or **log + out**. +- Don't use **like** or **would you like**. Use **want** instead. Better yet, + rephrase so that it's not referring to the user's emotional state, but rather + what is required. + +#### Use with caution + +- Avoid using **leverage**, especially as a verb. "Leverage" is considered a + buzzword largely devoid of meaning apart from the simpler "use". +- Avoid using **once** as a synonym for "after". Typically, when "once" is used + in this way, it is followed by a verb in the perfect tense. +- Don't use **e.g.** Use "example", "such as", "like", or "for example". The + phrase is always followed by a comma. +- Don't use **i.e.** unless absolutely essential to make text fit. Use "that is" + instead. +- Use **disable** for binary operations that turn a feature or API off. Use + "turn on" and "turn off" instead of "enable" and "disable" for other + situations. For UI elements that are not available, use "dimmed" instead of + "disabled". +- Use **please** only when you're asking the user to do something inconvenient, + not just following the instructions in a typical flow. +- Use **really** sparingly in such constructions as "Do you really want to..." + Because of the weight it puts on the decision, it should be used to confirm + actions that the user is extremely unlikely to make.