SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdotnet-health-audit

dotnet-health-audit

Coding & development

View repository

Updated 10-16 06:16

About this skill

.NET Project Health Audit - Modular Execution Plan

This plan executes the .NET Project Health Audit through sequential, modular rules. Each step uses a specific rule that can be executed independently and produces output that feeds into the final report.

Three-Tier Subagent Architecture

When running in-session (Claude Code, Cursor, or any agent that supports the Agent tool), this skill operates through a tiered multi-subagent topology coordinated by agents/orchestrator.md. The somnio run CLI path uses the Rule Execution Order below (sequential, single model per run).

Entry point (in-session): agents/orchestrator.md (model: mid)

Tier assignments:

Tier Role Agents
cheap Mechanical scanners — filesystem scans, key extraction, presence checklists env-setup-agent, repo-analyzer, config-analyzer, support-lifecycle-analyzer, docs-analyzer
mid Reasoning analyzers — CI gate compliance, test quality judgment, code quality depth, API convention compliance, N+1 detection, dependency risk prioritization, SOLID/complexity assessment, AI harness quality judgment; also the orchestrator orchestrator, cicd-analyzer, testing-analyzer, code-quality-analyzer, api-design-analyzer, data-layer-analyzer, dependency-security-analyzer, solid-compliance-analyzer, harness-analyzer
frontier Report synthesis — cross-section score reconciliation, weighted overall score, narrative coherence, mandatory 15-section structure report-writer-agent

Agent Role & Context

Role: .NET Project Health Auditor

Your Core Expertise

You are a master at:

  • Comprehensive Project Auditing: Evaluating all aspects of .NET project health (tech stack, support lifecycle, dependency security, architecture, SOLID design, API design, data layer, testing, CI/CD, documentation, AI harness)
  • Evidence-Based Analysis: Analyzing repository evidence objectively without inventing data or making assumptions
  • Modular Rule Execution: Coordinating sequential execution of 17 specialized analysis rules
  • Score Calculation: Calculating section scores (0-100) and weighted overall scores accurately
  • Technical Risk Assessment: Identifying technical risks, technical debt, and project maturity indicators
  • Report Integration: Synthesizing findings from multiple analysis rules into unified Markdown reports
  • .NET / ASP.NET Core Best Practices: Deep knowledge of Controllers vs Minimal APIs, dependency injection, EF Core, async/await, nullable reference types, SOLID principles, and cyclomatic complexity
  • Backend Architecture: Understanding of Vertical Slice, Onion, Clean Architecture, and N-Layer patterns applied to .NET solutions
  • .NET Support Lifecycle: Computing whether a TargetFramework is within Microsoft's official support policy from release-cadence rules, not a hardcoded date table

Responsibilities:

  • Execute technical audits following the plan steps sequentially
  • Report findings objectively based on evidence found in the repository
  • Stop execution immediately if MANDATORY steps fail
  • Never invent or assume information - report "Unknown" if evidence is missing
  • Focus exclusively on technical aspects, exclude operational/governance recommendations

Expected Behavior:

  • Professional and Evidence-Based: All findings must be supported by actual repository evidence
  • Objective Reporting: Distinguish clearly between critical issues, recommendations, and neutral items
  • Explicit Documentation: Document what was checked, what was found, and what is missing
  • Error Handling: Stop execution on MANDATORY step failures; continue with warnings for non-critical issues
  • No Assumptions: If something cannot be proven by repository evidence, write "Unknown" and specify what would prove it

Critical Rules:

  • NEVER recommend CODEOWNERS or SECURITY.md files - these are governance decisions, not technical requirements
  • NEVER recommend operational documentation (runbooks, deployment procedures, monitoring) - focus on technical setup only
  • ALWAYS verify the .NET SDK against global.json - see the SDK Alignment requirement below (graceful, not a hard nvm-style gate)
  • ALWAYS execute comprehensive restore/build/test across the full solution before analysis
  • NEVER hardcode .NET end-of-support dates from memory - compute support status from the release-cadence rule in references/support-lifecycle-analysis.md, which stays correct without maintenance

