csharp-docs-and-comments

---
name: csharp-docs-and-comments
description: Add and improve XML documentation and comments in C# code. Use when asked to document C#, improve docs, add XML comments, audit documentation, doc warnings, or improve code comments in .NET projects.
license: Apache-2.0
---

# csharp-docs-and-comments

Adds and improves XML documentation comments (`///`) and inline code comments (`//`) in C# codebases.

**Audience of the generated documentation**: senior developer *consumers* — write for someone who knows C# but may not know this domain. Deliver context, constraints, domain concepts, preconditions, postconditions, side-effects, and differences between similar members. Never narrate what identifiers or signatures already say.

For full standards see `./REFERENCE.md`.

---

## Phase 0 — Argument Parsing

If the skill is invoked with an argument, infer scope from the pattern before asking questions:

| Pattern | Interpretation |
| --- | --- |
| No dots — e.g. `Duid` | Type name |
| Dots, no `::` — e.g. `NetDuid.Duid` | Fully-qualified type or namespace; grep to determine which |
| Contains `::` — e.g. `Duid::TryParse` | Member (method, property, field) on a type |

If scope is inferred from an argument, **skip Q1** in Phase 1.

---

## Phase 1 — Setup Questions

Ask all applicable questions together in one `AskUserQuestion` call.

### Q1 — Target scope (single-select; skip if argument provided)

- **Entire solution** — all non-generated `.cs` files in all projects
- **Specific project(s)** — discover `.csproj` files; present up to 3 as quick-picks + Other
- **Specific namespace(s)** — grep for unique namespace declarations; present up to 3 + Other
- **Specific type(s)** — use Other; prompt format: `TypeName` or `Namespace.TypeName`
- **Specific method or property** — use Other; prompt format: `TypeName::MemberName`

### Q2 — Comment types (multi-select)

- **XML documentation comments** (`///`) — API contract for consumers, drives IntelliSense
- **Inline code comments** (`//`) — internal reasoning for maintainers

### Q3 — Noisy comment policy (single-select)

- **Flag** — mark with `// TODO: low-value comment — consider removing or improving` but leave intact
- **Improve** — rewrite to add the missing context that would make it genuinely useful
- **Remove** — silence is better than noise; incorrect or obvious comments actively mislead

---

## Phase 2 — Discovery

1. **Locate solution root**: find `.sln` or (if absent) the nearest `.csproj`.
2. **Custom dictionary**: find all `*.dict`,`*.dic` files in the solution tree. Collect their words as valid terms for spell-checking.
3. **Enumerate target files** matching the scope; **exclude**:
   - Files inside `obj/` or `bin/` directories
   - `*.g.cs`, `*.Designer.cs`, `AssemblyInfo.cs`, `GlobalUsings*.cs`
   - Files whose first 5 lines contain `<auto-generated>`
4. **Partial class resolution** (type scope): grep for `partial (class|struct|record|interface) TypeName` across all non-excluded files; collect every matching file as part of the target.
5. **Overload resolution** (member scope): locate all files containing the type, then collect every overload sharing that member name.
6. **Namespace resolution**: grep `^\s*namespace TargetNamespace(\b|;|{)` across all non-excluded files.
7. **Identify test projects** by convention: project name or directory ends in `.Tests`, `.Test`, or `Tests`. Apply relaxed rules to files in test projects (see ./REFERENCE.md §9).

---

## Phase 3 — Branch Setup

### Large scope (solution / project / namespace)

Before making any edits, confirm a git repo is present and create an isolated branch:

```bash
git checkout -b "docs/csharp-docs-and-comments-$(echo '<scope>' | tr '.' '-' | tr '[:upper:]' '[:lower:]')-$(date +%Y%m%d%H%M)"
```

All edits land on this branch. Report the branch name at the end with review instructions.

### Small scope (type or member)

Edit the working tree directly — no branch needed.

---

## Phase 4 — Execution

### File-count thresholds

| Files | Strategy |
| --- | --- |
| ≤ 3 | Edit directly; apply ./REFERENCE.md standards inline |
| 4–15 | 2–3 parallel sub-agents, files batched evenly |
| > 15 | Parallel sub-agents, one per batch of 3–5 files |

### C# Docs Specialist sub-agent prompt

For each sub-agent batch, compose this prompt (fill in bracketed values):

```
You are a C# documentation specialist for a .NET codebase.

STEP 1 — Read the standards:
  Read the file at: csharp-docs-and-comments/./REFERENCE.md
  Follow every rule in it. Pay particular attention to the Quality Checklist (last section).

STEP 2 — Understand the task:
  Improve [XML documentation comments (///) / inline code comments (//) / both]
  in the files listed in Step 4.

  Context:
  - Audience: senior C# developers who know the language but not this codebase's domain.
  - Noisy comment policy: [flag with TODO / improve to add context / remove].
  - Valid project dictionary words (do not flag as misspellings): [list *.dict words].
  - These files are from a [source / test] project.

STEP 3 — Rules summary (full rules in ./REFERENCE.md):
  - Never write comments that restate what identifiers or signatures already say.
  - DO document: why code exists, domain concepts, constraints, preconditions,
    postconditions, exceptions (with circumstances), side-effects, differences
    from similar members, dangerous-refactoring warnings.
  - All public types and members require XML docs.
  - Use <inheritdoc/> on members that implement an interface or override a base
    class member. Use <inheritdoc cref="..."/> when the source is ambiguous.
    Never use <inheritdoc/> when there is nothing to inherit from.
  - For test projects: skip XML docs on test methods whose name + AAA structure
    fully conveys intent. Fix malformed existing comments regardless.
  - Skip generated files (*.g.cs, *.Designer.cs, <auto-generated> header).
  - For partial classes: document the primary declaration; other partials may
    use <inheritdoc/> or add member-specific docs.

STEP 4 — Files to process:
  [list absolute file paths, one per line]

STEP 5 — After editing:
  Run the Quality Checklist from ./REFERENCE.md against your own changes.
  Report back:
  - Files changed (list)
  - Quality checklist: pass / fail / N-A per item
  - Any items that could not be satisfied, and why
```

---

## Phase 5 — Summary Report

After all edits (and sub-agent results are collected), report to the user:

1. **Files changed** — list each modified file
2. **Quality checklist** — aggregate pass/fail per item across all files
3. **Branch** (if created):
   - Branch name
   - `git diff main...<branch>` to inspect changes
   - `git merge <branch>` or open a PR to apply
4. **Build check** — ask: *"Run `dotnet build` to confirm no compilation errors?"*