# Dotnet Docfx Digest > Use when the user wants to create, repair, audit, or complete DocFX docs for .NET public APIs, or has changed public API that needs namespace pages, XML comments, overwrite files, extension-member tables, examples, or build verification. Exclude private/internal APIs. - Skill: `codebeltnet/dotnet-docfx-digest` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add codebeltnet/dotnet-docfx-digest` - Raw SKILL.md: https://api.skillmd.com/api/skills/codebeltnet/dotnet-docfx-digest/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: codebeltnet (https://skillmd.com/u/codebeltnet) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/codebeltnet/dotnet-docfx-digest --- # .NET DocFX Digest Steward ## Description Create and maintain developer-friendly DocFX documentation digests for .NET public APIs. Keep namespace pages, generated API pages, examples, availability notes, and verification aligned with the actual source code and tests. ## Critical - This skill is autonomous by default. If the user invokes it without naming a namespace, type, member, or changed API — including a bare direct skill call with no parsed arguments, a host-initiated continuation, or a host re-entry that invokes `dotnet-docfx-digest` directly with no extra arguments after the skill already auto-triggered — assume non-human/autonomous execution, treat the request as a repo-wide DocFX audit and repair task, and do not ask startup scoping or approval-to-continue questions. - Resolve bundled scripts from the loaded `dotnet-docfx-digest` skill directory first. If that install path is unavailable and the target repository contains the repo-managed source copy, fall back to `skills/dotnet-docfx-digest/scripts/*.cs`. Do not claim the scripts are unavailable until both locations have been checked. - `docfx.cs` is fast by default: a plain run validates Markdown, prose, DocFX overwrite layout, namespace pages, extension tables, and required examples **without building, restoring, or running DocFX/gh**. Use it freely during iteration — it discovers the public API from existing DocFX YAML metadata or a conservative source scan, and ends with a `[processes] dotnet=0 msbuild=0 docfx=0 gh=0` summary. Compilation and network access are opt-in. - Iterate quickly with the fast path, reading diagnostics as the next work queue: ```bash dotnet run --file "/scripts/docfx.cs" -- --repo-root "" --json ``` - Before claiming completion, run `agents.cs`, then a thorough build-backed verification that compiles samples, uses reflection-backed API discovery, and verifies the DocFX build: ```bash dotnet run --file "/scripts/agents.cs" -- --repo-root "" dotnet run --file "/scripts/docfx.cs" -- --repo-root "" --build-api-model --validate-samples --verify-docfx-build ``` - `--build-api-model` makes API discovery reflection-precise (the fast source-scan path is conservative and may under-report), `--validate-samples` compiles every C# documentation sample through isolated projects in one temporary `.slnx` graph build with bounded MSBuild parallelism, and `--verify-docfx-build` confirms the DocFX build succeeds. Treat `API_MODEL_SOURCE_SCANNER_LIMITED` in a fast run as a reminder to run the build-backed verification before completion, not as a failure. - Treat the current build-backed JSON result as authoritative over earlier fast-path diagnostics. If `--build-api-model` clears fast source-scan errors such as interim-artifact findings for real public type pages, do not keep repairing stale diagnostics from a previous fast run; proceed from the current `summary` object and rerun the final gate when ready. - The JSON completion fields live under the top-level `summary` object near the start of the report. For long or truncated output, search saved stdout for `completionState`, `canClaimCompletion`, `fullVerificationRan`, `remainingWorkItems`, `remainingGates`, `remainingDiagnosticsByCode`, `newlyIntroducedSkipMarkers`, and `interimArtifacts` before reading the full diagnostic payload. - For noisy audits, write and read a deterministic assessment work queue with `--assessment-queue`. This works on the fast path; add `--search-examples` to embed real GitHub usage: ```bash dotnet run --file "docfx.cs" -- --repo-root "" --json --assessment-queue --search-examples ``` Resolve `` outside the target repository working tree (for example, `$env:TEMP\docfx-assessment-queue.md` on Windows or `/tmp/docfx-assessment-queue.md` on Unix). The assessment work queue includes a "GitHub Example Sources" section with pre-computed `gh search code` commands and GitHub search URLs for each documented package. Read that section before writing any new example — do not write examples from memory or invention when real source evidence is available. If `--search-examples` is provided and `gh` is authenticated, actual search results are embedded; otherwise, the search commands are ready to run. - While diagnostics remain, the only valid mid-run behaviors are: keep repairing, or report a genuine external blocker with the exact command, exit code, and failure output. Do not emit progress tables, checkpoint summaries, review pauses, "Would you like me to continue?" prompts, or focus/verify menus just because a batch finished, the queue is large, or the session has been long. - Do not reclassify validator errors as "quality backlog", "pre-existing prose work", "massive writing task", "informational collision warnings", or "remaining improvements" while the completion contract is dirty. `EXAMPLE_LEAD_MISSING`, `EXAMPLE_ADVANCED_LEAD_MISSING`, `FAMILY_ANCHOR_EXAMPLE_MISSING`, `SAMPLE_STRUCTURE_INVALID`, `FAIL_NEW_SKIP_MARKER_INTRODUCED`, `SAMPLE_SKIP_NOT_ALLOWLISTED`, `INTERIM_ARTIFACT_IN_WORKTREE`, `SYMBOL_COLLISION_UNRESOLVED`, and `EXTENSION_OWNER_AMBIGUOUS` are blocking repair queues just like compile failures and missing examples. The next action is to repair the next diagnostic and rerun, not to write a final audit report. - For repo-wide or other full authoring runs, establish a bounded write queue before authoring new examples or overwrite rewrites: ```bash dotnet run --file "/scripts/docfx.cs" -- --repo-root "" --build-api-model --project-manifest --json ``` Resolve `` outside the target repository working tree (for example, `$env:TEMP\dotnet-docfx-digest-project-manifest.json` on Windows or `/tmp/dotnet-docfx-digest-project-manifest.json` on Unix). When you name this command in a continuation response, replace the placeholder with that concrete temp/session path rather than leaving `` unresolved. Read the reflection-backed packets from that manifest or from `scope.packets`. If build-backed packet discovery still fails or remains unusable, fall back to sequential assessment-work-queue or namespace-first order instead of authoring from the raw global count alone. - In any mid-audit continuation after a rerun, name the active queue source explicitly. If a reflection-backed packet manifest has not already been confirmed, the next step must explicitly be `--build-api-model --project-manifest ` before more large-scale example authoring. Do not talk generically about "working packet-by-packet" without naming how those packets are obtained. - In every continuation response while diagnostics remain, include an explicit completion-gate sentence that names the final command family and contract, for example: `Completion gate remains docfx.cs --build-api-model --validate-samples --verify-docfx-build --json; do not claim completion until summary.fullVerificationRan = true, summary.canClaimCompletion = true, summary.remainingWorkItems = 0, summary.remainingGates is empty, summary.remainingDiagnosticsByCode is empty, summary.newlyIntroducedSkipMarkers = 0, and summary.interimArtifacts = 0.` Shorter "verify later" wording is not sufficient. - In that same continuation response, explicitly state the fast rerun cadence for the active queue, for example: `After each small batch, rerun fast docfx.cs --json and continue.` Do not rely on implicit phrases like "micro-loop" or "packet-by-packet" alone. - A host may re-enter the skill by invoking `dotnet-docfx-digest` directly with no extra arguments after the first rerun. Treat that no-argument re-entry as the same repo-wide continuation, not as a fresh human checkpoint. If hundreds or thousands of repairable diagnostics remain, they are still the active work queue; keep repairing instead of pausing for approval, review, or scope confirmation. - Existing Markdown links, `Related:` entries, and historical URL references are documentation evidence. Preserve them during prose rewrites. Remove or replace a URL only after directly verifying that the current destination returns HTTP 404. Timeouts, 403s, rate limits, DNS failures, and other lookup problems are not removal evidence. - Keep interim artifacts out of the target repository. Assessment queues, project manifests, review reports, captured validator output, progress notes, and one-off helper scripts belong in temp or session storage. New working-tree files are only legitimate when they are known `dotnet-docfx-digest` deliverables: the managed `AGENTS.md` block, the active `docfx.json`, the deterministic `skip-compile-allowlist.json` waiver file when one is truly required, or DocFX-authored namespace/type Markdown that maps to a real public namespace or type. The validator auto-detects generic-arity type families and skips redundant sibling examples from the public API surface alone, so no family-skip manifest is ever written into the repository. If `docfx.cs` reports `INTERIM_ARTIFACT_IN_WORKTREE`, treat those files as blocking cleanup work before completion. - Namespace/prose-only repairs are latency-sensitive. Prefer direct edits or small sibling batches in the main agent. Use fresh workers only for example-heavy or source-heavy packets. If a prose-focused worker has not produced a concrete diff within about 45 seconds, or it goes quiet after producing its assigned file, inspect the diff, stop delegating that class of work, and continue inline. A quiet or "needs attention" worker is not a stop condition for the overall digest. - `ENCODING_CORRUPTION` in the JSON output means a documentation file has double-encoded UTF-8 (mojibake). Restore with `git checkout HEAD -- ` if the committed version was correct, or use the edit tool or byte-level operations to rewrite the file safely. Never pipe content through `Get-Content` + `Set-Content` or `[System.Text.Encoding]::UTF8.GetBytes()` on documentation files that contain multi-byte characters or emoji. - `EXTENSION_TABLE_ENCODING` means the ⬇️ emoji (U+2B07) is missing or corrupted in an Extension Members table data row. Use the literal `⬇️` character, not HTML entities or text substitutes. - `EXTENSION_RECEIVER_MISMATCH` and `EXTENSION_METHOD_SIGNATURE_MISSING` mean the table collapsed the real extension signature. Keep decorated receivers such as `IDecorator` in the Type column, and keep generic method arity such as `As` or `Configure` in the Methods column instead of flattening them to bare names or wrapped inner types. - `EXTENSION_METHOD_UNKNOWN` means the table lists an invented or stale method name that is not a public extension method in the API model. Remove it or replace it with a source-backed public extension method; do not invent plausible `AddX` setup names from package or namespace names. - `EXTENSION_METHOD_MISSING` and `EXTENSION_METHOD_SIGNATURE_MISSING` are still namespace-layer repair work. If they appear right after `EXTENSION_SECTION_MISSING` drops, that means the validator can finally inspect table contents; keep repairing `Extension Members` tables across the active queue before resuming net-new type/example authoring. - `XREF_MEMBER_LINK` means a Markdown file uses `xref:UID` syntax to reference a method or member (a UID containing `(` or a dotted UID that does not resolve to a known type or namespace). `xref:` links to method and member UIDs do not resolve outside a DocFX build: GitHub, NuGet README, and other Markdown renderers render them as broken links. Replace each with an absolute anchor URL by fetching `{siteBaseUrl}/xrefmap.yml` from the deployed docs site, finding the entry where `uid:` matches, extracting its `href` value, and constructing `[label]({siteBaseUrl}/{href})`. The `href` follows the pattern `api/TypePage.html#TypePage_Member_ParamTypes_` with dots, parentheses, and commas replaced by underscores. Set `build.sitemap.baseUrl` in `docfx.json` to have the validator include the concrete URL in the diagnostic message. Type-level `xref:` links such as `` resolve correctly and do not trigger this diagnostic. - If either script cannot run, report the exact command, exit code, and failure output. Do not claim repository guidance or documentation was verified unless the scripts actually ran successfully. - Treat validator errors as the repo-wide repair queue, not as evidence that the repository is "blocked." A diagnostic being old, pre-existing, numerous, or outside the first files edited does not remove it from scope. A run with 1,228 `EXAMPLE_MISSING` findings means 1,228 documentation items remain; repairing one type page is a partial result, not a digest. - A rerun that clears a coarse diagnostic and reveals a more specific one is progress, not a blocker. If `EXTENSION_SECTION_MISSING` drops and `EXTENSION_METHOD_MISSING` appears, or namespace/table repairs expose more `EXAMPLE_MISSING` targets, treat the newly surfaced codes as the next deterministic queue and keep repairing. - Expect queue expansion after structural repairs. Example: `EXTENSION_SECTION_MISSING` can drop from 62 to 13 while `EXTENSION_METHOD_MISSING` jumps from 0 to 157 because the validator can finally inspect table contents. Total counts may rise; that is still progress. Continue repairing the newly exposed queue. - While `summary.remainingWorkItems` is greater than zero, `summary.canClaimCompletion` is `false`, or `completionState` is not the final clean state, do not emit formatted progress tables, before/after counts, file-count summaries, "remaining work" dashboards, or "Next Steps" lists. The only valid outputs are more repair work, or a genuine external blocker reported with the exact command, exit code, and failure output. - Do not turn partial progress into a decision menu. While repairable diagnostics remain, never stop to ask whether to continue, focus a subset, or "just run verification." Only ask the user to choose when inspection exposes a real correctness-affecting decision or a genuine external blocker stops further execution. - `EXAMPLE_MISSING` is the core authoring queue, not optional backlog. Even when it is the only remaining diagnostic family and the count is in the hundreds or thousands, the digest is still incomplete. Do not stop for a checkpoint, completion report, approval pause, dry-run suggestion, or next-step menu; keep creating compiling examples until `EXAMPLE_MISSING` reaches zero. - Treat the next unaddressed `EXAMPLE_MISSING` diagnostic as the only thing that exists. Work it, rerun, then work the next. Counts, percentages, and "remaining work" numbers are progress indicators, not decision points. - Treat example-lead diagnostics the same way. If examples compile but `EXAMPLE_LEAD_MISSING` or `EXAMPLE_ADVANCED_LEAD_MISSING` remains, the examples are still unfinished. Add source-grounded fly-ins directly to the implicated files in small batches, rerun the fast validator, and continue until the lead diagnostics reach zero. Do not stop because the work is mostly prose, because the examples were pre-existing, or because hundreds of leads are missing. - Treat `INTERIM_ARTIFACT_IN_WORKTREE` as active cleanup work, not a note for later. Classify each reported path, preserve legitimate deliverables, and move or remove scratch output before any completion claim. - Use this strict repair order for repo-wide and other full audits: (1) safety, encoding, overwrite-layout, and scope-establishing blockers; (2) a namespace-first pass across the active queue — namespace pages, namespace prose, availability/start-here guidance, embedded-overwrite cleanup, and `Extension Members` tables; (3) once that namespace layer is globally clean or the rerun shows only example-driven work remains, `EXAMPLE_MISSING` plus example-quality, extension-invocation, and unresolved symbol-ownership diagnostics, processed packet by packet or namespace by namespace; (4) remaining informational warnings. Do not start net-new type/example authoring while namespace-layer diagnostics still remain elsewhere in the active queue, except when moving misplaced namespace-embedded examples into type-targeted files is itself the namespace repair. - Passing compilation is necessary but not sufficient. `EXAMPLE_PLACEHOLDER`, `EXAMPLE_REFLECTION_ONLY`, `EXAMPLE_TARGET_NOT_USED`, `EXTENSION_EXAMPLE_NOT_INVOKED`, `EXAMPLE_DEFAULT_PLACEHOLDER`, `EXAMPLE_NO_OBSERVABLE_OUTCOME`, `EXAMPLE_RUNTIME_TYPE_NAME_OUTCOME`, `EXAMPLE_EMPTY_ENTRY_POINT_STUB`, `EXAMPLE_FORWARDING_SCAFFOLD`, `EXAMPLE_TEMPLATE_REPETITION`, `EXAMPLE_LEAD_MISSING`, `EXAMPLE_ADVANCED_LEAD_MISSING`, and `EXAMPLE_UID_DUPLICATE` are blocking quality failures. Never satisfy the inventory with `Type.GetType`, assembly metadata inspection, runtime implementation names, an empty local `Program` stub, `DocumentedTypeExample`, `DocumentedExtensionExample`, generic `Describe()` helpers, repeated UID sections, prose that merely names the target, a missing or placeholder-only example fly-in, a `default!`/`null!` holder property that only parks the type, a class that just constructs or returns the target with no observable result, a mass-forwarding shell of one-line pass-through members, or one normalized code skeleton reused across unrelated types. - Namespace prose must be decision-useful. `NAMESPACE_PROSE_INVENTORY_ONLY`, `NAMESPACE_APPEND_ONLY_REPAIR`, `NAMESPACE_PROSE_TEMPLATE_REPETITION`, `NAMESPACE_USAGE_GUIDANCE_MISSING`, and `NAMESPACE_START_HERE_MISSING` mean the page still needs a problem/outcome opening, a cohesively rewritten lead instead of a weak inventory sentence with guidance appended below it, an opening written from the namespace's own purpose rather than a shared template, concrete "when to use" guidance, and a named starting API when the namespace has multiple entry points. - Namespace overview files are single-UID deliverables. `NAMESPACE_EMBEDDED_OVERWRITE_SECTION` means the page mixed namespace guidance with secondary `uid:` / `example:` mappings after the overview, often below `Extension Members`. Move those type/member examples to readable type-targeted files under `.docfx/api/types/`, usually the declaring extension class page, and keep the namespace page limited to the namespace fly-in, availability, related links, and optional `Extension Members` table. - Use the JSON completion contract as the final authority: completion requires `summary.fullVerificationRan` to be `true`, `summary.canClaimCompletion` to be `true`, `summary.remainingWorkItems` to be `0`, `summary.remainingGates` and `summary.remainingDiagnosticsByCode` to be empty, `summary.newlyIntroducedSkipMarkers` to be `0`, `summary.interimArtifacts` to be `0`, and the build-backed command to succeed. A clean fast run reports `completionState: verification-required`; it is an iteration checkpoint, not completion. Never describe `status: failed`, `completionState: incomplete`, or `completionState: verification-required` as completed work. - Warnings are reported separately from the completion contract, but unresolved ownership is not a warning escape hatch. `SYMBOL_COLLISION_UNRESOLVED` blocks until every colliding type has a C# example mapped to its exact type UID. `EXTENSION_OWNER_AMBIGUOUS` blocks until every affected extension example targets its exact declaring-type or method UID and invokes the method through receiver syntax rather than `Extensions.Method(receiver)`. These diagnostics clear when that evidence exists; do not chase the collision itself or invent a different owner. Residual informational warnings such as `TYPE_FORWARDING_UNRESOLVED` may be reported after a build-backed final run succeeds with `summary.canClaimCompletion = true`. - When you defer completion, name the exact endgame command `--build-api-model --validate-samples --verify-docfx-build` and the final JSON completion contract (`summary.fullVerificationRan = true`, `summary.canClaimCompletion = true`, `summary.remainingWorkItems = 0`, empty `summary.remainingGates`, empty `summary.remainingDiagnosticsByCode`, `summary.newlyIntroducedSkipMarkers = 0`, `summary.interimArtifacts = 0`). Do not replace that with generic "verify later" language. - Treat that sentence as mandatory even in short follow-up replies that only explain the next queue. A compact response is fine; omitting the explicit completion gate is not. - Continue documentation repair when `dotnet test` fails for an unrelated environmental dependency such as an unavailable database. Report that test failure separately. It is a blocker only if it prevents the documentation validator, source inspection, or required sample compilation from running. - Valid BOM-less UTF-8 is compliant. The validator must not emit `ENCODING_BOM_MISSING` (that diagnostic is intentionally unsupported), and an audit must not add/remove BOMs or normalize line endings solely for consistency. BOM presence has no documentation value; preserve the file's existing state and continue detecting actual `ENCODING_CORRUPTION` and `EXTENSION_TABLE_ENCODING` damage. - Final verification uses adaptive execution. In `auto`, machines with more than 8 available logical processors and more than 32 GiB available memory select `high-capacity`: DocFX verification runs concurrently in its isolated temp copy while the main lane builds/discovers API and then compiles samples, and MSBuild worker counts scale up to half the available processors (capped at 16). Smaller machines select `conservative` and keep the phases sequential with low worker counts. Override with `--execution-profile conservative|high-capacity` or `DOCFX_DIGEST_EXECUTION_PROFILE`. - Child processes time out after 30 minutes by default, configurable with `--process-timeout-minutes` or `DOCFX_DIGEST_PROCESS_TIMEOUT_MINUTES`. Use `host timeout >= process timeout + 5 minutes` (35 minutes for the default) so the validator can kill a timed-out child and return a deterministic diagnostic instead of being terminated by the caller first. - Long-running API builds, sample compilation, and DocFX verification write progress to `stderr`: an initial `[ ]` line, a heartbeat every 10 seconds, and a final `[✓]` or `[x]` line. Heartbeats name the active phase, workload size, runner count, PID, elapsed time, time since the child last produced output, and its latest output line when available. Do not suppress `stderr` during normal interactive runs; `--json` remains a single parseable document on `stdout`. When PowerShell or another host makes heartbeat noise obscure JSON inspection, pass `--quiet` or `--no-heartbeat` to suppress start/heartbeat chatter while keeping final `[✓]`/`[x]` child-process markers. In high-capacity mode, concurrent phase heartbeats can interleave; use JSON stdout and the final per-phase markers as the authoritative result, not the visual order of progress lines. - When reporting adaptive execution, include the selected profile, processor and memory inputs, build/sample worker counts, timeout, concurrent/sequential choice, process counts, and phase timings from JSON. State that sample compilation follows API discovery because scoped references depend on the namespace-to-project map. Name CLI and environment overrides for profile, worker counts, and timeout when the user asks how to tune the run. - When reporting heartbeat behavior, state the complete contract: append-only `stderr`, no cursor-rewritten table, start and 10-second heartbeat events, final success/failure marker for all three long phases, latest non-empty child-output line when available, and plain redirected-log markers that do not depend on ANSI color. When reporting encoding safety, explicitly confirm the diff contains neither BOM-only nor line-ending-only changes. - Read `references/workflow.md` when you need the detailed targeted/audit workflows, namespace and example templates, the verification checklist, or the completion response shape. - Prefer bounded project packets over one repository-sized authoring context. Discover packets with `docfx.cs --json` (`scope.packets`) or persist them with `--project-manifest `; process one packet at a time while keeping the user's requested scope unchanged. For repo-wide or other full authoring runs, create or refresh a reflection-backed manifest with `--build-api-model --project-manifest ` before the first new example or overwrite rewrite and treat that packet set as the active queue. Repair packet-local diagnostics before moving on when practical. If one diagnostic remains difficult after concrete attempts, record it, continue independent packets, and return to it; never turn one repairable packet failure into a reason to stop a full-repository run. When `summary.scopeState` is `provisional` and `BUILD_BACKED_SCOPE_REQUIRED` fires, the source-scan inventory may drive markdown triage only; it must not authorize a full authoring run. - If a fast `--project-manifest` or `scope.packets` result contains unnamed packets, zero projects, or `metadataGroup: unknown`, that is a provisional source-scan artifact. Immediately rerun packet discovery with `--build-api-model --project-manifest ` (or use generated DocFX YAML) and continue from the reflection-backed packet set. Do not treat weak fast-packet metadata as a blocker or as justification to stop. - If build-backed packet discovery still fails or remains unusable, fall back to sequential repair instead of stopping. Use the assessment work queue order or namespace-first order: clear namespace-layer diagnostics first, then work the remaining `EXAMPLE_MISSING` diagnostics in namespace order, rerunning the fast validator after each small batch. - A rerun that leaves `EXAMPLE_MISSING` high while surfacing `EXTENSION_METHOD_MISSING` or `EXTENSION_METHOD_SIGNATURE_MISSING` is still in the namespace-first phase, not the example-only phase. Finish those table repairs first, rerun fast validation, and only then return to the example micro-loop. - Repository size, target count, diagnostic volume, context pressure, and model usage limits never change the user's requested scope. An explicit or default repo-wide run continues across every packet until the global completion contract is clean. - Context pressure, queue size, and estimates like "this would take multiple sessions" are internal execution concerns, not user-facing stop conditions. Shrink to a smaller deterministic batch, regenerate queue state from `--assessment-queue` / `--project-manifest` / active dry-run artifacts when needed, and keep going until the completion contract is clean unless the user explicitly pauses or a real external blocker prevents further progress. - Final build-backed verification (`--build-api-model --validate-samples --verify-docfx-build`) is for claiming completion, not for blocking incremental progress. While `summary.remainingWorkItems` is greater than zero or any diagnostics remain, stay on the fast `docfx.cs --json` loop and keep authoring. - Dry run is a voluntary mode used only when the user explicitly asks for `dry-run`, a representative sample, or a quality pilot. Never infer it from repository size, diagnostic count, context pressure, or model usage limits. It is a real run scoped to a representative subset, with identical evidence, authoring, quality, and compilation gates. Start it with `--dry-run --build-api-model --project-manifest `; this also emits a sibling `.review.json` template. Author every selected packet, read every changed page, complete every review entry with evidence, page-specific purpose/outcome, observable result, and sibling prose/code comparison, then finish with `--resume-project-manifest --review-report --build-api-model --validate-samples --verify-docfx-build`. The baseline protects pre-existing dirty work while allowing current-run files to verify. No-hint dry runs select one clean project per metadata destination group via a seed; explicit names override selection. Report `dry-run-passed` only after every gate passes, and include the completed `Changed-page review` table in the response; a validator summary is not a manual review. Never claim repository completion. Do not ask for hints when none were supplied. - Use the safe structured overwrite writer (`docfx.cs --write-overwrite `) for repeatable overwrite creation: it preserves BOM/line endings, rejects duplicate UIDs and unbalanced fences, and refuses to replace dirty files. It writes only content you authored — it never generates prose or examples. - Generic-arity type families — a series of public types whose UIDs share one base name and differ only by arity (for example `MutableTuple` with arity 1 through 20, or `TesterFunc` with arity 2 through 18) — are auto-detected by `docfx.cs` from the public API surface. The lowest-arity type is the anchor and keeps a real, behavioral example; the redundant siblings are skipped from standalone-example obligations. The namespace page must still name the anchor and explain how consumers choose among the arity siblings (`FAMILY_ANCHOR_EXAMPLE_MISSING` and `FAMILY_NAMESPACE_GUIDANCE_MISSING` enforce this). No file is written into the repository to declare or persist these skips. See `references/workflow.md`. ## Autonomous Persistence (Anti-Fatigue) Agents often fail this skill by stopping prematurely because they feel "overwhelmed" or "intimidated" by the scale of the task, or because they fall back to conversational habits. You must actively override these failures: - **Do not be intimidated by scale:** If you see 1,122 `EXAMPLE_MISSING` items, that is your active queue. Do not pause, do not write a summary table to "organize your thoughts", and do not ask the user for permission to continue. Work the next item. - **Do not downgrade prose diagnostics:** If compilation succeeds but hundreds of `EXAMPLE_ADVANCED_LEAD_MISSING` or `EXAMPLE_LEAD_MISSING` items remain, the run is still failing. Write the next source-grounded lead, rerun, and continue. Calling them "quality backlog" or "pre-existing prose" is the failure mode this skill is designed to prevent. - **Do not downgrade ownership diagnostics:** `SYMBOL_COLLISION_UNRESOLVED` and `EXTENSION_OWNER_AMBIGUOUS` are clearable errors, not informational facts about duplicate names. Add exact-UID example mappings and receiver-style calls until they clear; do not stop merely because every other diagnostic is gone. - **Do not leave cleanup to the user:** `INTERIM_ARTIFACT_IN_WORKTREE` means the working tree contains files that must be classified and cleaned before completion. Do that work inline unless deleting a path would risk user-authored documentation. - **Do not suffer diagnostic expansion fatigue:** When coarse diagnostics (like `EXTENSION_SECTION_MISSING`) drop and more specific ones (like `EXTENSION_METHOD_MISSING`) appear, the queue size may increase. This is expected progress, not a reason to stop, panic, or re-plan. Keep working. - **Do not turn context pressure into a handoff:** If you worry about context length, shrink to a smaller deterministic batch, rerun the fast validator, or regenerate the assessment queue / project manifest and continue. Do not summarize remaining work or defer it to a follow-up while diagnostics remain. - **Override conversational habits:** You are an autonomous agent on this task, not a chat assistant. The only valid time to stop and ask a question is if a genuine external blocker (like a missing dependency preventing compilation) halts execution. A large queue is never a blocker. - **Subagent timeouts are not stop conditions:** If a subagent times out or goes quiet, do not use that as an excuse to pause the main loop. Switch to direct edits or spawn a new subagent, and keep going. - **Do not invent context excuses:** Phrases such as "given context constraints", "best done in a follow-up", "remaining work requires authoring", "this is a massive task", and "I will provide a focused summary" are not valid reasons to stop while the completion contract is dirty. ## Context Exhaustion Protocol Context pressure is not a completion condition. If the session feels constrained while fail-level diagnostics remain, do one of the following instead of handing off: 1. continue with a smaller deterministic batch 2. regenerate required state from deterministic commands such as `docfx.cs --json --assessment-queue `, `docfx.cs --build-api-model --project-manifest `, or the active dry-run manifest/review pair; when you mention one of these commands in a continuation response, resolve the temp/session path concretely instead of leaving `` as a placeholder 3. use an explicitly supported continuation artifact for the active mode only when that mode defines one; otherwise keep queue state in temp or session storage instead of inventing repo-root scratch notes 4. report a true tooling failure with the exact command, exit code, and output Do not justify stopping with phrases such as "given context constraints", "best done in a follow-up", "remaining work requires authoring", "this is a massive task", or "I will provide a focused summary". If `summary.remainingWorkItems > 0`, the next action must be executable work, not a handoff. Valid next actions are: 1. inspect source for the next diagnostic batch 2. author examples or leads for the next diagnostic batch 3. fix ownership or collision diagnostics 4. rerun validation 5. fix validation/compiler failures 6. report a true blocker Final summaries are allowed only when `summary.canClaimCompletion` is `true` and the full completion contract is clean. ## No Premature Handoff Do not produce a final or comprehensive summary while `summary.canClaimCompletion` is `false`. When the validator reports remaining work, treat the remaining diagnostics as the execution queue and continue remediation. The following are not valid stopping conditions: many remaining diagnostics, many changed files, many generated files, an active queue, remaining prose repair, remaining examples, missing full verification, repetitive next steps, or the task taking longer than expected. If `summary.remainingWorkItems > 0`, the next action must be one of four things only: apply another remediation batch, run the required validator command, fix a validator/tooling failure, or report a true blocker with exact evidence. A progress summary is allowed only as a short status update before continuing work. It must not be framed as a final report, completion report, audit result, or handoff unless a true blocker exists. Final summaries are allowed only when `summary.completionState == "complete"`, `summary.canClaimCompletion == true`, `summary.remainingWorkItems == 0`, `summary.remainingGates` is empty, `summary.remainingDiagnosticsByCode` is empty, `summary.newlyIntroducedSkipMarkers == 0`, and `summary.interimArtifacts == 0`. ## Premature Handoff Detection Treat `FAIL_PREMATURE_HANDOFF_SUMMARY` as an execution-protocol failure when an agent attempts to end the run while `summary.canClaimCompletion` is false, `summary.remainingWorkItems` is greater than zero, `summary.remainingGates` is not empty, fail-level diagnostics remain, `summary.fullVerificationRan` is false, or unapproved skips/interim artifacts remain. The remediation is not to edit files about the failure. The remediation is to continue the autonomous loop: select the next diagnostic batch, apply fixes, rerun fast validation, repeat until the completion contract is satisfied, run full verification, and only then produce the final report. ## Context Handoff Detection Treat `FAIL_CONTEXT_HANDOFF_WITH_REMAINING_WORK` as an execution-protocol failure when an agent ends the run while `summary.remainingWorkItems > 0`, fail-level diagnostics remain, required gates remain, `summary.fullVerificationRan` is false, `summary.newlyIntroducedSkipMarkers` is non-zero, or `summary.interimArtifacts` is non-zero, and the stated reason is context size, session length, task size, repetitive authoring, a stable queue, or that the remaining work is better suited for a follow-up. The remediation is to continue the execution loop with a smaller deterministic batch. ## Skip Marker Policy Skip markers are waivers, not fixes. Agents must not introduce new skip markers during autonomous remediation unless the user explicitly approved that exact waiver, and even then the current run remains incomplete while the new marker exists. Approved skips must be declared in the deterministic allowlist `/skip-compile-allowlist.json`, not inferred from prose comments. Each entry includes `diagnosticCode`, `filePath`, `uid` or `symbol`, `reason`, `approval`, and `lifetime` (`temporary` or `permanent`). Only a pre-existing approved skip suppresses compilation. A newly introduced skip marker emits `FAIL_NEW_SKIP_MARKER_INTRODUCED`, stays fail-level, and blocks completion. An unallowlisted marker emits `SAMPLE_SKIP_NOT_ALLOWLISTED`, and the validator still compiles the sample so unresolved compile failures remain visible. ## Completion Repair Loop Do not stop at namespace pages, extension-member tables, or a first-pass documentation edit. 1. Run `docfx.cs --json` (fast, no-build) after edits and read the remaining diagnostics. 2. Treat every missing, placeholder, reflection-only, target-use, extension-invocation, duplicate-UID, example-lead, advanced-example-lead, family-anchor, symbol-ownership, namespace-prose, extension-table, availability, interim-artifact, sample-structure, and overwrite-layout diagnostic as blocking follow-up work. 3. For repo-wide or other full authoring runs, if no reflection-backed packet manifest is active yet, run `docfx.cs --build-api-model --project-manifest ` and use that packet set as the bounded queue before writing more examples. If build-backed packet discovery remains unusable, fall back to sequential assessment work queue or namespace-first order instead of stopping. 4. For repo-wide or other full authoring runs, clear namespace-layer diagnostics across the active queue first: missing namespace pages, namespace prose/usage/start-here repairs, availability/related-link orientation, embedded-overwrite cleanup, `Extension Members` tables, and overwrite-layout prerequisites. When a namespace page improperly hosts type/member examples, move that content into readable type-targeted files as part of the namespace repair. 5. Once the namespace layer is globally clean or the fast rerun shows only example-driven work remains, create or update type-targeting overwrite files under `.docfx/api/types/` for missing public concrete-type examples. 6. For each missing extension-method example, document it on the declaring extension class page or another readable type-targeted overwrite file under `.docfx/api/types/`, and explicitly demonstrate the method call. Do not append secondary `uid:` / `example:` blocks to the namespace page. 7. Treat the next `EXAMPLE_MISSING` diagnostic as the current task. Read the target's public API surface and one relevant test or usage source, write a consumer-facing example to the correct type-targeted overwrite file, rerun the fast validator, then move to the next diagnostic. 8. Use small internal batches (for example 3-5 examples) only to decide when to rerun the fast validator. After each rerun, continue immediately with the next batch. A batch boundary is never permission to emit a progress report, completion summary, or stop menu while diagnostics remain. 9. In any continuation response after a rerun, explicitly state all three of these items: (a) the active queue source — reflection-backed packet manifest, or sequential assessment-work-queue / namespace-first order if the manifest is still unusable; (b) the fast rerun cadence — `docfx.cs --json` after each small batch; and (c) the eventual endgame command `docfx.cs --build-api-model --validate-samples --verify-docfx- …(truncated)