Execution Discipline (NON-NEGOTIABLE):

  • NEVER skip, combine, or abbreviate any step — each step in this plan MUST be executed individually and completely
  • NEVER summarize a reference file instead of executing it — you MUST read each reference file AND follow its instructions fully
  • NEVER take shortcuts — even if you believe you already know the answer, you MUST execute the analysis commands and collect real evidence
  • ALWAYS read the reference file first — before executing any step, read the referenced .md file completely, then follow its instructions
  • ALWAYS log step completion — after completing each step, output: "STEP N COMPLETED: [brief result summary]" before proceeding to the next
  • NEVER proceed to the next step without completing the current one — partial execution of a step is not acceptable
  • If a step fails: document the failure, attempt recovery, and only skip if recovery is impossible (with explicit documentation of what was skipped and why)

REQUIREMENT - .NET SDK ALIGNMENT

MANDATORY STEP 0: Before executing any .NET project analysis, ALWAYS verify the installed .NET SDK against the project's global.json pin (if present) and confirm the solution restores and builds cleanly.

Rule to Execute: Read and follow the instructions in references/version-alignment.md

IMPORTANT DIFFERENCE FROM NODE.JS-BASED SKILLS: Unlike the React/NestJS audits (which MUST hard-stop on any nvm/Node.js version mismatch), .NET SDKs are backward compatible with older TargetFramework values. SDK alignment is therefore a strong recommendation with graceful degradation, not a hard blocking gate — only a genuinely broken dotnet restore/dotnet build stops execution.

Step 0. .NET Environment Setup and Test Coverage Verification

Goal: Verify the .NET SDK, align it with global.json when present, restore/build the full solution, and generate code coverage.

Rules to Execute:

  1. Read and follow the instructions in references/tool-installer.md (installs/verifies the .NET SDK and companion CLI tools)
  2. Read and follow the instructions in references/version-alignment.md (SDK alignment; stops only on restore/build failure)
  3. Read and follow the instructions in references/version-validator.md (build sanity check, Central Package Management validation)
  4. Read and follow the instructions in references/test-coverage.md (coverage generation via Coverlet)

Execution Order:

  1. Execute references/tool-installer.md rule first
  2. Execute references/version-alignment.md rule (stops only if dotnet restore fails)
  3. Execute references/version-validator.md rule to verify the build
  4. Execute references/test-coverage.md rule to generate coverage

Integration: Save all outputs from these rules for integration into the final audit report.

Failure Handling: If dotnet restore/dotnet build fails for the solution, STOP execution and provide resolution steps.

Parallel Execution Strategy

Steps 1-12 can be partially parallelized using the Agent tool to launch multiple analysis agents simultaneously. Use the following wave structure:

Wave 0 (Sequential - MANDATORY): Step 0 — Environment Setup Must complete fully before any analysis begins.

Wave 1 (Parallel): Steps 1 + 2 + 3 — Repository Inventory + Configuration Analysis + Support Lifecycle Analysis Launch all three as parallel agents. All read from the filesystem/already-collected TFM data independently.

Wave 2 (Parallel): Steps 4 + 5 + 6 + 7 + 12 — CI/CD + Testing + Code Quality + Dependency Security + AI Harness & Adoption Launch all five as parallel agents. Independent read-only analyses; the harness analysis depends on no prior artifact, so it joins this wave.

Wave 3 (Parallel): Steps 8 + 9 + 10 — API Design + Data Layer + SOLID Compliance Launch all three as parallel agents. Independent framework-specific analyses.

Wave 4 (Sequential): Step 11 — Documentation Analysis Can run after all analysis waves complete.

Wave 5 (Sequential): Steps 13 + 14 — Report Generation + Export Must run last — requires ALL previous results.

Agent Launch Pattern: For each parallel wave, use the Agent tool to spawn one agent per step. Each agent MUST:

  1. Read the referenced .md file completely
  2. Execute ALL instructions in that file
  3. Return the complete analysis results
  4. Never abbreviate or summarize — return full evidence

Example for Wave 1:

  • Agent 1: "Read references/repository-inventory.md and execute ALL instructions. Return complete findings."
  • Agent 2: "Read references/config-analysis.md and execute ALL instructions. Return complete findings."
  • Agent 3: "Read references/support-lifecycle-analysis.md and execute ALL instructions. Return complete findings."

Step 1. Repository Inventory

Goal: Detect solution/project structure, project types (Web API, Blazor, Worker Service, class library), architecture pattern (Vertical Slice, Onion, Clean Architecture, N-Layer, or Flat), and naming conventions.

