From 1ed85b7a6f65e285a80034c6f7f42793e40c1016 Mon Sep 17 00:00:00 2001 From: Serhiiiiko <2021elit0049@ms.sumdu.edu.ua> Date: Mon, 16 Mar 2026 12:29:12 +0200 Subject: [PATCH 1/4] "Enhance SKILL.md with gradual Roslyn warning promotion and detailed workflow for legacy projects." --- skills/dotnet-code-analysis/SKILL.md | 172 ++++++++++++++++-- .../dotnet-code-analysis/references/config.md | 20 +- 2 files changed, 174 insertions(+), 18 deletions(-) diff --git a/skills/dotnet-code-analysis/SKILL.md b/skills/dotnet-code-analysis/SKILL.md index b21e1b4..a86f92e 100644 --- a/skills/dotnet-code-analysis/SKILL.md +++ b/skills/dotnet-code-analysis/SKILL.md @@ -1,8 +1,8 @@ --- name: dotnet-code-analysis -version: "1.0.0" +version: "1.0.1" category: "Code Quality" -description: "Use the free built-in .NET SDK analyzers and analysis levels. Use when a .NET repo needs first-party code analysis, `EnableNETAnalyzers`, `AnalysisLevel`, or warning policy wired into build and CI." +description: "Use the free built-in .NET SDK analyzers and analysis levels with gradual Roslyn warning promotion. Use when a .NET repo needs first-party code analysis, `EnableNETAnalyzers`, `AnalysisLevel`, or warning-as-error policy wired into build and CI." compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENTS.md` commands first." --- @@ -13,6 +13,7 @@ compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENT - the repo wants first-party .NET analyzers - CI should fail on analyzer warnings - the team needs `AnalysisLevel` or `AnalysisMode` guidance +- the repo needs a gradual Roslyn warning promotion strategy ## Value @@ -37,17 +38,152 @@ compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENT 2. Run this skill's `Workflow` through the `Ralph Loop` until outcomes are acceptable. 3. Return the `Required Result Format` with concrete artifacts and verification evidence. +## Hard Rules for AI Agents + +These rules are non-negotiable. Violating them undermines the user's explicit intent. + +1. **Never disable or remove `TreatWarningsAsErrors` or `WarningsAsErrors`** if the user or the project has set them. Do not comment them out, set them to `false`, move them behind a condition, or add `false` to make the build pass. +2. **Never add `` entries or `#pragma warning disable` to suppress warnings that the user has chosen to treat as errors**, unless the user explicitly approves the suppression for a specific case. +3. **Never silently downgrade rule severity** in `.editorconfig` (e.g., changing `error` to `warning` or `none`) to make a build succeed. +4. If a build fails because of warnings-as-errors, **fix the actual code issue**. If the fix is too large or risky, **ask the user** whether to defer that specific warning ID instead of silently disabling it. +5. If the volume of warnings is too large to fix in one pass, **report the count and categories to the user** and ask which ones to tackle first — do not unilaterally disable the policy. + ## Workflow +### Decision Flow + +```mermaid +flowchart TD + A[Start: code analysis requested] --> B{Project type?} + B -->|New project| C[Apply strict policy from the start] + B -->|Legacy / existing| D[Scan current warning count] + C --> E[Enable TreatWarningsAsErrors globally] + C --> F[Set AnalysisLevel latest-recommended] + C --> G["Promote security CA3xxx/CA5xxx to error"] + D --> H{Warning count?} + H -->|"< 30 warnings"| I[Fix all, then enable TreatWarningsAsErrors] + H -->|"> 30 warnings"| J[Ask user: which categories first?] + J --> K[Use WarningsAsErrors with specific IDs] + K --> L[Fix warnings in the selected batch] + L --> M[Build passes? Add next batch] + M --> N{More categories to promote?} + N -->|Yes| J + N -->|No| O[Transition to TreatWarningsAsErrors = true] + I --> O + E --> O + O --> P[Validate: build + CI green] +``` + +### Steps + 1. Start with SDK analyzers before adding third-party packages. -2. Enable or document: +2. **Detect project maturity**: is this a new project or an existing/legacy codebase? +3. Enable or document: - `EnableNETAnalyzers` - `AnalysisLevel` - `AnalysisMode` - - warning policy such as `TreatWarningsAsErrors` -3. Keep per-rule severity in the repo-root `.editorconfig`. -4. Use `dotnet build` as the analyzer execution gate in CI. -5. Add third-party analyzers only for real gaps that first-party rules do not cover. +4. **Apply the right warning promotion strategy** (see below). +5. Keep per-rule severity in the repo-root `.editorconfig`. +6. Use `dotnet build` as the analyzer execution gate in CI. +7. Add third-party analyzers only for real gaps that first-party rules do not cover. + +## Warning Promotion Strategy + +### New Projects + +For new or small projects with few existing warnings: + +- Set `true` in `Directory.Build.props` immediately. +- Set `latest-recommended`. +- Promote security rules (CA3xxx, CA5xxx) to error in `.editorconfig`. +- Fix all warnings before merging. The project is young enough that this is manageable. + +### Legacy / Existing Projects — Gradual Promotion + +For established codebases, a blanket `TreatWarningsAsErrors` will produce hundreds or thousands of errors. An AI agent cannot realistically fix them all at once, and attempting it will flood context and produce low-quality fixes. Instead, promote warnings to errors in deliberate batches. + +#### Phase 1: Trivial Hygiene (lowest effort, highest signal-to-noise) + +Start here. These warnings are trivial to fix mechanically and reduce noise for the real work: + +| Warning ID | Description | Typical fix | +|-----------|-------------|-------------| +| CS8019 | Unnecessary using directive | Remove the unused using | +| CS0219 | Variable assigned but never used | Remove the variable | +| CS0168 | Variable declared but never used | Remove the variable | +| CS1591 | Missing XML comment for public type/member | Add doc comment or disable for internal code | +| CS0612 | Use of obsolete member (no message) | Replace with non-obsolete API | +| CS0618 | Use of obsolete member (with message) | Follow the migration guidance | + +Promote these first: + +```xml + + CS8019;CS0219;CS0168 + +``` + +Fix all occurrences, then move to Phase 2. + +#### Phase 2: Code Quality (medium effort, high value) + +| Warning ID | Description | Category | +|-----------|-------------|----------| +| CA2000 | Dispose objects before losing scope | Reliability | +| CA1062 | Validate arguments of public methods | Design | +| CA1822 | Mark members as static | Performance | +| CA1860 | Avoid using Enumerable.Any() for length check | Performance | +| CA1861 | Avoid constant arrays as arguments | Performance | +| CA2007 | Consider calling ConfigureAwait | Reliability | +| CS8600–CS8610 | Nullable reference type warnings | Nullability | + +**Ask the user**: "Which of these categories do you want to promote next? Nullability? Performance? Reliability?" + +Add the selected IDs to `WarningsAsErrors` and fix them before adding more. + +#### Phase 3: Security (high priority, always promote) + +| Warning ID | Description | +|-----------|-------------| +| CA3001 | Review code for SQL injection | +| CA3002 | Review code for XSS | +| CA3003 | Review code for file path injection | +| CA3075 | Insecure DTD processing | +| CA5350 | Do not use weak cryptographic algorithms | +| CA5351 | Do not use broken cryptographic algorithms | +| CA5394 | Do not use insecure randomness | + +These should be promoted to error early regardless of project maturity. Set in `.editorconfig`: + +```editorconfig +[*.cs] +dotnet_analyzer_diagnostic.category-Security.severity = error +``` + +#### Phase 4: Full Coverage + +Once all targeted batches pass cleanly, transition from selective `WarningsAsErrors` to global `TreatWarningsAsErrors`: + +```xml + + true + + CA1707 + +``` + +### Interaction Protocol + +When applying warning promotion to a legacy codebase: + +1. **Run `dotnet build` and count warnings** by ID and category. +2. **Report the summary to the user**: "Found 47 CS8019, 23 CA1822, 12 CA2000, 8 CS8600 warnings." +3. **Ask the user which batch to tackle**: "I recommend starting with CS8019 (unused usings) and CS0219 (unused variables) — these are mechanical fixes. Want me to proceed?" +4. **Fix the selected batch** and verify the build passes. +5. **Add those IDs to `WarningsAsErrors`** so they stay enforced going forward. +6. **Report back** and ask about the next batch. + +Never skip the ask step. The user decides the pace. ## Bootstrap When Missing @@ -55,26 +191,33 @@ If first-party .NET code analysis is requested but not configured yet: 1. Detect current state: - `dotnet --info` - - `rg -n "EnableNETAnalyzers|AnalysisLevel|AnalysisMode|TreatWarningsAsErrors" -g '*.csproj' -g 'Directory.Build.*' .` + - `rg -n "EnableNETAnalyzers|AnalysisLevel|AnalysisMode|TreatWarningsAsErrors|WarningsAsErrors" -g '*.csproj' -g 'Directory.Build.*' .` + - `dotnet build SOLUTION_OR_PROJECT 2>&1` — count current warnings by ID 2. Treat SDK analyzers as built-in functionality, not as a separate third-party install path. -3. Enable the needed properties in the solution's MSBuild config, typically in `Directory.Build.props` or the target project file: +3. Classify the project: new (few or zero warnings) vs. legacy (many warnings). +4. Enable the needed properties in the solution's MSBuild config, typically in `Directory.Build.props` or the target project file: - `EnableNETAnalyzers` - `AnalysisLevel` - `AnalysisMode` when needed - - warning policy such as `TreatWarningsAsErrors` -4. Keep rule-level severity in the repo-root `.editorconfig`. -5. Run `dotnet build SOLUTION_OR_PROJECT` and return `status: configured` or `status: improved`. -6. If the repo intentionally defers analyzer policy to another documented build layer, return `status: not_applicable`. +5. **Apply the appropriate warning promotion strategy** based on project maturity: + - New project: apply strict policy immediately. + - Legacy project: start with Phase 1 and ask the user before each batch. +6. Keep rule-level severity in the repo-root `.editorconfig`. +7. Run `dotnet build SOLUTION_OR_PROJECT` and return `status: configured` or `status: improved`. +8. If the repo intentionally defers analyzer policy to another documented build layer, return `status: not_applicable`. ## Deliver - first-party analyzer policy that is explicit and reviewable - build-time analyzer execution for CI +- warning promotion roadmap that matches the project's maturity ## Validate - analyzer behavior is driven by repo config, not IDE defaults - CI can reproduce the same warnings and errors locally +- no `TreatWarningsAsErrors`, `WarningsAsErrors`, or severity settings were removed or weakened by the agent without user approval +- promoted warnings produce build errors, not just IDE hints ## Ralph Loop @@ -113,3 +256,6 @@ For setup-only requests with no execution, return `status: configured` and exact - "Turn on built-in .NET analyzers." - "Make analyzer warnings fail the build." - "Set the right `AnalysisLevel` for this repo." +- "Start treating unused usings and unused variables as errors." +- "Help me gradually promote Roslyn warnings in my legacy project." +- "Which warnings should I promote to errors next?" diff --git a/skills/dotnet-code-analysis/references/config.md b/skills/dotnet-code-analysis/references/config.md index 4db511f..2598893 100644 --- a/skills/dotnet-code-analysis/references/config.md +++ b/skills/dotnet-code-analysis/references/config.md @@ -95,17 +95,27 @@ Available categories: `Design`, `Documentation`, `Globalization`, `Interoperabil ``` -Makes all warnings fail the build. Combine with explicit severity settings to control which rules are promoted. +Makes all warnings fail the build. Best for new projects or mature codebases that have already cleared their warning backlog. Combine with `WarningsNotAsErrors` for explicit exceptions. -### WarningsAsErrors (Selective) +**Agent rule**: never disable, remove, or comment out this property to make a build pass. Fix the code instead or ask the user. + +### WarningsAsErrors (Selective — Preferred for Legacy Codebases) ```xml - CA2000;CA3001 + CS8019;CS0219;CS0168;CA2000;CA3001 ``` -Promote specific warnings to errors without affecting others. +Promote specific warnings to errors without affecting others. This is the recommended approach for gradual adoption in legacy projects: + +1. Start with trivial hygiene warnings (CS8019 unused usings, CS0219/CS0168 unused variables). +2. Fix all occurrences in the codebase. +3. Add the IDs to `WarningsAsErrors` so they stay enforced. +4. Ask the user which category to promote next. +5. Repeat until the codebase is clean enough to switch to `TreatWarningsAsErrors`. + +**Agent rule**: never remove IDs from this list to make a build pass. The user chose these IDs deliberately. ### WarningsNotAsErrors @@ -116,7 +126,7 @@ Promote specific warnings to errors without affecting others. ``` -Keep specific warnings as warnings when using `TreatWarningsAsErrors`. +Keep specific warnings as warnings when using `TreatWarningsAsErrors`. Use this for rules the team has explicitly decided to defer. ### NoWarn From 1a2839f74ba9b467827a1b55e22b17e61813a186 Mon Sep 17 00:00:00 2001 From: Serhiiiiko <2021elit0049@ms.sumdu.edu.ua> Date: Mon, 16 Mar 2026 12:34:02 +0200 Subject: [PATCH 2/4] Removed fancy text for humans to read , remade it so it will be more agent friendly and take less token context --- skills/dotnet-code-analysis/SKILL.md | 257 ++++++---------- .../dotnet-code-analysis/references/config.md | 279 ++---------------- 2 files changed, 126 insertions(+), 410 deletions(-) diff --git a/skills/dotnet-code-analysis/SKILL.md b/skills/dotnet-code-analysis/SKILL.md index a86f92e..5e5238d 100644 --- a/skills/dotnet-code-analysis/SKILL.md +++ b/skills/dotnet-code-analysis/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-code-analysis -version: "1.0.1" +version: "2.0.0" category: "Code Quality" description: "Use the free built-in .NET SDK analyzers and analysis levels with gradual Roslyn warning promotion. Use when a .NET repo needs first-party code analysis, `EnableNETAnalyzers`, `AnalysisLevel`, or warning-as-error policy wired into build and CI." compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENTS.md` commands first." @@ -15,12 +15,6 @@ compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENT - the team needs `AnalysisLevel` or `AnalysisMode` guidance - the repo needs a gradual Roslyn warning promotion strategy -## Value - -- produce a concrete project delta: code, docs, config, tests, CI, or review artifact -- reduce ambiguity through explicit planning, verification, and final validation skills -- leave reusable project context so future tasks are faster and safer - ## Do Not Use For - third-party analyzer selection by itself @@ -32,230 +26,167 @@ compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENT - project files or `Directory.Build.props` - current analyzer severity policy -## Quick Start - -1. Read the nearest `AGENTS.md` and confirm scope and constraints. -2. Run this skill's `Workflow` through the `Ralph Loop` until outcomes are acceptable. -3. Return the `Required Result Format` with concrete artifacts and verification evidence. - ## Hard Rules for AI Agents -These rules are non-negotiable. Violating them undermines the user's explicit intent. +Non-negotiable. Violating these undermines the user's explicit intent. -1. **Never disable or remove `TreatWarningsAsErrors` or `WarningsAsErrors`** if the user or the project has set them. Do not comment them out, set them to `false`, move them behind a condition, or add `false` to make the build pass. -2. **Never add `` entries or `#pragma warning disable` to suppress warnings that the user has chosen to treat as errors**, unless the user explicitly approves the suppression for a specific case. -3. **Never silently downgrade rule severity** in `.editorconfig` (e.g., changing `error` to `warning` or `none`) to make a build succeed. -4. If a build fails because of warnings-as-errors, **fix the actual code issue**. If the fix is too large or risky, **ask the user** whether to defer that specific warning ID instead of silently disabling it. -5. If the volume of warnings is too large to fix in one pass, **report the count and categories to the user** and ask which ones to tackle first — do not unilaterally disable the policy. +1. Never disable or remove `TreatWarningsAsErrors` or `WarningsAsErrors` if the project has set them. Do not comment them out, set to `false`, wrap in a condition, or add `false` to make the build pass. +2. Never add `` or `#pragma warning disable` for warnings the user chose to treat as errors, unless the user explicitly approves the suppression. +3. Never silently downgrade severity in `.editorconfig` (e.g. `error` to `warning` or `none`) to make a build succeed. +4. If warnings-as-errors breaks the build — fix the code. If the fix is too large, ask the user whether to defer that warning ID. +5. If warning volume is too large to fix in one pass — report count and categories to the user and ask which to tackle first. Do not unilaterally disable the policy. ## Workflow -### Decision Flow - ```mermaid flowchart TD - A[Start: code analysis requested] --> B{Project type?} - B -->|New project| C[Apply strict policy from the start] - B -->|Legacy / existing| D[Scan current warning count] - C --> E[Enable TreatWarningsAsErrors globally] - C --> F[Set AnalysisLevel latest-recommended] - C --> G["Promote security CA3xxx/CA5xxx to error"] - D --> H{Warning count?} - H -->|"< 30 warnings"| I[Fix all, then enable TreatWarningsAsErrors] - H -->|"> 30 warnings"| J[Ask user: which categories first?] - J --> K[Use WarningsAsErrors with specific IDs] - K --> L[Fix warnings in the selected batch] - L --> M[Build passes? Add next batch] - M --> N{More categories to promote?} - N -->|Yes| J - N -->|No| O[Transition to TreatWarningsAsErrors = true] - I --> O - E --> O - O --> P[Validate: build + CI green] + A[Start] --> B{New or legacy project?} + B -->|New| C[TreatWarningsAsErrors=true immediately] + B -->|Legacy| D[dotnet build, count warnings by ID] + D --> E{"< 30 warnings?"} + E -->|Yes| F[Fix all, then enable TreatWarningsAsErrors] + E -->|No| G[Report counts to user, ask which batch first] + G --> H[Add selected IDs to WarningsAsErrors] + H --> I[Fix that batch, verify build] + I --> J{More batches?} + J -->|Yes| G + J -->|No| F + C --> K[Set AnalysisLevel latest-recommended] + F --> K + K --> L[Promote security CA3xxx/CA5xxx to error in .editorconfig] + L --> M[Validate: build + CI green] ``` -### Steps - -1. Start with SDK analyzers before adding third-party packages. -2. **Detect project maturity**: is this a new project or an existing/legacy codebase? -3. Enable or document: - - `EnableNETAnalyzers` - - `AnalysisLevel` - - `AnalysisMode` -4. **Apply the right warning promotion strategy** (see below). -5. Keep per-rule severity in the repo-root `.editorconfig`. -6. Use `dotnet build` as the analyzer execution gate in CI. -7. Add third-party analyzers only for real gaps that first-party rules do not cover. +1. Start with SDK analyzers before third-party packages. +2. Detect project maturity: new or existing/legacy. +3. Enable `EnableNETAnalyzers`, `AnalysisLevel`, `AnalysisMode` in `Directory.Build.props`. +4. Apply the right warning promotion strategy (see below). +5. Per-rule severity goes in repo-root `.editorconfig`. +6. `dotnet build` is the analyzer gate in CI. ## Warning Promotion Strategy ### New Projects -For new or small projects with few existing warnings: - -- Set `true` in `Directory.Build.props` immediately. -- Set `latest-recommended`. -- Promote security rules (CA3xxx, CA5xxx) to error in `.editorconfig`. -- Fix all warnings before merging. The project is young enough that this is manageable. - -### Legacy / Existing Projects — Gradual Promotion - -For established codebases, a blanket `TreatWarningsAsErrors` will produce hundreds or thousands of errors. An AI agent cannot realistically fix them all at once, and attempting it will flood context and produce low-quality fixes. Instead, promote warnings to errors in deliberate batches. - -#### Phase 1: Trivial Hygiene (lowest effort, highest signal-to-noise) +Set these in `Directory.Build.props` immediately: +- `TreatWarningsAsErrors` = true +- `AnalysisLevel` = latest-recommended +- Security category = error in `.editorconfig` -Start here. These warnings are trivial to fix mechanically and reduce noise for the real work: +Fix all warnings before merging. -| Warning ID | Description | Typical fix | -|-----------|-------------|-------------| -| CS8019 | Unnecessary using directive | Remove the unused using | -| CS0219 | Variable assigned but never used | Remove the variable | -| CS0168 | Variable declared but never used | Remove the variable | -| CS1591 | Missing XML comment for public type/member | Add doc comment or disable for internal code | -| CS0612 | Use of obsolete member (no message) | Replace with non-obsolete API | -| CS0618 | Use of obsolete member (with message) | Follow the migration guidance | +### Legacy Projects — Gradual Promotion -Promote these first: +Blanket `TreatWarningsAsErrors` on a legacy codebase produces hundreds/thousands of errors. An agent cannot fix them all at once — context floods, fix quality drops. Promote in batches. -```xml - - CS8019;CS0219;CS0168 - -``` - -Fix all occurrences, then move to Phase 2. +#### Phase 1: Trivial Hygiene (start here) -#### Phase 2: Code Quality (medium effort, high value) +Mechanical fixes, lowest effort: +- CS8019 — unnecessary using directive (remove it) +- CS0219 — variable assigned but never used (remove it) +- CS0168 — variable declared but never used (remove it) +- CS1591 — missing XML comment for public member (add comment or disable for internal code) +- CS0612 — obsolete member used, no message (replace with non-obsolete API) +- CS0618 — obsolete member used, with message (follow migration guidance) -| Warning ID | Description | Category | -|-----------|-------------|----------| -| CA2000 | Dispose objects before losing scope | Reliability | -| CA1062 | Validate arguments of public methods | Design | -| CA1822 | Mark members as static | Performance | -| CA1860 | Avoid using Enumerable.Any() for length check | Performance | -| CA1861 | Avoid constant arrays as arguments | Performance | -| CA2007 | Consider calling ConfigureAwait | Reliability | -| CS8600–CS8610 | Nullable reference type warnings | Nullability | +Add to `WarningsAsErrors`: `CS8019;CS0219;CS0168`. Fix all, then Phase 2. -**Ask the user**: "Which of these categories do you want to promote next? Nullability? Performance? Reliability?" +#### Phase 2: Code Quality (ask user which categories) -Add the selected IDs to `WarningsAsErrors` and fix them before adding more. +- CA2000 — dispose objects before losing scope (Reliability) +- CA1062 — validate public method arguments (Design) +- CA1822 — mark members as static (Performance) +- CA1860 — avoid Enumerable.Any() for length check (Performance) +- CA1861 — avoid constant arrays as arguments (Performance) +- CA2007 — consider calling ConfigureAwait (Reliability) +- CS8600–CS8610 — nullable reference type warnings (Nullability) -#### Phase 3: Security (high priority, always promote) +Ask: "Which categories next — Nullability, Performance, or Reliability?" Add selected IDs to `WarningsAsErrors`, fix, repeat. -| Warning ID | Description | -|-----------|-------------| -| CA3001 | Review code for SQL injection | -| CA3002 | Review code for XSS | -| CA3003 | Review code for file path injection | -| CA3075 | Insecure DTD processing | -| CA5350 | Do not use weak cryptographic algorithms | -| CA5351 | Do not use broken cryptographic algorithms | -| CA5394 | Do not use insecure randomness | - -These should be promoted to error early regardless of project maturity. Set in `.editorconfig`: +#### Phase 3: Security (always promote early) +Set in `.editorconfig` regardless of project maturity: ```editorconfig [*.cs] dotnet_analyzer_diagnostic.category-Security.severity = error ``` -#### Phase 4: Full Coverage +Covers CA3001 (SQL injection), CA3002 (XSS), CA3003 (path injection), CA3075 (insecure DTD), CA5350/CA5351 (weak crypto), CA5394 (insecure randomness). -Once all targeted batches pass cleanly, transition from selective `WarningsAsErrors` to global `TreatWarningsAsErrors`: +#### Phase 4: Full Coverage +Once all batches pass, transition to: ```xml - - true - - CA1707 - +true +CA1707 ``` -### Interaction Protocol - -When applying warning promotion to a legacy codebase: +### Interaction Protocol (legacy codebases) -1. **Run `dotnet build` and count warnings** by ID and category. -2. **Report the summary to the user**: "Found 47 CS8019, 23 CA1822, 12 CA2000, 8 CS8600 warnings." -3. **Ask the user which batch to tackle**: "I recommend starting with CS8019 (unused usings) and CS0219 (unused variables) — these are mechanical fixes. Want me to proceed?" -4. **Fix the selected batch** and verify the build passes. -5. **Add those IDs to `WarningsAsErrors`** so they stay enforced going forward. -6. **Report back** and ask about the next batch. +1. Run `dotnet build`, count warnings by ID. +2. Report summary: "Found 47 CS8019, 23 CA1822, 12 CA2000, 8 CS8600." +3. Ask which batch to tackle. Recommend starting with Phase 1. +4. Fix selected batch, verify build. +5. Add those IDs to `WarningsAsErrors`. +6. Report back, ask about next batch. Never skip the ask step. The user decides the pace. ## Bootstrap When Missing -If first-party .NET code analysis is requested but not configured yet: - 1. Detect current state: - `dotnet --info` - `rg -n "EnableNETAnalyzers|AnalysisLevel|AnalysisMode|TreatWarningsAsErrors|WarningsAsErrors" -g '*.csproj' -g 'Directory.Build.*' .` - - `dotnet build SOLUTION_OR_PROJECT 2>&1` — count current warnings by ID -2. Treat SDK analyzers as built-in functionality, not as a separate third-party install path. -3. Classify the project: new (few or zero warnings) vs. legacy (many warnings). -4. Enable the needed properties in the solution's MSBuild config, typically in `Directory.Build.props` or the target project file: - - `EnableNETAnalyzers` - - `AnalysisLevel` - - `AnalysisMode` when needed -5. **Apply the appropriate warning promotion strategy** based on project maturity: - - New project: apply strict policy immediately. - - Legacy project: start with Phase 1 and ask the user before each batch. -6. Keep rule-level severity in the repo-root `.editorconfig`. -7. Run `dotnet build SOLUTION_OR_PROJECT` and return `status: configured` or `status: improved`. -8. If the repo intentionally defers analyzer policy to another documented build layer, return `status: not_applicable`. + - `dotnet build SOLUTION_OR_PROJECT 2>&1` — count warnings by ID +2. Classify: new (few/zero warnings) vs legacy (many warnings). +3. Enable `EnableNETAnalyzers`, `AnalysisLevel`, `AnalysisMode` in MSBuild config. +4. Apply promotion strategy matching project maturity. +5. Per-rule severity in repo-root `.editorconfig`. +6. Run `dotnet build`, return `status: configured` or `status: improved`. +7. If repo defers analyzer policy to another build layer, return `status: not_applicable`. ## Deliver -- first-party analyzer policy that is explicit and reviewable +- explicit, reviewable first-party analyzer policy - build-time analyzer execution for CI -- warning promotion roadmap that matches the project's maturity +- warning promotion plan matching project maturity ## Validate -- analyzer behavior is driven by repo config, not IDE defaults -- CI can reproduce the same warnings and errors locally -- no `TreatWarningsAsErrors`, `WarningsAsErrors`, or severity settings were removed or weakened by the agent without user approval +- analyzer behavior driven by repo config, not IDE defaults +- CI reproduces same warnings/errors locally +- no `TreatWarningsAsErrors`, `WarningsAsErrors`, or severity settings removed/weakened without user approval - promoted warnings produce build errors, not just IDE hints ## Ralph Loop -Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work. - -1. Plan first (mandatory): - - analyze current state - - define target outcome, constraints, and risks - - write a detailed execution plan - - list final validation skills to run at the end, with order and reason -2. Execute one planned step and produce a concrete delta. -3. Review the result and capture findings with actionable next fixes. -4. Apply fixes in small batches and rerun the relevant checks or review steps. -5. Update the plan after each iteration. -6. Repeat until outcomes are acceptable or only explicit exceptions remain. -7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path. +1. Plan: analyze state, define target, constraints, risks, execution plan, validation steps. +2. Execute one step, produce concrete delta. +3. Review result, capture findings. +4. Apply fixes in small batches, rerun checks. +5. Update plan after each iteration. +6. Repeat until acceptable or only explicit exceptions remain. +7. Missing dependency: bootstrap or return `status: not_applicable`. ### Required Result Format - `status`: `complete` | `clean` | `improved` | `configured` | `not_applicable` | `blocked` -- `plan`: concise plan and current iteration step -- `actions_taken`: concrete changes made -- `validation_skills`: final skills run, or skipped with reasons -- `verification`: commands, checks, or review evidence summary -- `remaining`: top unresolved items or `none` - -For setup-only requests with no execution, return `status: configured` and exact next commands. +- `plan`: concise plan and current step +- `actions_taken`: concrete changes +- `validation_skills`: final skills run or skipped with reasons +- `verification`: commands, checks, or review evidence +- `remaining`: unresolved items or `none` ## Load References -- read `references/rules.md` for SDK analyzer rule categories and severity guidance -- read `references/config.md` for AnalysisLevel, AnalysisMode, and .editorconfig settings +- `references/rules.md` — rule categories and severity guidance +- `references/config.md` — MSBuild properties and .editorconfig settings ## Example Requests - "Turn on built-in .NET analyzers." - "Make analyzer warnings fail the build." -- "Set the right `AnalysisLevel` for this repo." +- "Set the right AnalysisLevel for this repo." - "Start treating unused usings and unused variables as errors." - "Help me gradually promote Roslyn warnings in my legacy project." - "Which warnings should I promote to errors next?" diff --git a/skills/dotnet-code-analysis/references/config.md b/skills/dotnet-code-analysis/references/config.md index 2598893..93e42ad 100644 --- a/skills/dotnet-code-analysis/references/config.md +++ b/skills/dotnet-code-analysis/references/config.md @@ -1,327 +1,112 @@ -# AnalysisLevel and .editorconfig Configuration - -This reference covers MSBuild properties for SDK analyzers and .editorconfig settings for rule configuration. +# MSBuild Properties and .editorconfig for Code Analysis ## MSBuild Properties -Configure these in `Directory.Build.props` or individual project files. +Set in `Directory.Build.props` or project files. ### EnableNETAnalyzers ```xml - - true - +true ``` - -- Enabled by default in .NET 5+. -- Set explicitly for clarity and to prevent accidental disabling. +Default true in .NET 5+. Set explicitly to prevent accidental disabling. ### AnalysisLevel -Controls which rules are enabled based on .NET version and analysis mode. - -```xml - - latest - -``` +Values: `5.0`–`10.0` (specific SDK), `latest`, `latest-recommended`, `latest-minimum`, `latest-all`, `preview`. -| Value | Meaning | -|-------|---------| -| `5.0`, `6.0`, `7.0`, `8.0`, `9.0`, `10.0` | Rules available in that SDK version | -| `latest` | Rules from the installed SDK version | -| `latest-recommended` | Latest SDK with Recommended mode | -| `latest-minimum` | Latest SDK with Minimum mode | -| `latest-all` | Latest SDK with All mode | -| `preview` | Experimental rules from preview SDK | +Combined syntax includes mode: `latest-recommended` equals `latest` + `Recommended` mode. ### AnalysisMode -Controls which subset of rules are enabled. - -```xml - - Recommended - -``` - -| Mode | Description | -|------|-------------| -| `None` | All rules disabled except explicitly enabled | -| `Default` | Default severity for all rules (same as not setting) | -| `Minimum` | Small set of critical rules | -| `Recommended` | Common high-value rules (start here) | -| `All` | Every available rule | - -### Combined Syntax - -AnalysisLevel can include the mode: - -```xml - - latest-recommended - -``` - -This is equivalent to: - -```xml - - latest - Recommended - -``` +Values: `None` (all off), `Default`, `Minimum` (critical only), `Recommended` (start here), `All`. ### Category-Specific AnalysisMode -Override mode for specific categories: - ```xml - - latest-recommended - All - All - +latest-recommended +All +All ``` - -Available categories: `Design`, `Documentation`, `Globalization`, `Interoperability`, `Maintainability`, `Naming`, `Performance`, `Reliability`, `Security`, `Usage`. +Categories: Design, Documentation, Globalization, Interoperability, Maintainability, Naming, Performance, Reliability, Security, Usage. ### TreatWarningsAsErrors ```xml - - true - +true ``` +All warnings fail the build. Use for new projects or clean codebases. Agent rule: never disable to make a build pass. -Makes all warnings fail the build. Best for new projects or mature codebases that have already cleared their warning backlog. Combine with `WarningsNotAsErrors` for explicit exceptions. - -**Agent rule**: never disable, remove, or comment out this property to make a build pass. Fix the code instead or ask the user. - -### WarningsAsErrors (Selective — Preferred for Legacy Codebases) +### WarningsAsErrors (selective — preferred for legacy) ```xml - - CS8019;CS0219;CS0168;CA2000;CA3001 - +CS8019;CS0219;CS0168;CA2000;CA3001 ``` - -Promote specific warnings to errors without affecting others. This is the recommended approach for gradual adoption in legacy projects: - -1. Start with trivial hygiene warnings (CS8019 unused usings, CS0219/CS0168 unused variables). -2. Fix all occurrences in the codebase. -3. Add the IDs to `WarningsAsErrors` so they stay enforced. -4. Ask the user which category to promote next. -5. Repeat until the codebase is clean enough to switch to `TreatWarningsAsErrors`. - -**Agent rule**: never remove IDs from this list to make a build pass. The user chose these IDs deliberately. +Promote specific IDs to errors. Preferred for gradual adoption: add IDs as you fix each batch. Agent rule: never remove IDs from this list to make a build pass. ### WarningsNotAsErrors ```xml - - true - CA1707 - +true +CA1707 ``` - -Keep specific warnings as warnings when using `TreatWarningsAsErrors`. Use this for rules the team has explicitly decided to defer. +Explicit exceptions when using TreatWarningsAsErrors. ### NoWarn ```xml - - $(NoWarn);CA1062 - +$(NoWarn);CA1062 ``` - -Disable specific warnings entirely. Use sparingly; prefer .editorconfig for visibility. +Disables warnings entirely. Use sparingly; prefer .editorconfig for visibility. ### EnforceCodeStyleInBuild ```xml - - true - +true ``` +Enables IDE code style rules during build (off by default for performance). -Enable IDE code style rules during build (disabled by default for performance). - -## .editorconfig Configuration - -Place at repository root. Rules cascade to subdirectories. - -### Basic Structure - -```editorconfig -# Top-level settings -root = true - -[*.cs] -# All C# files +## .editorconfig -[*.{cs,vb}] -# All .NET code files - -[**/Tests/**/*.cs] -# Test files only -``` +Place at repo root. Rules cascade to subdirectories. -### Analyzer Severity Configuration +### Severity per rule ```editorconfig [*.cs] -# Set specific rule severity -dotnet_diagnostic.CA1000.severity = warning dotnet_diagnostic.CA2000.severity = error dotnet_diagnostic.CA1707.severity = none - -# Bulk category severity (requires .NET 6+) -dotnet_analyzer_diagnostic.category-Security.severity = error -dotnet_analyzer_diagnostic.category-Performance.severity = warning ``` -### Common Patterns - -#### Production Code Hardened +### Severity per category (.NET 6+) ```editorconfig [*.cs] -# Security rules as errors dotnet_analyzer_diagnostic.category-Security.severity = error - -# Reliability rules as warnings -dotnet_analyzer_diagnostic.category-Reliability.severity = warning - -# Performance rules as warnings dotnet_analyzer_diagnostic.category-Performance.severity = warning ``` -#### Test Code Relaxed +### Scope patterns ```editorconfig [**/Tests/**/*.cs] -[**/Test/**/*.cs] -[**/*.Tests/**/*.cs] -# Relax naming rules for test methods dotnet_diagnostic.CA1707.severity = none - -# Relax null checks for test assertions dotnet_diagnostic.CA1062.severity = none -# Allow test-specific patterns -dotnet_diagnostic.CA2007.severity = none -``` - -#### Generated Code Excluded - -```editorconfig [*.generated.cs] -[*.designer.cs] generated_code = true ``` -### Code Style Settings - -```editorconfig -[*.cs] -# Namespace preferences -csharp_style_namespace_declarations = file_scoped:suggestion - -# Expression-bodied members -csharp_style_expression_bodied_methods = when_on_single_line:suggestion -csharp_style_expression_bodied_properties = true:suggestion - -# Pattern matching -csharp_style_pattern_matching_over_as_with_null_check = true:warning -csharp_style_pattern_matching_over_is_with_cast_check = true:warning - -# Null checking -csharp_style_prefer_null_check_over_type_check = true:suggestion - -# var preferences -csharp_style_var_for_built_in_types = true:suggestion -csharp_style_var_when_type_is_apparent = true:suggestion -csharp_style_var_elsewhere = true:suggestion -``` - -### Formatting Settings - -```editorconfig -[*.cs] -# Indentation -indent_style = space -indent_size = 4 -tab_width = 4 - -# New lines -csharp_new_line_before_open_brace = all -csharp_new_line_before_else = true -csharp_new_line_before_catch = true -csharp_new_line_before_finally = true -``` - -## Recommended Starting Configuration - -### Directory.Build.props - -```xml - - - true - latest-recommended - true - - - - true - - -``` - -### .editorconfig (Root) - -```editorconfig -root = true - -[*] -indent_style = space -indent_size = 4 -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -[*.cs] -# Security rules as errors -dotnet_analyzer_diagnostic.category-Security.severity = error - -# Reliability rules as warnings, promote over time -dotnet_analyzer_diagnostic.category-Reliability.severity = warning - -# Relax test files -[**/Tests/**/*.cs] -dotnet_diagnostic.CA1707.severity = none -dotnet_diagnostic.CA1062.severity = none -``` - -## Verification Commands +## Verification ```bash -# Build with analyzer output dotnet build - -# Build with detailed analyzer timing dotnet build /p:ReportAnalyzer=true - -# Check effective analyzer configuration -dotnet build /v:d | grep -i "analyzer" ``` ## References -- [AnalysisLevel documentation](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#analysislevel) -- [Code analysis configuration](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-options) -- [EditorConfig settings](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-files) +- [AnalysisLevel](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#analysislevel) +- [Configuration options](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-options) +- [EditorConfig](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-files) - [Suppress warnings](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/suppress-warnings) From 831cd1f1c2b71f18d7e49328168e58d10dd58547 Mon Sep 17 00:00:00 2001 From: Serhiiiiko <2021elit0049@ms.sumdu.edu.ua> Date: Mon, 16 Mar 2026 12:38:36 +0200 Subject: [PATCH 3/4] return styling --- .../dotnet-code-analysis/references/config.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/skills/dotnet-code-analysis/references/config.md b/skills/dotnet-code-analysis/references/config.md index 93e42ad..8b952a7 100644 --- a/skills/dotnet-code-analysis/references/config.md +++ b/skills/dotnet-code-analysis/references/config.md @@ -97,6 +97,74 @@ dotnet_diagnostic.CA1062.severity = none generated_code = true ``` +### Code Style Settings + +```editorconfig +[*.cs] +csharp_style_namespace_declarations = file_scoped:suggestion +csharp_style_expression_bodied_methods = when_on_single_line:suggestion +csharp_style_expression_bodied_properties = true:suggestion +csharp_style_pattern_matching_over_as_with_null_check = true:warning +csharp_style_pattern_matching_over_is_with_cast_check = true:warning +csharp_style_prefer_null_check_over_type_check = true:suggestion +csharp_style_var_for_built_in_types = true:suggestion +csharp_style_var_when_type_is_apparent = true:suggestion +csharp_style_var_elsewhere = true:suggestion +``` + +### Formatting Settings + +```editorconfig +[*.cs] +indent_style = space +indent_size = 4 +tab_width = 4 +csharp_new_line_before_open_brace = all +csharp_new_line_before_else = true +csharp_new_line_before_catch = true +csharp_new_line_before_finally = true +``` + +## Recommended Starting Configuration + +### Directory.Build.props + +```xml + + + true + latest-recommended + true + + + + true + + +``` + +### .editorconfig (root) + +```editorconfig +root = true + +[*] +indent_style = space +indent_size = 4 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.cs] +dotnet_analyzer_diagnostic.category-Security.severity = error +dotnet_analyzer_diagnostic.category-Reliability.severity = warning + +[**/Tests/**/*.cs] +dotnet_diagnostic.CA1707.severity = none +dotnet_diagnostic.CA1062.severity = none +``` + ## Verification ```bash From 3bf62278120f62473c52ead1b235c21c8fd119aa Mon Sep 17 00:00:00 2001 From: Serhii <130470742+Serhiiiiko@users.noreply.github.com> Date: Mon, 16 Mar 2026 12:47:09 +0200 Subject: [PATCH 4/4] Update version from 2.0.0 to 1.0.1 --- skills/dotnet-code-analysis/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/dotnet-code-analysis/SKILL.md b/skills/dotnet-code-analysis/SKILL.md index 5e5238d..86794f1 100644 --- a/skills/dotnet-code-analysis/SKILL.md +++ b/skills/dotnet-code-analysis/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-code-analysis -version: "2.0.0" +version: "1.0.1" category: "Code Quality" description: "Use the free built-in .NET SDK analyzers and analysis levels with gradual Roslyn warning promotion. Use when a .NET repo needs first-party code analysis, `EnableNETAnalyzers`, `AnalysisLevel`, or warning-as-error policy wired into build and CI." compatibility: "Requires a .NET SDK-based repository; respects the repo's `AGENTS.md` commands first."