From 19fe50339d4df7cd850449dc2d239fe9f443c753 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Tue, 29 Sep 2026 16:35:10 +0100 Subject: [PATCH 1/2] Improved writing style with rules in the doc-writer skill. --- .agents/skills/doc-writer/SKILL.md | 47 +++++++++++++++++++ .../skills/whatsnew/references/03-critique.md | 1 + .../references/whats-new-template.mdx | 2 +- ...ty-toolkit-integration-doc-writer.agent.md | 1 + .github/instructions/astro.instructions.md | 3 +- 5 files changed, 52 insertions(+), 2 deletions(-) diff --git a/.agents/skills/doc-writer/SKILL.md b/.agents/skills/doc-writer/SKILL.md index 2c3392ab8..219ece8f4 100644 --- a/.agents/skills/doc-writer/SKILL.md +++ b/.agents/skills/doc-writer/SKILL.md @@ -820,6 +820,53 @@ Use consistent terminology throughout: - Use diverse, international examples - Avoid idioms and culturally-specific references +### Prose patterns to avoid + +AI-drafted text falls into recognizable patterns. One instance may be fine but several together make a page read as machine-written and cost the reader time. Before finishing a draft, check for these and rewrite them. + +Sentence structure: + +- Avoid sentences with more than four clauses if possible. Split such a sentence in order to be more direct. +- Avoid framing such as "It's not X, it's Y", "The question isn't X. It's Y", or "Not X. Not Y. Just Z." Instead, say what the thing is. +- Avoid self-answered questions such as "The result? Faster startup." Instead write "Startup is faster." +- Avoid sentence fragments used for emphasis, for example "Local. Fast. Free." Write complete sentences. +- Avoid groups of three used by reflex. List three items only when there are three things. +- Avoid trailing "-ing" clauses that add significance without information. For example, "..., highlighting its flexibility". +- Avoid short phrases hung off a final comma instead of finishing the sentence. +- Avoid "from X to Y" when X and Y aren't ends of a real range. +- Avoid "serves as", "stands as", or "represents" where "is" works. +- Avoid "The first... The second... The third..." prose. Use a list or ``. + +Openings and endings: + +- Don't state a count before a list, such as "Four reasons to...". Instead just state it. +- Don't put evidence before the point. Lead with the point. +- Don't narrate the writing or your reasoning. For example, "It's worth being precise about...". +- Don't defend uncontroversial points or answer objections that nobody raised. +- Cut filler transitions: don't use "It's worth noting", "Importantly", "Interestingly", "Notably", "Here's the thing", "Here's the catch", or similar constructions. + +Word choice and tone: + +- Avoid marketing language: seamless, unlock, elevate, supercharge, game-changing, cutting-edge, unprecedented. Describe what the feature does. +- Do not inflate stakes. For example, "... fundamentally changes how you build software". +- Avoid empty intensifiers: quietly, deeply, fundamentally, remarkably, arguably, truly. +- Avoid stock AI vocabulary: delve, harness, utilize, leverage as a verb (use "use"), streamline, certainly, tapestry, landscape, paradigm, synergy, load-bearing, and "gated" meaning restricted. Use "ecosystem" and "framework" only in their literal technical sense. +- Don't coin labels, such as "the configuration trap" and "port drift", and use them as if they were established terms. +- Don't repeat a distinctive word or phrase from earlier in the page as a callback. +- Avoid analogies, such as "Think of it as...", "It's like a...", "Imagine a world where...", unless the analogy is clearer than the direct explanation. +- Avoid quotable one-liners that carry no information. +- Don't claim something is well known. For example avoid "famously", "notoriously", "a classic", and "as you know". +- Don't cite unnamed sources. Avoid "experts recommend", "many teams find", or similar. Link a specific source or drop the claim. +- Don't list historical companies or technology shifts to build authority. +- Avoid performative candor, such as "And yes, ..." or "To be honest, ...". +- Say where something is defined, stored, or configured, not "where it actually lives". + +Formatting: + +- Don't use em dashes or parenthesis for asides or dramatic pauses. Use commas, a colon, or two sentences. +- Don't start every bullet with a bold phrase. Bold lead-ins are for glossary-style definition lists only (see the glossary format in `.github/instructions/astro.instructions.md`). +- Don't use Unicode arrows (→) or curly quotes in prose. Write "then", "to", or use ``. Arrows are fine inside code and diagrams. + ## Icons and Images ### Icon Location diff --git a/.agents/skills/whatsnew/references/03-critique.md b/.agents/skills/whatsnew/references/03-critique.md index b945bb0f7..b9efaae47 100644 --- a/.agents/skills/whatsnew/references/03-critique.md +++ b/.agents/skills/whatsnew/references/03-critique.md @@ -21,6 +21,7 @@ actionable, severity-ranked findings report. **Makes no edits** — {polish} act - Sections and bullets lead with developer impact, ordered by customer DX. - Positives first; caveats/breaking changes appropriately placed. - KISS — no walls of text, no filler, no marketing superlatives. +- No patterns from doc-writer's "Prose patterns to avoid" list. **What's-new style adherence** - "This release introduces" bullets map **1:1** to the `##` sections, same order. diff --git a/.agents/skills/whatsnew/references/whats-new-template.mdx b/.agents/skills/whatsnew/references/whats-new-template.mdx index 9786ac910..4b96e5075 100644 --- a/.agents/skills/whatsnew/references/whats-new-template.mdx +++ b/.agents/skills/whatsnew/references/whats-new-template.mdx @@ -23,7 +23,7 @@ # placeholders, no researched prose. Content lands in {research}/{polish}. # ───────────────────────────────────────────────────────────────────────────── title: "What's new in Aspire {{VERSION_MAJOR_MINOR}}" -seoTitle: "TODO(polish): 50–60 char social-card title, e.g. What's new in Aspire {{VERSION_MAJOR_MINOR}} — , , and more" +seoTitle: "TODO(polish): 50–60 char social-card title, e.g. What's new in Aspire {{VERSION_MAJOR_MINOR}}: , , and more" description: "TODO(draft): one-sentence, SEO-friendly summary of the headline features in Aspire {{VERSION_MAJOR_MINOR}}. Trimmed to 200 chars for OG." sidebar: label: Aspire {{VERSION_MAJOR_MINOR}} diff --git a/.github/agents/community-toolkit-integration-doc-writer.agent.md b/.github/agents/community-toolkit-integration-doc-writer.agent.md index 713062f12..55b8d145d 100644 --- a/.github/agents/community-toolkit-integration-doc-writer.agent.md +++ b/.github/agents/community-toolkit-integration-doc-writer.agent.md @@ -184,6 +184,7 @@ prerequisites. Do not present the add-on as a standalone service. - Include explanations of what code does, especially for non-obvious patterns - For required parameters, list them with bullet points and descriptions - Reference NuGet packages with the 📦 emoji and link format: `[📦 PackageName](https://nuget.org/packages/PackageName)` +- Follow the "Prose patterns to avoid" list in the `doc-writer` skill (`.agents/skills/doc-writer/SKILL.md`). ### Common patterns diff --git a/.github/instructions/astro.instructions.md b/.github/instructions/astro.instructions.md index a6b0e3aa6..9bc743e3d 100644 --- a/.github/instructions/astro.instructions.md +++ b/.github/instructions/astro.instructions.md @@ -187,6 +187,7 @@ pageActions: false # disable AI/share actions var builder = DistributedApplication.CreateBuilder(args); ``` ```` +- Follow the "Prose patterns to avoid" list in the `doc-writer` skill (`.agents/skills/doc-writer/SKILL.md`). ### Bulleted List Grammar @@ -434,4 +435,4 @@ If a banner is present, dismiss it before any screenshot or visual verification. | `pnpm format` | Prettier formatting | | `pnpm update:integrations` | Sync NuGet integration data | | `pnpm update:samples` | Sync sample data from GitHub | -| `pnpm update:all` | Run all data updates | \ No newline at end of file +| `pnpm update:all` | Run all data updates | From 2d9e87a4d6fe3b9f3fcaf761ce396e19c439965d Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Fri, 2 Oct 2026 11:55:55 +0100 Subject: [PATCH 2/2] Integrated feedback from @IEvangelist. --- .agents/skills/doc-writer/SKILL.md | 49 +----------------- .../doc-writer/references/prose-patterns.md | 50 +++++++++++++++++++ .../skills/whatsnew/references/03-critique.md | 2 +- ...ty-toolkit-integration-doc-writer.agent.md | 2 +- .github/instructions/astro.instructions.md | 2 +- 5 files changed, 55 insertions(+), 50 deletions(-) create mode 100644 .agents/skills/doc-writer/references/prose-patterns.md diff --git a/.agents/skills/doc-writer/SKILL.md b/.agents/skills/doc-writer/SKILL.md index 8a3046669..9e07f3270 100644 --- a/.agents/skills/doc-writer/SKILL.md +++ b/.agents/skills/doc-writer/SKILL.md @@ -7,6 +7,8 @@ description: Guidelines for producing accurate and maintainable documentation fo This skill provides guidelines for AI coding agents to help maintainers produce accurate and easy-to-maintain documentation for the Aspire project. The aspire.dev repository is the official documentation site for Aspire, and this skill helps ensure consistent, high-quality documentation. +Before finishing any draft, check it against the [Prose Patterns skill reference](./references/prose-patterns.md). + ## Documentation Overview ### Site Structure @@ -820,53 +822,6 @@ Use consistent terminology throughout: - Use diverse, international examples - Avoid idioms and culturally-specific references -### Prose patterns to avoid - -AI-drafted text falls into recognizable patterns. One instance may be fine but several together make a page read as machine-written and cost the reader time. Before finishing a draft, check for these and rewrite them. - -Sentence structure: - -- Avoid sentences with more than four clauses if possible. Split such a sentence in order to be more direct. -- Avoid framing such as "It's not X, it's Y", "The question isn't X. It's Y", or "Not X. Not Y. Just Z." Instead, say what the thing is. -- Avoid self-answered questions such as "The result? Faster startup." Instead write "Startup is faster." -- Avoid sentence fragments used for emphasis, for example "Local. Fast. Free." Write complete sentences. -- Avoid groups of three used by reflex. List three items only when there are three things. -- Avoid trailing "-ing" clauses that add significance without information. For example, "..., highlighting its flexibility". -- Avoid short phrases hung off a final comma instead of finishing the sentence. -- Avoid "from X to Y" when X and Y aren't ends of a real range. -- Avoid "serves as", "stands as", or "represents" where "is" works. -- Avoid "The first... The second... The third..." prose. Use a list or ``. - -Openings and endings: - -- Don't state a count before a list, such as "Four reasons to...". Instead just state it. -- Don't put evidence before the point. Lead with the point. -- Don't narrate the writing or your reasoning. For example, "It's worth being precise about...". -- Don't defend uncontroversial points or answer objections that nobody raised. -- Cut filler transitions: don't use "It's worth noting", "Importantly", "Interestingly", "Notably", "Here's the thing", "Here's the catch", or similar constructions. - -Word choice and tone: - -- Avoid marketing language: seamless, unlock, elevate, supercharge, game-changing, cutting-edge, unprecedented. Describe what the feature does. -- Do not inflate stakes. For example, "... fundamentally changes how you build software". -- Avoid empty intensifiers: quietly, deeply, fundamentally, remarkably, arguably, truly. -- Avoid stock AI vocabulary: delve, harness, utilize, leverage as a verb (use "use"), streamline, certainly, tapestry, landscape, paradigm, synergy, load-bearing, and "gated" meaning restricted. Use "ecosystem" and "framework" only in their literal technical sense. -- Don't coin labels, such as "the configuration trap" and "port drift", and use them as if they were established terms. -- Don't repeat a distinctive word or phrase from earlier in the page as a callback. -- Avoid analogies, such as "Think of it as...", "It's like a...", "Imagine a world where...", unless the analogy is clearer than the direct explanation. -- Avoid quotable one-liners that carry no information. -- Don't claim something is well known. For example avoid "famously", "notoriously", "a classic", and "as you know". -- Don't cite unnamed sources. Avoid "experts recommend", "many teams find", or similar. Link a specific source or drop the claim. -- Don't list historical companies or technology shifts to build authority. -- Avoid performative candor, such as "And yes, ..." or "To be honest, ...". -- Say where something is defined, stored, or configured, not "where it actually lives". - -Formatting: - -- Don't use em dashes or parenthesis for asides or dramatic pauses. Use commas, a colon, or two sentences. -- Don't start every bullet with a bold phrase. Bold lead-ins are for glossary-style definition lists only (see the glossary format in `.github/instructions/astro.instructions.md`). -- Don't use Unicode arrows (→) or curly quotes in prose. Write "then", "to", or use ``. Arrows are fine inside code and diagrams. - ## Icons and Images ### Icon Location diff --git a/.agents/skills/doc-writer/references/prose-patterns.md b/.agents/skills/doc-writer/references/prose-patterns.md new file mode 100644 index 000000000..f0b7aefa3 --- /dev/null +++ b/.agents/skills/doc-writer/references/prose-patterns.md @@ -0,0 +1,50 @@ +# Prose Patterns + +When drafting text, be direct, use simple language, and keep sentences down to three or four clauses unless there is a good reason to write a longer sentence. + +## Prose patterns to avoid + +AI-drafted text falls into recognizable patterns. One instance may be fine but several together make a page read as machine-written and cost the reader time. Before finishing a draft, check for these and rewrite them. + +### Sentence structure + +- Avoid sentences with more than four clauses if possible. Split such a sentence in order to be more direct. +- Avoid framing such as "It's not X, it's Y", "The question isn't X. It's Y", or "Not X. Not Y. Just Z." Instead, say what the thing is. +- Avoid self-answered questions such as "The result? Faster startup." Instead write "Startup is faster." +- Avoid sentence fragments used for emphasis, for example "Local. Fast. Free." Write complete sentences. +- Avoid groups of three used by reflex. List three items only when there are three things. +- Avoid trailing "-ing" clauses that add significance without information. For example, "..., highlighting its flexibility". +- Avoid short phrases hung off a final comma instead of finishing the sentence. +- Avoid "from X to Y" when X and Y aren't ends of a real range. +- Avoid "serves as", "stands as", or "represents" where "is" works. +- Avoid "The first... The second... The third..." prose. Use a list or ``. + +### Openings and endings + +- Don't state a count before a list, such as "Four reasons to...". Instead just state it. +- Don't put evidence before the point. Lead with the point. +- Don't narrate the writing or your reasoning. For example, "It's worth being precise about...". +- Don't defend uncontroversial points or answer objections that nobody raised. +- Cut filler transitions: don't use "It's worth noting", "Importantly", "Interestingly", "Notably", "Here's the thing", "Here's the catch", or similar constructions. + +### Word choice and tone + +- Avoid marketing language: seamless, unlock, elevate, supercharge, game-changing, cutting-edge, unprecedented. Describe what the feature does. +- Do not inflate stakes. For example, "... fundamentally changes how you build software". +- Avoid empty intensifiers: quietly, deeply, fundamentally, remarkably, arguably, truly. +- Avoid stock AI vocabulary: delve, harness, utilize, leverage as a verb (use "use"), streamline, certainly, tapestry, landscape, paradigm, synergy, load-bearing, and "gated" meaning restricted. Use "ecosystem" and "framework" only in their literal technical sense. +- Don't coin labels, such as "the configuration trap" and "port drift", and use them as if they were established terms. +- Don't repeat a distinctive word or phrase from earlier in the page as a callback. +- Avoid analogies, such as "Think of it as...", "It's like a...", "Imagine a world where...", unless the analogy is clearer than the direct explanation. +- Avoid quotable one-liners that carry no information. +- Don't claim something is well known. For example avoid "famously", "notoriously", "a classic", and "as you know". +- Don't cite unnamed sources. Avoid "experts recommend", "many teams find", or similar. Link a specific source or drop the claim. +- Don't list historical companies or technology shifts to build authority. +- Avoid performative candor, such as "And yes, ..." or "To be honest, ...". +- Say where something is defined, stored, or configured, not "where it actually lives". + +### Formatting + +- Don't use em dashes or parenthesis for asides or dramatic pauses in new or edited prose. Use commas, a colon, or two sentences. +- Don't start every bullet with a bold phrase. Bold lead-ins are for glossary-style definition lists only (see the glossary format in `.github/instructions/astro.instructions.md`). +- Don't use Unicode arrows (→) or curly quotes in prose. Write "then", "to", or use ``. Arrows are fine inside code and diagrams. diff --git a/.agents/skills/whatsnew/references/03-critique.md b/.agents/skills/whatsnew/references/03-critique.md index b9efaae47..255351bb2 100644 --- a/.agents/skills/whatsnew/references/03-critique.md +++ b/.agents/skills/whatsnew/references/03-critique.md @@ -21,7 +21,7 @@ actionable, severity-ranked findings report. **Makes no edits** — {polish} act - Sections and bullets lead with developer impact, ordered by customer DX. - Positives first; caveats/breaking changes appropriately placed. - KISS — no walls of text, no filler, no marketing superlatives. -- No patterns from doc-writer's "Prose patterns to avoid" list. +- Follow the "Prose patterns to avoid" list in the `doc-writer` skill prose pattern reference (`.agents/skills/doc-writer/prose-patterns.md`). **What's-new style adherence** - "This release introduces" bullets map **1:1** to the `##` sections, same order. diff --git a/.github/agents/community-toolkit-integration-doc-writer.agent.md b/.github/agents/community-toolkit-integration-doc-writer.agent.md index 55b8d145d..ab8ee18c6 100644 --- a/.github/agents/community-toolkit-integration-doc-writer.agent.md +++ b/.github/agents/community-toolkit-integration-doc-writer.agent.md @@ -184,7 +184,7 @@ prerequisites. Do not present the add-on as a standalone service. - Include explanations of what code does, especially for non-obvious patterns - For required parameters, list them with bullet points and descriptions - Reference NuGet packages with the 📦 emoji and link format: `[📦 PackageName](https://nuget.org/packages/PackageName)` -- Follow the "Prose patterns to avoid" list in the `doc-writer` skill (`.agents/skills/doc-writer/SKILL.md`). +- Follow the "Prose patterns to avoid" list in the `doc-writer` skill prose pattern reference (`.agents/skills/doc-writer/prose-patterns.md`). ### Common patterns diff --git a/.github/instructions/astro.instructions.md b/.github/instructions/astro.instructions.md index 9bc743e3d..36e8ae906 100644 --- a/.github/instructions/astro.instructions.md +++ b/.github/instructions/astro.instructions.md @@ -187,7 +187,7 @@ pageActions: false # disable AI/share actions var builder = DistributedApplication.CreateBuilder(args); ``` ```` -- Follow the "Prose patterns to avoid" list in the `doc-writer` skill (`.agents/skills/doc-writer/SKILL.md`). +- Follow the "Prose patterns to avoid" list in the `doc-writer` skill prose pattern reference (`.agents/skills/doc-writer/prose-patterns.md`). ### Bulleted List Grammar