Rule to Execute: Read and follow the instructions in references/repository-inventory.md

Integration: Save repository structure findings for Architecture and Tech Stack sections.

Step 2. Core Configuration Files

Goal: Read and analyze appsettings hierarchy, Directory.Build.props, Central Package Management, nullable reference types, and secrets handling.

Rule to Execute: Read and follow the instructions in references/config-analysis.md

Integration: Save configuration findings for Tech Stack and Code Quality sections.

Step 3. Support Lifecycle Analysis

Goal: Determine whether every detected TargetFramework is within Microsoft's official .NET support policy (computed from release-cadence rules, not a hardcoded date table), and identify the current recommended LTS upgrade target.

Rule to Execute: Read and follow the instructions in references/support-lifecycle-analysis.md

Integration: Save support-status findings into the Tech Stack section (this step does NOT add a new report section).

Step 4. CI/CD Workflows Analysis

Goal: Read all CI/CD pipeline definitions (GitHub Actions, Azure Pipelines, GitLab CI) and Docker setup for the .NET build.

Rule to Execute: Read and follow the instructions in references/cicd-analysis.md

Integration: Save CI/CD findings for CI/CD section scoring.

Step 5. Testing Infrastructure

Goal: Find and classify all test projects, identify the test framework, mocking/assertion libraries, and test types (unit vs integration).

Rule to Execute: Read and follow the instructions in references/testing-analysis.md

Integration: Save testing findings for Testing section, integrate with coverage results from Step 0.

Step 6. Code Quality and Analyzers

Goal: Analyze Roslyn analyzer configuration, TreatWarningsAsErrors, .editorconfig severity rules, nullable compliance, and sync-over-async anti-patterns.

Rule to Execute: Read and follow the instructions in references/code-quality.md

Integration: Save code quality findings for Code Quality section scoring. Cyclomatic complexity itself is measured by Step 10 (SOLID Compliance Analysis) — this step cross-references those numbers rather than re-measuring them.

Step 7. Dependency Security Analysis

Goal: Identify vulnerable NuGet packages (direct and transitive) and outdated dependencies via dotnet list package --vulnerable/--outdated, beyond whatever surfaces incidentally in restore output.

Rule to Execute: Read and follow the instructions in references/dependency-security-analysis.md

Integration: Save dependency findings into the Tech Stack section (this step does NOT add a new report section). For a deeper security review, recommend the standalone Security Audit (/somnio:security-audit).

Step 8. API Design Analysis

Goal: Analyze Controllers/Minimal API design, DTOs, validation patterns, OpenAPI/Swagger documentation, and API versioning.

Rule to Execute: Read and follow the instructions in references/api-design-analysis.md

Integration: Save API design findings for API Design section scoring.

Step 9. Data Layer Analysis

Goal: Analyze EF Core (or Dapper) integration, repository patterns, migrations, and query patterns.

Rule to Execute: Read and follow the instructions in references/data-layer-analysis.md

Integration: Save data layer findings for Data Layer section scoring.

Step 10. SOLID Compliance and Cyclomatic Complexity Analysis

Goal: Assess adherence to SRP/OCP/LSP/ISP/DIP within whichever architecture pattern Step 1 identified, and measure real cyclomatic complexity by forcing Roslyn analyzers on for this audit run via MSBuild command-line properties (no files in the target repo are modified).

Rule to Execute: Read and follow the instructions in references/solid-compliance-analysis.md

Integration: Save SOLID/complexity findings into the Architecture section (this step does NOT add a new report section).

Step 11. Documentation and Operations

Goal: Review technical documentation, XML doc comments, Swagger UI reachability, and environment setup.

Rule to Execute: Read and follow the instructions in references/documentation-analysis.md

Integration: Save documentation findings for Documentation & Operations section scoring.

Step 12. AI Harness & Adoption Analysis

Goal: Score the project's AI harness — CLAUDE.md, .claude/rules/, settings.json permissions and hooks, .claude/agents/, commands/skills, and the pre-push git hook — on the 10-dimension, 100-point rubric, judging quality, not just presence.

Rule to Execute: Read and follow the instructions in references/harness-analysis.md

Integration: Save the AI Harness & Adoption findings, score, and prioritised action list for the "AI Harness & Adoption" report section.

Step 13. Generate Final Report

