Updates from review on #53542

Several themes came through this review. Update the prompts to match.

Author: BillWagner

.github/projects/EverydayCSharp-ProjectMap.md

@@ -5,15 +5,16 @@ the [feature inclusion notes](#feature-coverage-decisions).
 
 ## Goals
 
-1. **Fundamentals lives in a four-tier content structure.** The C# documentation follows a progressive organization: *Get started* for beginners new to programming or C#, *Fundamentals* for developers learning everyday C#, *Deep dives* (Focus/Advanced sections) for specialized or advanced topics, and *Reference* for complete language syntax and API details. Every article should include a tip near the top that identifies where the article sits in this progression and who it's written for. The tip should describe the types of readers who would benefit most, identify readers who might need to start with *Get started* content first (for example, developers new to programming, or developers unfamiliar with object-oriented concepts), and identify readers with relevant experience who can skip ahead (for example, experienced C# developers or other experienced developers in a similar language, like Java or C++, who can jump directly to *Deep dives* or *Reference*).
+1. **Fundamentals lives in a four-tier content structure.** The C# documentation follows a progressive organization: *Get started* for beginners new to programming or C#, *Fundamentals* for developers learning everyday C#, *Deep dives* (Focus/Advanced sections) for specialized or advanced topics, and *Reference* for complete language syntax and API details. Every article should include a tip near the top that identifies where the article sits in this progression and who it's written for. The tip should describe the types of readers who would benefit most, identify readers who might need to start with *Get started* content first (for example, developers new to programming, or developers unfamiliar with object-oriented concepts), and identify readers with relevant experience who can skip ahead (for example, experienced C# developers or other experienced developers in a similar language, like Java or C++, who can jump directly to *Deep dives* or *Reference*). Because Fundamentals readers don't yet carry C# vocabulary across articles, define every C# term at first use within the article — including terms the author considers obvious (for example, *dereference*, *type parameter* vs. *type argument*) — and link to the deeper reference.
 1. **Make Fundamentals complete.** A developer learning C# should be able to read the Fundamentals section and understand "Everyday C#" — the features and patterns used in the vast majority of production code.
 1. **Pull content toward the goal.** Rather than focusing on migrating content *out* of legacy sections (Tutorials, C# concepts, How-to, Programming guide), we focus on building a great Fundamentals section and pull content in as it fits.
-1. **Teach through examples.** Most engineers learn software languages by reading and writing example code, not by reading *about* the language. Every article in the Fundamentals section should be example-heavy: short prose introduces a concept, then one or more code samples demonstrate it in context. Favor showing over telling. Keep each sample as small and focused as possible—demonstrate one concept per example. Don't introduce additional concepts, patterns, or API calls that aren't directly relevant to the point being made. If a reader has to understand something unrelated to follow the sample, the sample is doing too much.
+1. **Teach through examples.** Most engineers learn software languages by reading and writing example code, not by reading *about* the language. Every article in the Fundamentals section should be example-heavy: short prose introduces a concept, then one or more code samples demonstrate it in context. Favor showing over telling. Keep each sample as small and focused as possible—demonstrate one concept per example. Don't introduce additional concepts, patterns, or API calls that aren't directly relevant to the point being made. If a reader has to understand something unrelated to follow the sample, the sample is doing too much. Samples must be readable on first pass: for any construct the sample isn't teaching, use the most familiar form (`while` or `foreach` before `for`; a regular method before a static factory). Add a brief intent comment on any line whose purpose isn't immediately obvious (especially lines like `_ = something;` or literal arguments with hidden significance). When the sample illustrates a decision, show *both* branches and include the result as a trailing comment (`// => …`) so readers correlate code to output without running it.
 1. **Follow the C# standard's organization.** The section ordering mirrors the [C# standard](https://github.com/dotnet/csharpstandard/blob/main/standard/README.md) (§7 Basic concepts → §8 Types → §11 Patterns → §12 Expressions → §15 Classes → §22 Exceptions → §23 Attributes). Content not in the standard appears after standard-aligned sections.
 1. **Emphasize everday C#.** Everyday C# features get fuller explanations. Older features that readers (including AI agents and Copilots) already have extensive information about receive lighter treatment. All sample code uses the latest released syntax and idioms.
 1. **Target audience.** Developers who know at least one other programming language and are learning C#, or C# developers updating their knowledge of the latest features and idioms. Not absolute beginners in programming.
 1. **Samples showcase Everday C# feature sets.** All sample code across the Fundamentals section should incorporate the language features listed in [Include and explain](#include-and-explain), [Use in sample code without detailed explanation](#use-in-sample-code-without-detailed-explanation), and the relevant subsets from [Include a subset](#include-a-subset). This means even an article about, for example, exception handling should use collection expressions, file-scoped namespaces, nullable reference types, raw string literals, and other everyday C# features in its samples — not just the feature under discussion. Readers absorb these idioms organically by seeing them used consistently.
 1. **Gently opinionated.** Guide new readers toward the recommended way to accomplish tasks in modern C#. When multiple language features solve the same problem, present the recommended feature as the default and mention the other alternative briefly, if at all. Every recommendation must include a justification—state *why* the recommended approach is preferred (for example, improved readability, better tooling support, stronger type safety, or reduced boilerplate). Don't just say "use X"; say "use X because it provides Y." However, never describe older features as obsolete or deprecated—they aren't. Nothing in this section should suggest that developers need to update existing working code. The guidance is forward-looking: when writing *new* code, prefer the recommended approach.
+1. **Default to the current-project frame, and teach how to verify settings.** Most Fundamentals readers are either starting a new project or following along in a freshly created one, so the default frame for any setup or configuration statement is a current project from a recent template. That keeps the prose concrete and the samples runnable without setup detours. *Lead with the current-project assumption* — for example, "New projects from recent templates set `<Nullable>enable</Nullable>` in the project file" — and don't open with hedges. *Immediately follow* such statements with a one- or two-sentence pointer that shows existing-project readers where to verify the setting in their own `.csproj` and how to enable it if it's missing. *Reserve full migration guidance for the migration articles*: when the existing-project path is more than a setting check (for example, planning a phased rollout), link out rather than inlining the strategy. When a feature is recommended as the fix for a diagnostic, run the code and confirm the diagnostic actually clears in the scenario being recommended.
 
 ## Include major topic types
 
@@ -111,6 +112,7 @@ entirely.
 
 - *Structure each article as concept → example → concept → example*, not as a wall of prose with a code block at the end.
 - *Prefer small, focused examples* that each illustrate one point, over large monolithic samples.
+- *Make each sample readable on first pass.* For any construct a sample isn't teaching, pick the most familiar form (`while` or `foreach` before `for`; a regular method before a static factory). Add a brief intent comment on any line whose purpose isn't obvious. When the sample illustrates a decision, show both branches and print the result as a trailing comment (`// => …`).
 - *Review every sample's using directives, type declarations, and local variables* to confirm they use the latest syntax (e.g., `global using`, file-scoped namespace, `var`, collection expressions, primary constructors) even when those features aren't the article's topic.
 - *Treat the three feature tables as a checklist* when writing or reviewing samples. If a feature from "Use in sample code without detailed explanation" appears naturally, use it without commentary. If a feature from "Include a subset" is relevant to the scenario, include it with a brief link to its full article.
 

.github/projects/EverydayCSharp-planFundamentalsRestructuring.prompt.md

@@ -3,24 +3,52 @@
 **TL;DR:** Break the ~91-article restructuring into ~31 small, independently mergeable PRs organized in proposed TOC order. Each PR touches ≤10 files (articles, snippets, toc.yml, redirects), adds its content to the live TOC immediately, and leaves the section in a publishable state. Every new or revised article follows the example-heavy, latest-version-saturation style from Goals 4 and 8.
 
 **Conventions for every PR:**
-- Update `toc.yml` incrementally so new content is navigable immediately.
-- Add redirect entries for every moved file (use the "/.openpublishing/redirection.csharp.json" file).
-- All snippet code uses the full "Everyday C#" feature set per the feature tables.
-- Prefer file based apps over larger project-based samples for simplicity and ease of understanding, unless a feature requires a more complex setup.
+
+The Fundamentals audience is a developer who knows another language and is learning C#. An alternative audience is a new developer that has only months of experience with C# as their first programming language. They don't yet have C# vocabulary, can't recognize C#-specific idioms on sight, and don't share the project context an experienced C# developer takes for granted. The conventions below are grouped by the audience-derived principle they serve so each one's *why* stays visible.
+
+*Sample readability (P1) — write samples that a new C# developer can read line-by-line:*
+
 - All code examples are included from external snippet files (no inline code blocks), and every article has a corresponding snippet project.
+- All snippet code uses the full "Everyday C#" feature set per the feature tables.
+- Prefer file-based apps over larger project-based samples for simplicity and ease of understanding, unless a feature requires a more complex setup.
+- For any construct the sample isn't teaching, pick the most familiar form: use `while` or `foreach` before `for` (reserve `for` for explicit index iteration); use a regular method before a static factory unless the article is about factories.
+- Add a brief intent comment on any line whose purpose isn't immediately obvious — for example, lines like `_ = something;` or a literal argument with hidden significance.
+- When a sample illustrates a decision, show *both* branches and include the result as a trailing comment (`// => …`) so readers correlate code to output without running it.
+- Never place consecutive code snippets. They are hard to read and harder for readers to follow. Either intersperse explanatory text between snippets or combine related snippets into a single example.
+
+*Terminology (P2) — treat every C# term as new until the article defines it:*
+
+- Define concepts when they are first introduced. Don't assume readers know what a "type" or "namespace" is before those concepts are covered in the proposed TOC. Remember that this is "fundamentals" content. Any term likely to be unfamiliar to a new C# developer should be defined inline at first use — one short sentence — with a link to the deeper reference. This applies to terms the author considers obvious (for example, *dereference*, *type parameter* vs. *type argument*, *primary constructor*), not just terms the author considers new.
+- When a symbol's meaning depends on context (`T?` differs between value types, constrained reference types, and unconstrained generics), spell out which form you mean before listing rules. Lead a constraints discussion with a one-line model of what is being constrained.
+- Definitions are less important for concepts that aren't related to the C# language. The goal for Fundamentals is to teach readers how C# works. While we teach through examples, the libraries and packages used in the examples are less important than the language features being demonstrated. For example, when teaching about collections, it's more important to explain what a collection is and how to use them in C# than to provide an in-depth explanation of `List<T>` vs. `Dictionary<K,V>`.
+- Cross reference liberally. It's assumed readers are familiar with content in the "Get started" section, so links there should be minimal and scoped to recommendations for beginners to start there instead. Links and cross references should encourage readers to learn more and dive deeper into the fundamental concepts covered in this section.
+- If and only if a feature was first added in one of the last three released versions (C# 12–14), mention when it was first introduced.
+
+*Reader's project frame (P3) — default to a current project, and teach how to verify settings:*
+
+- Lead with the current-project assumption. "New projects from recent templates set `<Nullable>enable</Nullable>` in the project file" is the default framing for any setup or configuration statement — no opening hedge.
+- Immediately follow such statements with a one- or two-sentence pointer that shows existing-project readers where to verify the setting in their own `.csproj` and how to enable it if it's missing.
+- Reserve full migration guidance for the migration articles. When the existing-project path is more than a setting check (for example, planning a phased rollout), link out rather than inlining the strategy.
+- When a feature is recommended as the fix for a diagnostic, run the code and confirm the diagnostic actually clears in the scenario being recommended. Reviewer skepticism ("does that actually work here?") usually means the verification wasn't done.
+- When recommending a modern feature over an older alternative, always include a justification — state *why* the recommended approach is preferred. Never describe older features as obsolete or deprecated (Goal 9).
+
+*Structural hygiene that supports the principles above:*
+
 - Each article follows concept → example → concept → example structure. The concept discussion should include motivating scenarios for the feature or concept being covered.
-- Prefer articles that are between a 5 and 10 minute read (roughly 1000–2000 words). Longer and shorter artiles are allowed, but should be the exception.
-- Cross reference liberally. However, it's assumed that readers are familiar with content in the "Get started" section. Links to that section should be minimal, and possibly scoped to recommendations for beginners to start there instead. Links and cross references should encourage readers to learn more and dive deeper into the fundamental concepts covered in this section.
-- If and only if a feature was first added in one of the last three released versions (C# 12 - 14) mention the first it was first introduced.
+- One topic per paragraph. A new case (for example, "the same pitfall also applies to arrays of structs") starts a new paragraph.
+- Promote a bold paragraph-lead to `###` when it anchors more than one paragraph of content. Inline bold disappears in the TOC and is harder to scan.
+- Replace long "the rule is simple" prose with a short structured rule — a one-sentence lead, bold trigger words, then a two- or three-bullet list or a labeled example.
+- Prefer articles that are between a 5- and 10-minute read (roughly 1000–2000 words). Longer and shorter articles are allowed, but should be the exception.
+
+*Mechanics — TOC, metadata, links, redirects:*
+
+- Update `toc.yml` incrementally so new content is navigable immediately.
+- Add redirect entries for every moved file (use the "/.openpublishing/redirection.csharp.json" file).
 - Every article must include a tip near the top that identifies where the article sits in the four-tier content structure (*Get started* → *Fundamentals* → *Deep dives* → *Reference*), describes who it's written for, and routes readers to the right tier based on their experience level (Goal 1).
-- Define concepts when they are first introduced. Don't assume readers know what a "type" or "namespace" is before those concepts are covered in the proposed TOC. Remember that this is "fundamentals" content. Any term likely to be unfamiliar to a new C# developer should be defined. When defining a concept, link to articles that provide more detail. Definitions are less important for concepts that aren't related to the C# language: Remember the goal for Fundamentals is to teach readers how C# works. While we teach through examples, the libraries and packages used in the examples are less important than the language features being demonstrated. For example, when teaching about collections, it's more important to explain what a collection is and how to use them in C# than to provide an in-depth explanation of `List<T>` vs. `Dictionary<K,V>`.
-- Similarly, define all terms that may be unfamiliar to the reader when they are first introduced. Link to articles that provide more detail on these terms. Remember that the audience for Fundamentals articles is new to C# and the .NET ecosystem. They are likely not to be familiar with all C# terminology, or all computer science terminology. Provide clear definitions and context.
 - Set the `ms.topic` metadata value in each article's YAML front matter to match the article's content type (`overview`, `tutorial`, `concept`, `how-to`, `troubleshooting`, or `reference`).
 - After writing content, verify the article's structure, required metadata, and sections against the template for its content type (see the [Include major topic types](EverydayCSharp-ProjectMap.md#include-major-topic-types) table for template links). This is mandatory for every article before it can be merged to ensure consistency and completeness across the Fundamentals section.
 - Do not add F1 or helpviewer keywords to Fundamentals articles. When pulling content from the Reference section, remove any F1 or helpviewer keywords.
-- When recommending a modern feature over an older alternative, always include a justification—state *why* the recommended approach is preferred. Never describe older features as obsolete or deprecated (Goal 9).
 - Do not add links to files that will be created in future PRs until those files are live. For example, if PR 3 creates the `fundamentals/types/enums.md` article, then earlier PRs should not link to that file until PR 3 is merged. This may require some temporary duplication of content or placeholders for links, but it will prevent broken links in merged PRs. Instead, when an article is created, add appropriate links to it in earlier articles as needed to connect the content together.
-- Never place consecutive code snippets. They are hard to read and harder for readers to follow. Either intersperse explanatory text between snippets or combine related snippets into a single example.
 
 ## Phase A: Program Structure (§7)