Add mcaf-dotnet-profiling skill

KSemenenko · KSemenenko · commit c5b52bfdab32 · 2026-03-08T14:45:33.000+01:00
diff --git a/README.md b/README.md
@@ -115,7 +115,7 @@ Platform-specific bundles can stay small and still be explicit.
 For example, a typical .NET repo baseline can install `mcaf-dotnet` as the entry skill, `mcaf-dotnet-features`, `mcaf-solution-governance`, `mcaf-testing`, exactly one of `mcaf-dotnet-xunit`, `mcaf-dotnet-tunit`, or `mcaf-dotnet-mstest`, plus `mcaf-dotnet-quality-ci`, `mcaf-dotnet-complexity`, `mcaf-solid-maintainability`, `mcaf-architecture-overview`, and `mcaf-ci-cd`.
 In that setup, `mcaf-dotnet` knows when to open the more specific .NET skills, the repo-root lowercase `.editorconfig` is the default source of truth for formatting and analyzer severity, and `AGENTS.md` records the exact `dotnet build`, `dotnet test`, `dotnet format`, `analyze`, and coverage commands. Nested `.editorconfig` files are allowed when they serve a clear subtree-specific purpose, such as stricter domain rules, generated-code handling, test-specific conventions, or legacy-code containment.
 For .NET code changes, the task is not done when tests are green if the repo also configured formatters, analyzers, coverage, architecture tests, or security gates. Agents should run the repo-defined post-change quality pass before completion.
-If the repo standardizes on concrete tools, install the matching tool skills as well. Typical open or free .NET additions include `mcaf-dotnet-format`, `mcaf-dotnet-code-analysis`, `mcaf-dotnet-analyzer-config`, `mcaf-dotnet-stylecop-analyzers`, `mcaf-dotnet-roslynator`, `mcaf-dotnet-meziantou-analyzer`, `mcaf-dotnet-cloc`, `mcaf-dotnet-coverlet`, `mcaf-dotnet-quickdup`, `mcaf-dotnet-reportgenerator`, `mcaf-dotnet-stryker`, `mcaf-dotnet-netarchtest`, `mcaf-dotnet-archunitnet`, `mcaf-dotnet-semgrep`, and `mcaf-dotnet-csharpier`. `mcaf-dotnet-codeql` stays available, but should be chosen only when its hosting and licensing model fits the repository.
+If the repo standardizes on concrete tools, install the matching tool skills as well. Typical open or free .NET additions include `mcaf-dotnet-format`, `mcaf-dotnet-code-analysis`, `mcaf-dotnet-analyzer-config`, `mcaf-dotnet-stylecop-analyzers`, `mcaf-dotnet-roslynator`, `mcaf-dotnet-meziantou-analyzer`, `mcaf-dotnet-cloc`, `mcaf-dotnet-coverlet`, `mcaf-dotnet-profiling`, `mcaf-dotnet-quickdup`, `mcaf-dotnet-reportgenerator`, `mcaf-dotnet-stryker`, `mcaf-dotnet-netarchtest`, `mcaf-dotnet-archunitnet`, `mcaf-dotnet-semgrep`, and `mcaf-dotnet-csharpier`. `mcaf-dotnet-codeql` stays available, but should be chosen only when its hosting and licensing model fits the repository.
 
 ### 2.5 Context Rules
 
diff --git a/TUTORIAL.md b/TUTORIAL.md
@@ -148,6 +148,7 @@ Add tool-specific .NET skills only when the repo standardizes on them:
 - `mcaf-dotnet-format`
 - `mcaf-dotnet-meziantou-analyzer`
 - `mcaf-dotnet-netarchtest`
+- `mcaf-dotnet-profiling`
 - `mcaf-dotnet-quickdup`
 - `mcaf-dotnet-reportgenerator`
 - `mcaf-dotnet-roslynator`