Goal: Generate the final .NET Project Health Audit report by integrating all analysis results.

Rule to Execute: Read and follow the instructions in references/report-generator.md

Integration: This rule integrates all previous analysis results and generates the final report.

The format rules in references/report-format-enforcer.md apply to this step: the report writer reads them alongside the generator, and the somnio run runner applies the enforcer automatically right after the generator, so it is not a separately numbered rule.

Report Sections (9 scored dimensions / 15 numbered sections — Steps 3, 7, and 10 deepen existing sections, they do not add new ones):

  • Executive Summary with overall score
  • At-a-Glance Scorecard with all 9 section scores, plus the > Test Coverage: line, the scoring legend, and the Overall Score interpretation sentence
  • All 9 detailed sections (Tech Stack — including support lifecycle and dependency security; Architecture — including SOLID compliance and real cyclomatic complexity; API Design; Data Layer; Testing; Code Quality; Documentation & Operations; CI/CD; AI Harness & Adoption) — Testing carries the canonical Code Coverage / Coverage Breakdown fields
  • Additional Metrics (no coverage percentages — those live only in the scorecard line and the Testing section)
  • Risks & Opportunities (5-8 bullets)
  • Recommendations (6-10 prioritized actions)
  • Appendix: Evidence Index
  • Appendix: Scoring Methodology (unnumbered; the only place weights appear)

Step 14. Export Final Report

Goal: Save the final shareable Markdown report to the reports directory.

Action: Create the reports directory if it doesn't exist and save the final .NET Project Health Audit report to: ./reports/<YYYY-MM-DD>-<project>-dotnet-health-audit.md

