Improve writing style with rules in the doc-writer skill

.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 `<Steps>`.
+
+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 `<Steps>`. Arrows are fine inside code and diagrams.
+
 ## Icons and Images
 
 ### Icon Location

.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.

.agents/skills/whatsnew/references/whats-new-template.mdx

@@ -29,7 +29,7 @@ title: "What's new in Aspire {{VERSION_MAJOR_MINOR}}"
 resourceImage:
   light: "{{RESOURCE_IMAGE_LIGHT}}"
   dark: "{{RESOURCE_IMAGE_DARK}}"
-seoTitle: "TODO(polish): 50–60 char social-card title, e.g. What's new in Aspire {{VERSION_MAJOR_MINOR}} — <theme 1>, <theme 2>, and more"
+seoTitle: "TODO(polish): 50–60 char social-card title, e.g. What's new in Aspire {{VERSION_MAJOR_MINOR}}: <theme 1>, <theme 2>, 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}}

.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
 

.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 |
+| `pnpm update:all` | Run all data updates |