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:

dotnet run --file "<resolved-skill-dir>/scripts/docfx.cs" -- --repo-root "<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:

dotnet run --file "<resolved-skill-dir>/scripts/agents.cs" -- --repo-root "<repo-root>"
dotnet run --file "<resolved-skill-dir>/scripts/docfx.cs" -- --repo-root "<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:

dotnet run --file "docfx.cs" -- --repo-root "<repo-root>" --json --assessment-queue <temp-path> --search-examples

Resolve <temp-path> 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:

dotnet run --file "<resolved-skill-dir>/scripts/docfx.cs" -- --repo-root "<repo-root>" --build-api-model --project-manifest <temp-path> --json

Resolve <temp-path> 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 <temp-path> 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 <path> 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 -- <file> 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<Type> in the Type column, and keep generic method arity such as As<T> or Configure<TOptions> 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 <xref:Namespace.Type> 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 <path>; 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 <path> 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 <temp-path> (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 <temp-path>; this also emits a sibling <name>.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 <temp-path> --review-report <review-path> --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 <request.json>) 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 <temp-path>, docfx.cs --build-api-model --project-manifest <temp-path>, 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 <temp-path> 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 <docfx-workspace>/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 <temp-path> 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)