Format: Markdown-formatted report (use proper Markdown syntax, use # headings, bold markers, and backtick code references).

Command:

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-dotnet-health-audit.md

Note: For security analysis, run the standalone Security Audit (/somnio:security-audit).

Execution Summary

Total Rules: 17 rules

Rule Execution Order:

  1. references/tool-installer.md {model: cheap}
  2. references/version-alignment.md (SDK alignment; stops only if restore fails) {model: cheap}
  3. references/version-validator.md (build sanity check) {model: cheap}
  4. references/test-coverage.md (coverage generation) {model: cheap}
  5. references/repository-inventory.md {model: cheap}
  6. references/config-analysis.md {model: cheap}
  7. references/support-lifecycle-analysis.md {model: cheap}
  8. references/cicd-analysis.md {model: mid}
  9. references/testing-analysis.md {model: mid}
  10. references/code-quality.md {model: mid}
  11. references/dependency-security-analysis.md {model: mid}
  12. references/api-design-analysis.md {model: mid}
  13. references/data-layer-analysis.md {model: mid}
  14. references/solid-compliance-analysis.md {model: mid}
  15. references/documentation-analysis.md {model: cheap}
  16. references/harness-analysis.md {model: mid}
  17. references/report-generator.md {model: frontier}

Wave-Based Parallel Execution:

  • Wave 0 (Sequential): Step 0 — Environment Setup (rules 1-4)
  • Wave 1 (Parallel): Steps 1 + 2 + 3 — Repository Inventory + Configuration + Support Lifecycle (rules 5-7)
  • Wave 2 (Parallel): Steps 4 + 5 + 6 + 7 + 12 — CI/CD + Testing + Code Quality + Dependency Security + AI Harness & Adoption (rules 8-11, 16)
  • Wave 3 (Parallel): Steps 8 + 9 + 10 — API Design + Data Layer + SOLID Compliance (rules 12-14)
  • Wave 4 (Sequential): Step 11 — Documentation (rule 15)
  • Wave 5 (Sequential): Steps 13 + 14 — Report Generation + Export (rule 17)

Benefits of Modular Approach:

  • Each rule can be executed independently
  • Outputs can be saved and reused
  • Easier debugging and maintenance
  • Wave-based parallelization accelerates analysis using the Agent tool
  • Clear separation of concerns
  • Strict no-shortcuts enforcement ensures complete, evidence-based analysis
  • Graceful SDK alignment handling avoids false-positive hard stops
  • Full solution restore/build/test verification before analysis
  • Support-lifecycle and dependency-security findings stay current without manual maintenance (rule-based computation, not hardcoded data)

Subagent Dispatch (in-session)

This section describes the in-session multi-agent path. The Rule Execution Order above remains the CLI (somnio run) path and is unchanged.

Entry point: agents/orchestrator.md (model: mid). The orchestrator dispatches all subagents via the Agent tool, validates artifacts between waves, and hands the artifact manifest to the report writer.

Wave plan:

Wave Mode Subagent(s) Tier Reference(s) covered Artifact(s) produced
0 Sequential (MANDATORY gate on restore/build failure only) env-setup-agent cheap tool-installer, version-alignment, version-validator, test-coverage step_00_env_setup.md, step_00_test_coverage.md
1 Parallel repo-analyzer, config-analyzer, support-lifecycle-analyzer cheap, cheap, cheap repository-inventory, config-analysis, support-lifecycle-analysis step_01_repository_inventory.md, step_02_config_analysis.md, step_03_support_lifecycle_analysis.md
2 Parallel cicd-analyzer, testing-analyzer, code-quality-analyzer, dependency-security-analyzer, harness-analyzer mid, mid, mid, mid, mid cicd-analysis, testing-analysis, code-quality, dependency-security-analysis, harness-analysis step_04_cicd_analysis.md, step_05_testing_analysis.md, step_06_code_quality.md, step_07_dependency_security_analysis.md, step_12_harness_analysis.md
3 Parallel api-design-analyzer, data-layer-analyzer, solid-compliance-analyzer mid, mid, mid api-design-analysis, data-layer-analysis, solid-compliance-analysis step_08_api_design_analysis.md, step_09_data_layer_analysis.md, step_10_solid_compliance_analysis.md
4 Sequential docs-analyzer cheap documentation-analysis step_11_documentation_analysis.md
5 Sequential report-writer-agent frontier report-generator, report-format-enforcer, assets/report-template.md reports/<YYYY-MM-DD>-<project>-dotnet-health-audit.md

Orchestrator behavior:

  • Wave 0 is the only hard-stop gate, and only on a genuine dotnet restore/dotnet build failure — SDK version mismatches alone do NOT stop execution (see the SDK Alignment note above).
  • For any non-mandatory artifact missing after a wave: retry the responsible agent once; if the artifact is still absent, log the skip and mark the section as Unavailable in the manifest.
  • The orchestrator NEVER reads source code or writes prose.

Report writer behavior:

  • Reads all fourteen artifacts produced by Waves 0–4.
  • Computes 9 weighted section scores and overall score per the weights defined in references/report-generator.md — that file is the single source of truth; do not restate the numbers here. Tech Stack blends in support-lifecycle and dependency-security findings; Architecture blends in SOLID/complexity findings — no extra sections, no extra weights.
  • Enforces the mandatory 15-section structure per references/report-format-enforcer.md.
  • Performs cross-section score reconciliation (e.g., low Testing score modulates Code Quality narrative).
  • Writes reports/<YYYY-MM-DD>-<project>-dotnet-health-audit.md and appends the metadata block.
  • NEVER re-reads raw source files.

Report File Name (MANDATORY)

The report file name is always:

<YYYY-MM-DD>-<project>-dotnet-health-audit.md
  • <YYYY-MM-DD> — the date of this run.
  • <project> — the git repository name slugified to kebab-case: lowercase, with spaces, _, . and / turned into -, every other character dropped, and repeated - collapsed. The name comes from the origin remote URL, so it is the same whatever the checkout directory, worktree or subdirectory is called; without a remote it is the main checkout's directory name, and outside a git repo the current directory name.
  • The trailing segment is this skill's name and never changes.

Derive it once, before writing anything:

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-dotnet-health-audit.md"

Everywhere this skill writes reports/<YYYY-MM-DD>-<project>-dotnet-health-audit.md, it means that resolved path.

When run through somnio run, the CLI computes the full report path and passes it in the prompt. Use the path it gives you verbatim — do not recompute it, or the runner will not find the report and the step will fail.

Report Metadata (MANDATORY)

Every generated report MUST include a metadata block at the very end. This is non-negotiable — never omit it.

Copy the Report Metadata table from the template as the last block of the report. Keep the Generated by row exactly as written in the template — never change, guess or omit the version. Fill the remaining rows as described.

Include this block at the very end of the report, as an unnumbered Markdown table (it follows the "Appendix: Scoring Methodology" block):

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | dotnet-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |