From 364dec375091985a79f4d049432da7adc3d7ea7f Mon Sep 17 00:00:00 2001 From: "warp-factories[bot]" <243557089+warp-factories[bot]@users.noreply.github.com> Date: Tue, 1 Sep 2026 15:14:15 +0000 Subject: [PATCH 1/2] docs(skills): tighten field-label quotes and drafting brevity Elevate recurring human review nits into draft_docs critical rules and procedural/feature templates: quotation marks for non-clickable field labels, and an explicit Cut again pass before shipping long pages. --- .agents/skills/draft_docs/SKILL.md | 3 +++ .agents/templates/feature-doc.md | 2 +- .agents/templates/procedural.md | 2 ++ 3 files changed, 6 insertions(+), 1 deletion(-) diff --git a/.agents/skills/draft_docs/SKILL.md b/.agents/skills/draft_docs/SKILL.md index f8f3743c..98410dff 100644 --- a/.agents/skills/draft_docs/SKILL.md +++ b/.agents/skills/draft_docs/SKILL.md @@ -145,6 +145,7 @@ These rules are frequently violated by agents. Apply them carefully during draft - **Unordered list marker is `*`** — Match the templates and existing docs. Reserve `-` for nested lists whose parent already uses `*`; use `1.` for numbered procedures. ✅ `* **Codebase Context** - Warp indexes your Git-tracked codebase` ❌ `- **Codebase Context** - ...` as the top-level marker on a new page - **Tables or parallel bullets for comparison and reference data** — When you present two or more parallel items (key types, plan tiers, environments) or structured reference data (API endpoints, parameters), use a Markdown table or tightly parallel bullets instead of one dense paragraph. ✅ a table with one row per API endpoint, or parallel `**Personal API keys**` / `**Agent API keys**` bullet groups ❌ a single paragraph mixing both key types and their billing rules - **Bold for UI elements** — Use `**Save**` not `` `Save` `` after action verbs like "click" +- **Quotes for non-clickable field labels** — If a name labels a field but is not itself clickable, put it in quotation marks, not bold. Bold the control next to it (dropdown, input, or the option you choose). ✅ `In the "Harness" dropdown, select **Claude Code** or **Codex**.` ❌ `In the **Harness** dropdown, select **Claude Code**.` ❌ `Choose **Claude Code** in the **Harness** field.` - **Bold per-segment for Settings paths** — Use `**Settings** > **AI** > **Knowledge**` not `` `Settings > AI > Knowledge` `` - **Orient the reader before every Settings path, CLI command, or URL** — On first reference in the page, name the app or tool. ✅ `In the Warp app, go to **Settings** > **AI** > **Knowledge**.` ❌ `Go to **Settings** > **AI** > **Knowledge**.` - **Verify labels, flags, and defaults against source** — Before documenting a button name, Settings path, CLI flag, permission default, or eligibility rule, confirm it in `warp-internal` / `warp-server` or the live UI. ✅ `warp --auto-approve` after checking `TuiArgs` ❌ inventing `--fast-forward` from memory or an old PR description @@ -155,6 +156,7 @@ These rules are frequently violated by agents. Apply them carefully during draft - **Keep error messages out of the main flow** — Do not weave full error strings through conceptual or procedural sections. Put them in a dedicated `## Troubleshooting` section near the end, formatted symptom → cause → fix. ✅ one Troubleshooting section with the exact error as a bold lead-in ❌ repeating the same error callout after every step - **Use callouts sparingly** — Prefer body prose. At most one or two callouts per page unless the content type template requires more, never two callouts back to back, and at most one per section. ✅ a single `:::note` for a non-obvious prerequisite ❌ a `:::note` / `:::tip` after every subsection - **No AI-ism buzzwords or meta-openers** — Never open with "This page covers/explains/walks through..."; state the thing itself. Avoid marketing adjectives (seamless, powerful, robust, comprehensive), inflated verbs (leverage, streamline, empower, unlock), restated cause-and-effect ("This process ensures..."), and recap lines. See AGENTS.md → Voice & tone for the full lists. ✅ "Run agents directly in your GitHub Actions workflows using `oz-agent-action`." ❌ "This page covers how the integration works, how to set it up, and common automation patterns." +- **Cut length before shipping** — Brevity is a drafting rule, not only a review checklist item. After the first complete draft, run a deletion-only "Cut again" pass (AGENTS.md → Voice & tone → Cut again): remove framing lines, restated cause-and-effect, internal implementation detail the reader cannot act on, and boilerplate a parent page already owns. Prefer one concrete sentence over a paragraph that re-explains the same step. A page past ~1500 words usually still has padding — cut first; split only if the remaining content still does not fit. ✅ a setup section that states only the required clicks and links out for credential types ❌ a multi-paragraph walkthrough of harness internals on a how-to page - **Document the user-visible model, not internal architecture** — Internal components (orchestrators, control planes, lifecycle state machines) get at most one sentence, and only when the reader can act on them. ✅ "Warp tracks every run. Check its status from the CLI, the API, or the dashboard." ❌ "The orchestration layer runs on Warp's servers (cloud control plane) and tracks lifecycle state (created → running → completed/failed)." - **Descriptive link text, and no dead-end pages** — Never use "here", "this page", or a bare URL as link text. End every new page with `## Next steps` (quickstarts and tutorials) or `## Related pages` (every other type), containing at least one internal link whose anchor names the destination topic. Do not use "Further reading" or "See also". ✅ `Learn more about [Codebase Context](/code/codebase-context/)` ❌ `Click [here](/code/codebase-context/)` ❌ ending a new feature page with no cross-links - **Disambiguate conditional and multi-clause wording** — If a sentence has two plausible readings (especially with "when", "if", "can", or stacked clauses), rewrite it so only one meaning remains. Prefer one idea per sentence. ✅ `Cloud handoff keeps your conversation's model only when that model is available in the cloud.` ❌ `Cloud handoff keeps your conversation's model when it can run in the cloud.` (keeps the model when it can? or only when cloud supports the model?) @@ -203,6 +205,7 @@ Before presenting the draft, verify against the quality checklist in `AGENTS.md` - [ ] The title is in frontmatter and there is no H1 in the body - [ ] Link text names the destination topic (not "here" / "this page" / raw URLs) - [ ] The first Settings path, CLI command, or URL on the page names the app or tool +- [ ] Non-clickable field labels use quotation marks; only interactive controls and chosen options are bold - [ ] Instructions include expected outcomes - [ ] Instructional sentences lead with the action or goal before the control, shortcut, or condition - [ ] Conditional or multi-clause sentences have only one clear reading (no ambiguous "when/if/can" stacking) diff --git a/.agents/templates/feature-doc.md b/.agents/templates/feature-doc.md index f315dc0a..8d5ababe 100644 --- a/.agents/templates/feature-doc.md +++ b/.agents/templates/feature-doc.md @@ -34,7 +34,7 @@ description: >- ## [Usage or configuration — sentence case, renamed to match the feature, e.g. "Creating environments"] -[PROCEDURAL section. Motivate before instructing, include expected outcomes after key steps, and group related actions that share a UI context.] +[PROCEDURAL section. Motivate before instructing, include expected outcomes after key steps, and group related actions that share a UI context. Bold clickable controls and selected options; put non-clickable field labels in quotation marks ("Harness" dropdown, not **Harness** dropdown). Keep steps short — cut internal implementation detail and move reference lists into a :::note or a linked page.] ### Prerequisites diff --git a/.agents/templates/procedural.md b/.agents/templates/procedural.md index 91373f91..9d4aa71a 100644 --- a/.agents/templates/procedural.md +++ b/.agents/templates/procedural.md @@ -29,6 +29,8 @@ description: >- 3. Step description. [STEP SIZING: Aim for one primary action per step, but group tightly related actions that share the same UI context — up to about three. A simple task should not need 10+ steps, and a single step should not be a mini-procedure.] +[UI LABELS: Bold clickable controls and the option the reader selects. Put non-clickable field labels in quotation marks. Example: In the "Harness" dropdown, select **Claude Code**. Not: In the **Harness** dropdown...] +[BREVITY IN STEPS: State the action and expected outcome only. Move reference lists (accepted credential types, valid formats) into a single :::note after the step, or link out — do not re-explain internals in the step body.] :::note [Optional. One or two callouts per page at most; prefer body prose. Delete if nothing applies.] From b7517970040387a7e1ffa1a480b938e7889917ea Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 1 Sep 2026 09:35:34 -0600 Subject: [PATCH 2/2] Update .agents/skills/draft_docs/SKILL.md Co-authored-by: warp-for-oss[bot] <277970191+warp-for-oss[bot]@users.noreply.github.com> --- .agents/skills/draft_docs/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/draft_docs/SKILL.md b/.agents/skills/draft_docs/SKILL.md index 98410dff..bf88cfa6 100644 --- a/.agents/skills/draft_docs/SKILL.md +++ b/.agents/skills/draft_docs/SKILL.md @@ -145,7 +145,7 @@ These rules are frequently violated by agents. Apply them carefully during draft - **Unordered list marker is `*`** — Match the templates and existing docs. Reserve `-` for nested lists whose parent already uses `*`; use `1.` for numbered procedures. ✅ `* **Codebase Context** - Warp indexes your Git-tracked codebase` ❌ `- **Codebase Context** - ...` as the top-level marker on a new page - **Tables or parallel bullets for comparison and reference data** — When you present two or more parallel items (key types, plan tiers, environments) or structured reference data (API endpoints, parameters), use a Markdown table or tightly parallel bullets instead of one dense paragraph. ✅ a table with one row per API endpoint, or parallel `**Personal API keys**` / `**Agent API keys**` bullet groups ❌ a single paragraph mixing both key types and their billing rules - **Bold for UI elements** — Use `**Save**` not `` `Save` `` after action verbs like "click" -- **Quotes for non-clickable field labels** — If a name labels a field but is not itself clickable, put it in quotation marks, not bold. Bold the control next to it (dropdown, input, or the option you choose). ✅ `In the "Harness" dropdown, select **Claude Code** or **Codex**.` ❌ `In the **Harness** dropdown, select **Claude Code**.` ❌ `Choose **Claude Code** in the **Harness** field.` +- **Quotes for non-clickable field labels** — If a name labels a field but is not itself clickable, put it in quotation marks, not bold. Bold only interactive controls with their own visible labels and the option the reader selects. ✅ `In the "Harness" dropdown, select **Claude Code** or **Codex**.` ❌ `In the **Harness** dropdown, select **Claude Code**.` ❌ `Choose **Claude Code** in the **Harness** field.` - **Bold per-segment for Settings paths** — Use `**Settings** > **AI** > **Knowledge**` not `` `Settings > AI > Knowledge` `` - **Orient the reader before every Settings path, CLI command, or URL** — On first reference in the page, name the app or tool. ✅ `In the Warp app, go to **Settings** > **AI** > **Knowledge**.` ❌ `Go to **Settings** > **AI** > **Knowledge**.` - **Verify labels, flags, and defaults against source** — Before documenting a button name, Settings path, CLI flag, permission default, or eligibility rule, confirm it in `warp-internal` / `warp-server` or the live UI. ✅ `warp --auto-approve` after checking `TuiArgs` ❌ inventing `--fast-forward` from memory or an old PR description