V0.7.0/dotnet docfx digest#22
Merged
Merged
Conversation
Introduce new docfx documentation skill for validating and maintaining .NET public API documentation. Includes SKILL.md definition, bundled scripts for DocFX maintenance and compilation validation, evals for testing, and references for overwrite file guidance.
Add install command, skill table entry, and 'Why docfx-digest' motivation section to README explaining the skill's approach to preventing API documentation rot through deterministic tooling.
Enhance the skill to require explicit examples in DocFX overwrite content for concrete public types and public extension methods, not just namespace pages or extension tables. Updates SKILL.md guidance and checklists, adds a new eval test case for the examples requirement, strengthens script documentation (agents.cs and docfx.cs to validate and report EXAMPLE_MISSING diagnostics), and clarifies overwrite-file usage patterns. Concrete types and extension methods now must have copy/paste-ready examples derived from tests or actual behavior.
Refine dotnet-docfx-digest skill documentation to emphasize that public non-abstraction type examples must be placed on the generated type-page/overwrite section, not only on namespace overview pages. Updates SKILL.md guidance, evals expectations, reference documentation, and helper script docs to consistently clarify this requirement.
Rename IsConcreteDocumentableType to IsExampleRequiredType and ConcreteTargets to RequiredExampleTargets throughout the validator. Simplify the type classification logic by removing specialized checks for enums, value types, attributes, and delegates, keeping only the core distinction: interfaces and abstractions do not require examples. Updates summary reporting and error messages to use clearer terminology.
Add section to AGENTS.md clarifying that all markdown files in the repository must use natural paragraph flow without artificial column-width breaks or hard-wrapped mid-sentence content. This improves readability across devices, eases maintenance, and produces cleaner git diffs.
Update README.md dotnet-docfx-digest section to reflect refined guidance: public non-abstraction types now require examples on the generated type page/overwrite section, not just on namespace pages. Clarifies that type-page examples are mandatory and distinct from namespace overview documentation.
Add --verify-docfx-build flag to docfx.cs script so generated API YAML, manifests, and configured site output stay outside the working tree. Updates SKILL.md instructions and verification checklist to run DocFX CLI in a temporary copy of the repository. Updates evals and supporting documentation to reflect the new verification workflow.
Reflect the new --verify-docfx-build capability that runs the DocFX CLI in a temporary repository copy, keeping generated metadata and site output outside the working tree.
Greptile SummaryThis PR introduces the
Confidence Score: 5/5Safe to merge — all changes are additive skill and documentation artifacts with no runtime or data-path mutations. The skill and its scripts are new, documentation-only tooling. The two concerns raised (SKILL.md word density and unpinned DocFX in CI) are maintenance observations that do not affect correctness, security, or existing functionality. The fixes previously flagged — the skills/dotnet-docfx-digest/SKILL.md warrants a future pass to trim content into references/workflow.md once the skill stabilizes. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A([Agent triggers dotnet-docfx-digest]) --> B[Run agents.cs\nInject managed block → AGENTS.md]
B --> C[Run docfx.cs --json\nFast: no build, no network]
C --> D{Diagnostics\nremaining?}
D -- Yes --> E[Repair batch\nnamespace/table/example/lead]
E --> C
D -- No --> F[Run docfx.cs\n--build-api-model\n--validate-samples\n--verify-docfx-build]
F --> G{completion contract\nclean?}
G -- No --> E
G -- Yes --> H([Claim completion])
subgraph "Fast path (always-on)"
C
D
E
end
subgraph "Build-backed gate (opt-in, required for completion)"
F
G
end
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A([Agent triggers dotnet-docfx-digest]) --> B[Run agents.cs\nInject managed block → AGENTS.md]
B --> C[Run docfx.cs --json\nFast: no build, no network]
C --> D{Diagnostics\nremaining?}
D -- Yes --> E[Repair batch\nnamespace/table/example/lead]
E --> C
D -- No --> F[Run docfx.cs\n--build-api-model\n--validate-samples\n--verify-docfx-build]
F --> G{completion contract\nclean?}
G -- No --> E
G -- Yes --> H([Claim completion])
subgraph "Fast path (always-on)"
C
D
E
end
subgraph "Build-backed gate (opt-in, required for completion)"
F
G
end
Reviews (25): Last reviewed commit: "📝 clarify full docfx verification gates..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Update dotnet-docfx-digest to create separate per-type DocFX overwrite files (e.g. .docfx/api/TypeUid.md) instead of namespace-only files. Modifies SKILL.md workflow steps, adds framework-aware MetadataLoadContext dependency resolution to scripts/docfx.cs, and validates that build.overwrite includes per-type files. Updates evals and reference documentation to reflect the new per-type overwrite strategy.
Reflect the per-type DocFX overwrite file support in dotnet-docfx-digest. Updates the skill description to mention framework-aware metadata resolution, per-type overwrite files, and the requirement that build.overwrite includes those files.
Move detailed script CLI documentation from scripts/README.md to references/scripts.md following progressive disclosure and Anthropic skill authoring conventions. Updates SKILL.md to reference the new location. Reorganizes skill sections, clarifies scope and principles, and updates evals to match the new structure. Includes enhanced docfx.cs with improved diagnostics and JSON output.
Reflect the restructured skill documentation and enhanced script capabilities in the README available skills table.
…ge checks Add deterministic repair-plan generation for noisy audits, namespace coverage validation to audit related sibling namespace pages consistently, cleanup boundary rules to preserve authored Markdown, and example inventory tracking. Update workflow steps to integrate repair-plan reading and namespace auditing before editing. Add three new test cases for repair-plan usage, cleanup preservation, and namespace family consistency.
Implement --repair-plan argument to generate deterministic Markdown work queues from validation diagnostics. Groups repository guidance failures, namespace repairs, extension-table fixes, required-example inventory, sample failures, and other errors with completion gates that prevent broad restore/checkout commands and preserve authored Markdown. Limits cleanup to known generated metadata files and safe output directories. Uses temp workspace for DocFX verification to avoid git status pollution.
Update README.md skill table description to document new repair-plan capability for converting noisy validation output into grouped work queues, deterministic cleanup boundary rules that preserve authored Markdown, and cleanup gates that prevent accidental documentation loss. Highlight temp-workspace verification with --verify-docfx-build to keep git status clean.
Add explicit 'Safety Gates' section that captures git status before editing, protects uncommitted documentation changes, and forbids broad restore/recovery commands. Integrate safety gates into both named-API and repo-wide audit workflows as first step. Add git diff verification before final completion. Expand execution gates in repair plan to require cleanup candidates be listed before deletion, preserve existing documentation changes, audit related namespace pages together, and verify diffs are intentional. Update test expectations to validate all safety checks.
Expand skill description to include no-broad-restore rules, cleanup-path listing requirements, related-namespace coverage validation, and git diff review completion checks in the repair-plan feature summary.
Explicitly document that agents.cs and docfx.cs are resolved from the loaded skill directory, with a fallback to repo-managed source when the skill directory is unavailable. Update all script invocation examples to use placeholder paths (<resolved-skill-dir> and <repo-root>) and clarify that repo-root must point to the actual target repository being documented. Add test case for script resolution when skill is installed globally and target repo doesn't vendor the scripts. Update reference documentation with script path resolution guidance.
Extend docfx verification to handle Codebelt repositories where the root .snk file is not present locally by automatically using -p:SkipSignAssembly=true during build, test, and DocFX verification. Updates skill instructions, evals, reference docs, and scripts to implement and document this behavior.
Explain to repository users that the dotnet-docfx-digest skill now supports strong-name signed repositories without requiring a local .snk file by automatically using -p:SkipSignAssembly=true when verification runs.
Introduce iterative repair pattern after per-type example and overwrite edits. Agents must rerun docfx.cs --json after modifications and fix remaining EXAMPLE_MISSING and overwrite inclusion diagnostics before completion, instead of listing them as final findings. Updates skill instructions, evals, and README to document and test this mandatory loop.
Enhance EXAMPLE_MISSING diagnostics with expected overwrite file paths and clearer guidance. Introduce AppendRequiredExampleDiagnostics() to render a formatted table showing namespace, expected location, and required action. Update docfx.cs to pass docfxWorkspace context for accurate path resolution. Revise skill instructions and evals to match improved diagnostic output and reporting format.
Add SAMPLE_SKIP_REASON_INSUFFICIENT diagnostic to catch weak skip reasons that are documentation work rather than true compilation blockers. Implement IsInsufficientSkipReason() to detect patterns like 'requires package', 'shows framework pattern', or 'full example demonstrates X'. Clarify in skill docs that extension-method examples belong on declaring class or namespace pages, not method-UID filenames. Update error inventory and evaluation tests.
Refactor DiscoverMarkdown() to parse docfx.json and enumerate Markdown files from configured build.content and build.overwrite inputs instead of blindly scanning the workspace. Prevents unrelated repository Markdown (README.md, CHANGELOG.md) from being treated as DocFX overwrite content. Add PathsEqual() helper for consistent path comparison. Update namespace-page validation to trigger revalidation when docfx.json changes. Add DOCFX_MARKDOWN_DISCOVERY_SKIPPED warning when config has no inputs and docfx.json is at repo root. Include two new evaluation test cases for configuration-aware discovery behavior.
Clarified DocFX YAML front matter requirements and property mappings for type examples and extension-method examples. Added explicit guidance on using the \�xample\ property array and prohibited hash-suffix filenames in overwrite file paths. Improved inline documentation to prevent template and API member suppression when using managed reference pages.
Add support for public static classes as valid non-abstraction documentation targets in docfx.cs, even when they are not extension containers. Update README.md to reflect this capability. Add comprehensive eval tests for dotnet-docfx-digest skill and introduce test-quality.ps1 for documentation quality verification workflows.
The DocfxValidator source scanner now surffaces public delegate types as required example targets, including generic delegates with variance modifiers. Also tightens extension method detection to only surface 'public static' extension methods, filtering out private/internal static helpers with 'this' parameters that are implementation details and not part of the documented public API surface.
Two new regression scenarios validate that the DocfxValidator correctly surfaces public delegate types (plain, generic, and variance-annotated) as required example targets, and that extension method detection properly filters to only 'public static' methods while excluding private/internal static helpers. Both scenarios verify that clean type pages are recognized as known deliverables without triggering INTERIM_ARTIFACT_IN_WORKTREE.
Updates SKILL.md to clarify the extension method detection improvements, adds a new regression test case (eval 104) in evals.json to verify that invented or stale extension method names are rejected with EXTENSION_METHOD_UNKNOWN diagnostics, and expands references/scripts.md with detailed documentation of the detection logic and validation rules.
Documents the extension method validation improvements in the README.md feature summary. Clarifies that extension method names are now verified against actual source and generated metadata, preventing invented or stale method names such as AddCuemonTextJson from appearing in namespace prose and extension member tables.
Adds validation logic to detect when Extension Members tables list invented or stale extension method names. Builds a globalExtensionMethodBaseNames set from all namespaces and validates each table entry against both namespace-specific and global extension method names, reporting EXTENSION_METHOD_UNKNOWN diagnostic for any methods that exist neither in the current namespace nor in any other documented namespace.
Adds a regression test scenario (inventedExtension) that verifies the validator detects invented extension method names in Extension Members tables. The scenario includes a namespace with only AddMinimalJsonOptions in source but a table listing both AddCuemonTextJson and AddMinimalJsonOptions, validates that EXTENSION_METHOD_UNKNOWN diagnostic is reported, then verifies that removing the invented method name resolves the diagnostic.
Clarifies SKILL.md instructions to distinguish between mechanical start-here templates and genuine choice-guidance prose. Start-here patterns are now reserved for namespaces with multiple plausible entry points; single-entry namespaces should describe the direct action and outcome instead of slot-fill sentences. Adds eval case 105 to verify agents recognize source-backed method names can still be poor prose when wrapped in formulaic guidance.
Documents the namespace prose guidance improvements in the dotnet-docfx-digest feature list. Clarifies that start-here patterns should be reserved for namespaces with multiple entry points, while single-entry namespaces should describe direct action and outcome instead of formulaic prose templates.
Adds ValidateExampleNarrative to detect examples that lack meaningful prose before the code fence. Flags bare code without human context (EXAMPLE_LEAD_MISSING) and advanced multi-block examples with shallow lead paragraphs (EXAMPLE_ADVANCED_LEAD_MISSING). Includes regression tests for both leadless and undersized-lead scenarios.
Updates SKILL.md to document the example narrative validation requirements. Adds eval cases to verify that agents catch bare-code examples and advanced setups with insufficiently detailed lead paragraphs. Example leads must explain the consumer task and expected outcome; advanced examples require deeper context about setup or workflow.
Expands workflow.md and scripts.md to document the example lead narrative validation logic. Explains the detection rules: leads must have at least 8 meaningful words and not be placeholder prose; advanced examples (multi-block, 35+ lines, complex patterns) require deeper contextual explanation beyond a thin one-liner.
Documents the new example narrative validation capability in the dotnet-docfx-digest feature list. Emphasizes that meaningful lead paragraphs before code fences improve developer experience and ensure examples are properly contextualized rather than presented as bare code.
Updates SKILL.md to clarify the completion contract: diagnostics such as EXAMPLE_LEAD_MISSING, EXAMPLE_ADVANCED_LEAD_MISSING, FAMILY_ANCHOR_EXAMPLE_MISSING, SAMPLE_STRUCTURE_INVALID, and INTERIM_ARTIFACT_IN_WORKTREE are blocking repair items, not optional quality backlog. Adds eval case 106 to verify agents refuse the quality-backlog escape hatch and continue working the queue until completion. Expands workflow.md with completion contract enforcement details.
Adds explicit guidance to the validator output clarifying that EXAMPLE_LEAD_MISSING, EXAMPLE_ADVANCED_LEAD_MISSING, FAMILY_ANCHOR_EXAMPLE_MISSING, SAMPLE_STRUCTURE_INVALID, and INTERIM_ARTIFACT_IN_WORKTREE are blocking repair items, not optional quality backlog. Updates the example diagnostic checklist to include lead, advanced-lead, and family-anchor categories in the final completion verification step.
Documents the completion contract enforcement capability in the dotnet-docfx-digest feature list. Clarifies that the validator enforces a binary completion state and refuses to claim the audit is complete while blocking repair items remain unresolved, ensuring that diagnostic queues are worked through to completion rather than deferred as optional backlog.
Converts SYMBOL_COLLISION_UNRESOLVED and EXTENSION_OWNER_AMBIGUOUS from warnings to blocking errors. Makes ownership validation scope-aware by filtering RequiredExampleTargets through the current scope plan. Adds HasExactUidExample and HasExactOwnerReceiverExample helpers to verify that exact-UID examples or receiver-style ownership examples exist for all unresolved collision targets. Updates test scenarios to verify diagnostics are errors, not warnings.
Updates SKILL.md to document scope-aware ownership validation: exact-UID examples and receiver-style examples are required to resolve cross-assembly collisions. Adds eval case 107 to verify that agents prioritize blocking ownership diagnostics and do not defer them as optional quality work. Expands scripts.md and workflow.md with scope-aware validation logic details.
Adds dotnet-docfx-digest feature description to README.md: Scope-aware ownership validation now blocks on exact-UID and receiver-style examples for cross-assembly type name and extension container collisions. This ensures unambiguous API documentation coverage across projects.
Add comprehensive guidance for selecting the executable test framework from the asset containing a conditionally compiled API. Covers NETSTANDARD2_0, modern asset variants, and framework selection rules. Includes new eval case 108 and extended reference documentation for the docfx.cs and agents.cs scripts.
Document the new asset-aware conditional API validation capability for the dotnet-docfx-digest skill. Explains framework selection rules for NETSTANDARD2_0 and modern asset variants.
Implement skip-compile-allowlist.json feature allowing documented, pre-approved skip markers for samples with legitimate external dependencies. Includes allowlist matching logic, UID/symbol tracking, pre-existing vs newly introduced marker distinction, and comprehensive test coverage demonstrating approved entries with reasons, approval dates, and lifetimes.
Update SKILL.md with escape hatch marker approval workflow and enforcement rules. Add eval cases 109 and 110 verifying proper allowlist entry matching and pre-existing marker tracking. Extend workflow.md and scripts.md with allowlist format specification, entry structure (diagnosticCode, filePath, UID, reason, approval, lifetime), and validation sequence.
Document the new escape hatch markers capability in the dotnet-docfx-digest feature list. Explains pre-approved skip-compile-allowlist.json support for documented external dependencies with approval workflow and lifetime tracking.
Add Context Exhaustion Protocol section to SKILL.md clarifying that context pressure is not a completion condition. Prevent handoff via context size, session length, task size, or 'better for a follow-up' when work remains. Strengthen README completion-gate contract and agent guidance against premature context-based handoffs. Add eval case 111 verifying agents reject invalid context-pressure stop reasons and continue with smaller batches or state regeneration. Updates workflow.md and agents.cs with protocol details.
Update AGENTS.md and README.md to explicitly document that the full docfx.cs verification command includes --build-api-model --validate-samples --verify-docfx-build, not just --verify-docfx-build alone. Clarifies that sample compilation is a required part of the completion gate and cannot be skipped.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces the new
dotnet-docfx-digestskill for managing and verifying .NET DocFX API documentation, updates repository documentation standards, and adds comprehensive references and evaluation scenarios to ensure robust documentation workflows. The most important changes are summarized below.Addition of the
dotnet-docfx-digestSkill:dotnet-docfx-digestskill, which automates the creation, auditing, and verification of DocFX documentation for .NET public APIs. It includes deterministic .NET 10 scripts for maintaining documentation, verifying examples, and ensuring only public APIs are documented. The skill is now listed in the install commands, skills table, and has a dedicated "Why" section inREADME.md, explaining its design and workflow. [1] [2] [3] [4]Documentation and Evaluation Enhancements:
skills/dotnet-docfx-digest/references/docfx-overwrite-files.mdthat provides detailed guidance on DocFX overwrite files, including model structure, usage, and best practices for agents and maintainers.skills/dotnet-docfx-digest/evals/evals.jsonto test the skill’s behavior in practical documentation update and verification situations, ensuring it handles public/private API boundaries, preserves manual edits, and verifies documentation deterministically.Repository Documentation Standards:
AGENTS.mdto require natural paragraph flow in all markdown files, prohibiting artificial line breaks within sentences for improved readability and maintainability.These changes collectively improve the repository's documentation quality, enforce deterministic and verifiable DocFX workflows, and provide clear guidance and evaluation for maintaining .NET API docs.