@@ -182,6 +183,7 @@ The website build generates this list from the actual folders under `skills/`.
 - `mcaf-dotnet-meziantou-analyzer` — [Folder](https://github.com/managedcode/MCAF/blob/main/skills/mcaf-dotnet-meziantou-analyzer), [Raw SKILL](https://raw.githubusercontent.com/managedcode/MCAF/main/skills/mcaf-dotnet-meziantou-analyzer/SKILL.md)
 - `mcaf-dotnet-mstest` — [Folder](https://github.com/managedcode/MCAF/blob/main/skills/mcaf-dotnet-mstest), [Raw SKILL](https://raw.githubusercontent.com/managedcode/MCAF/main/skills/mcaf-dotnet-mstest/SKILL.md)
 - `mcaf-dotnet-netarchtest` — [Folder](https://github.com/managedcode/MCAF/blob/main/skills/mcaf-dotnet-netarchtest), [Raw SKILL](https://raw.githubusercontent.com/managedcode/MCAF/main/skills/mcaf-dotnet-netarchtest/SKILL.md)
+- `mcaf-dotnet-profiling` — [Folder](https://github.com/managedcode/MCAF/blob/main/skills/mcaf-dotnet-profiling), [Raw SKILL](https://raw.githubusercontent.com/managedcode/MCAF/main/skills/mcaf-dotnet-profiling/SKILL.md)
 - `mcaf-dotnet-quality-ci` — [Folder](https://github.com/managedcode/MCAF/blob/main/skills/mcaf-dotnet-quality-ci), [Raw SKILL](https://raw.githubusercontent.com/managedcode/MCAF/main/skills/mcaf-dotnet-quality-ci/SKILL.md)
 - `mcaf-dotnet-quickdup` — [Folder](https://github.com/managedcode/MCAF/blob/main/skills/mcaf-dotnet-quickdup), [Raw SKILL](https://raw.githubusercontent.com/managedcode/MCAF/main/skills/mcaf-dotnet-quickdup/SKILL.md)
 - `mcaf-dotnet-reportgenerator` — [Folder](https://github.com/managedcode/MCAF/blob/main/skills/mcaf-dotnet-reportgenerator), [Raw SKILL](https://raw.githubusercontent.com/managedcode/MCAF/main/skills/mcaf-dotnet-reportgenerator/SKILL.md)
diff --git a/skills/mcaf-dotnet-profiling/SKILL.md b/skills/mcaf-dotnet-profiling/SKILL.md
@@ -0,0 +1,132 @@
+---
+name: mcaf-dotnet-profiling
+description: "Use the free official .NET diagnostics CLI tools for profiling and runtime investigation in .NET repositories. Use when a repo needs CPU tracing, live counters, GC and allocation investigation, exception or contention tracing, heap snapshots, or startup diagnostics without GUI-only tooling."
+compatibility: "Requires a .NET app or process to inspect; respects the repo's `AGENTS.md` commands first."
+---
+
+# MCAF: .NET Profiling
+
+## Trigger On
+
+- the repo needs performance or runtime profiling for a .NET application
+- the user asks about slow code, high CPU, GC pressure, allocation growth, exception storms, lock contention, or startup diagnostics
+- the team wants official CLI-based diagnostics without depending on `dnx`
+
+## 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
+
+- replacing realistic performance tests or load tests with ad-hoc tracing alone
+- production heap collection when the pause risk has not been accepted
+- GUI-only workflows that the repo cannot automate or document
+
+## Inputs
+
+- the nearest `AGENTS.md`
+- target application, process, or startup path
+- the symptom being investigated: CPU, memory, GC, contention, exceptions, or startup
+
+## 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.
+
+## Workflow
+
+1. Build and run a realistic target first:
+   - prefer `Release`
+   - prefer realistic config, inputs, and data volume
+2. Start with the lightest useful tool:
+   - `dotnet-counters` for live health signals
+   - `dotnet-trace` for CPU, exception, contention, GC, and startup traces
+   - `dotnet-gcdump` for managed heap inspection when memory shape matters
+3. Prefer installed CLI tools over `dnx` one-shot execution so the repo commands stay stable and reproducible.
+4. Capture one focused profile at a time instead of mixing every signal into one run.
+5. For CPU and general runtime hotspots, start with `dotnet-trace collect`.
+6. For live triage, start with `dotnet-counters monitor` on `System.Runtime`.
+7. For heap analysis, use `dotnet-gcdump` carefully and document the pause risk.
+8. After each change, rerun the same measurement path and compare before versus after.
+
+## Bootstrap When Missing
+
+If official .NET profiling tools are not available yet:
+
+1. Detect current state:
+   - `dotnet --info`
+   - `dotnet tool list --global`
+   - `command -v dotnet-counters`
+   - `command -v dotnet-trace`
+   - `command -v dotnet-gcdump`
+2. Choose the install path deliberately:
+   - preferred machine-level install:
+     - `dotnet tool install --global dotnet-counters`
+     - `dotnet tool install --global dotnet-trace`
+     - `dotnet tool install --global dotnet-gcdump`
+   - direct-download fallback when global tools are not suitable:
+     - use the official Microsoft Learn download links for `dotnet-counters`, `dotnet-trace`, and `dotnet-gcdump`
+3. Verify the installed tools resolve correctly:
+   - `dotnet-counters --version`
+   - `dotnet-trace --version`
+   - `dotnet-gcdump --version`
+4. Record exact profiling commands in `AGENTS.md`, for example:
+   - `dotnet-counters monitor --process-id <pid> --counters System.Runtime`
+   - `dotnet-trace collect --process-id <pid> --profile dotnet-common,dotnet-sampled-thread-time -o trace.nettrace`
+   - `dotnet-gcdump collect --process-id <pid> --output heap.gcdump`
+5. Run one bounded command and return `status: configured` or `status: improved`.
+6. If the repo intentionally standardizes on another profiling stack and does not want these tools, return `status: not_applicable`.
+
+## Deliver
+
+- explicit official .NET profiling commands
+- a clear profiling path for CPU, counters, and heap inspection
+- reproducible diagnostics commands that humans and agents can rerun
+
+## Validate
+
+- the chosen tool matches the actual symptom
+- commands target a realistic process and configuration
+- before/after comparisons use the same scenario
+- heap collection warnings are explicit when `dotnet-gcdump` is used
+
+## 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.
+
+### 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.
+
+## Load References
+
+- read `references/profiling.md` first
+
+## Example Requests
+
+- "Profile this .NET app for CPU hotspots."
+- "Investigate GC pressure in this service."
+- "Capture counters and a trace from startup."
+- "Set up official .NET profiling tools for local investigations."
diff --git a/skills/mcaf-dotnet-profiling/references/profiling.md b/skills/mcaf-dotnet-profiling/references/profiling.md
@@ -0,0 +1,175 @@
+# Official .NET Profiling Tools
+
+## What This Skill Uses
+
+This skill standardizes on official CLI-based .NET diagnostics tools:
+
+- `dotnet-counters` for live metrics and exported counters
+- `dotnet-trace` for trace capture and hotspot investigation
+- `dotnet-gcdump` for managed heap snapshots
+
+It intentionally avoids `dnx`-only flows so the commands remain explicit and durable in repo docs.
+
+## Installation Paths
+
+Preferred install path for frequent local diagnostics:
+
+```bash
+dotnet tool install --global dotnet-counters
+dotnet tool install --global dotnet-trace
+dotnet tool install --global dotnet-gcdump
+```
+
+Verify the tools:
+
+```bash
+dotnet-counters --version
+dotnet-trace --version
+dotnet-gcdump --version
+```
+
+If global tools are not suitable, use the official Microsoft Learn direct-download links for each tool:
+
+- `dotnet-counters`
+- `dotnet-trace`
+- `dotnet-gcdump`
+
+## Release-First Rule
+
+Profile realistic builds and realistic scenarios:
+
+```bash
+dotnet build -c Release
+dotnet run -c Release --project ./src/MyApp/MyApp.csproj
+```
+
+Avoid profiling Debug builds unless the debugging overhead itself is the question.
+
+## First-Line Live Triage with dotnet-counters
+
+Use `dotnet-counters` first when you need fast feedback about:
+
+- CPU usage
+- GC activity
+- allocation growth
+- exception rate
+- working set
+- thread pool pressure
+
+List candidate processes:
+
+```bash
+dotnet-counters ps
+```
+
+Monitor runtime counters:
+
+```bash
+dotnet-counters monitor --process-id <pid> --counters System.Runtime
+```
+
+Export counters for later comparison:
+
+```bash
+dotnet-counters collect --process-id <pid> --counters System.Runtime --format json -o counters.json
+```
+
+For startup diagnostics:
+
+```bash
+dotnet-counters monitor --counters System.Runtime -- dotnet exec ./bin/Release/net10.0/MyApp.dll
+```
+
+## CPU and Runtime Tracing with dotnet-trace
+
+Use `dotnet-trace` when counters show that deeper investigation is needed.
+
+List candidate processes:
+
+```bash
+dotnet-trace ps
+```
+
+Capture a focused general-purpose trace:
+
+```bash
+dotnet-trace collect --process-id <pid> --profile dotnet-common,dotnet-sampled-thread-time -o trace.nettrace
+```
+
+Capture GC-heavy detail:
+
+```bash
+dotnet-trace collect --process-id <pid> --profile gc-verbose -o gc.nettrace
+```
+
+Trace startup directly:
+
+```bash
+dotnet-trace collect -- dotnet exec ./bin/Release/net10.0/MyApp.dll
+```
+
+Get a top-method summary from a captured trace:
+
+```bash
+dotnet-trace report trace.nettrace topN --number 20
+```
+
+Convert for external viewers when needed:
+
+```bash
+dotnet-trace convert trace.nettrace --format Speedscope
+```
+
+## Exceptions, Contention, and JIT Clues
+
+`dotnet-trace` is the main CLI path when you need:
+
+- exception-heavy traces
+- contention signals
+- JIT and runtime event visibility
+
+Keep the run focused and compare the same scenario before and after each fix.
+
+## Heap Investigation with dotnet-gcdump
+
+Use `dotnet-gcdump` when you need managed heap composition rather than CPU stacks.
+
+List candidate processes:
+
+```bash
+dotnet-gcdump ps
+```
+
+Capture a heap snapshot:
+
+```bash
+dotnet-gcdump collect --process-id <pid> --output heap.gcdump
+```
+
+Get a heap summary report:
+
+```bash
+dotnet-gcdump report heap.gcdump
+```
+
+Important warning:
+
+- `dotnet-gcdump collect` triggers a full Gen 2 GC
+- this can pause the target process for a long time on large heaps
+- do not use it casually on latency-sensitive production paths
+
+## Practical Investigation Order
+
+1. Reproduce the issue in a realistic `Release` scenario.
+2. Start with `dotnet-counters monitor`.
+3. If the symptom is CPU or startup related, capture `dotnet-trace`.
+4. If the symptom is memory-shape related, capture `dotnet-gcdump`.
+5. Apply one fix at a time.
+6. Rerun the same command set and compare.
+
+## Useful Guardrails
+
+- use the same user as the target process, or root where required
+- on Linux and macOS, the tool and target process may need the same `TMPDIR`
+- prefer `dotnet exec` or direct app launch over `dotnet run` for startup tracing, because `dotnet run` may spawn extra child processes
+- keep artifacts named and stored predictably so comparisons are easy
