V0.7.0/dotnet docfx digest

[gimlichael]

This pull request introduces the new dotnet-docfx-digest skill 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-digest Skill:

• Introduced the dotnet-docfx-digest skill, 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 in README.md, explaining its design and workflow. [1] [2] [3] [4]

Documentation and Evaluation Enhancements:

• Added a new reference document skills/dotnet-docfx-digest/references/docfx-overwrite-files.md that provides detailed guidance on DocFX overwrite files, including model structure, usage, and best practices for agents and maintainers.
• Created a comprehensive set of evaluation scenarios in skills/dotnet-docfx-digest/evals/evals.json to 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:

• Updated AGENTS.md to 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.

[greptile-apps]

Greptile Summary

This PR introduces the dotnet-docfx-digest skill for managing and verifying .NET DocFX API documentation, adds repository-wide Markdown formatting and completion-gate rules to AGENTS.md, and updates the dotnet-new-lib-slnx scaffold template to align with the new overwrite-layout conventions.

• New dotnet-docfx-digest skill: deterministic .NET 10 file-based scripts (agents.cs, docfx.cs), a SKILL.md covering the full audit/verification workflow with a machine-readable completion contract, three reference files, and 30 evaluation scenarios — all wired into CI through two new PowerShell regression suites.
• dotnet-new-lib-slnx docfx.json updated: build.overwrite now lists both api/namespaces/**/*.md and api/types/**/*.md, and both trees are excluded from build.content, keeping the scaffold template consistent with the new skill's enforced overwrite layout.
• Repository standards tightened: AGENTS.md gains the Markdown Formatting rule (natural paragraph flow, no fixed-width breaks) and the Blocking Completion Gates section, with the corresponding guidance paragraphs added to README.md.

Confidence Score: 5/5

Safe to merge — all changes are additive (new skill, new tests, documentation updates) and the CI regression suites exercise the new scripts end-to-end in isolated temp workspaces.

The new skill adds substantial tooling but the changes are fully additive: no existing skills, workflows, or scaffolds are broken, the two new CI regression scripts run in temp workspaces, the dotnet-new-lib-slnx docfx.json template change is a deliberate layout alignment, and the AGENTS.md/README.md updates are documentation only. The only findings are a minor eval-ID ordering gap and an injected verification command that hardcodes a fallback path without mentioning the installed-path alternative — neither affects runtime correctness.

skills/dotnet-docfx-digest/evals/evals.json (IDs 17 and 18 are swapped) and skills/dotnet-docfx-digest/scripts/agents.cs (hardcoded verification path in injected AGENTS.md content).

Important Files Changed

Filename	Overview
skills/dotnet-docfx-digest/SKILL.md	New skill definition — well-structured with progressive disclosure, correct YAML frontmatter, and comprehensive workflow/completion-contract guidance throughout.
skills/dotnet-docfx-digest/scripts/agents.cs	ManagedBlock now correctly targets .docfx/api/types/{TypeUid}.md and uses the proper build.overwrite globs; the hardcoded skills/dotnet-docfx-digest/scripts/docfx.cs fallback in the injected verification command may be confusing in repos where the skill is globally installed.
skills/dotnet-docfx-digest/scripts/test-quality.ps1	Comprehensive regression suite covering semantic quality diagnostics (placeholder, reflection-only, forwarding scaffold, template repetition, namespace prose), discovery correctness, shared extension fingerprints, and prose-repetition detection — all run in isolated temp workspaces.
skills/dotnet-docfx-digest/scripts/test-project-scoped.ps1	Thorough scenario coverage for dry-run selection, scoped hints, ambiguous projects, dirty-skip fallthrough, family exemptions, manifest determinism, resume/review-gate flow, overwrite-writer safety, and stdout/stderr separation — all well-isolated in temp workspaces.
skills/dotnet-docfx-digest/evals/evals.json	30 evaluation scenarios with strong coverage of public/private boundaries, overwrite layout, changed-only scoping, and idempotency; evals 17 and 18 appear out of their natural numeric order in the JSON array.
.github/workflows/validate-skill-templates.yml	Adds a DocFX CLI install step before the validator runs; correctly handles the already-installed case with update, appends the tool path to GITHUB_PATH, and verifies via docfx --version.
skills/dotnet-new-lib-slnx/assets/library/.docfx/docfx.json	Updated to include both api/namespaces/**/*.md and api/types/**/*.md under build.overwrite and exclude both from build.content, bringing the scaffold template into alignment with the new dotnet-docfx-digest conventions.
AGENTS.md	Adds Markdown Formatting rule (natural paragraph flow), Blocking Completion Gates section, and a SHA-256 hash-identity verification shortcut — all clear and well-scoped.
scripts/validate-skill-templates.ps1	Two new validation result entries delegate to the new test-quality.ps1 and test-project-scoped.ps1 scripts and correctly surface non-zero exit codes as failures.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Agent triggers dotnet-docfx-digest] --> B[scripts/agents.cs\nInjects managed block → AGENTS.md]
    B --> C[scripts/docfx.cs --json\nFast validation: prose, layout,\nnamespace pages, extension tables]
    C --> D{Diagnostics?}
    D -- Yes --> E[Repair loop\nFix EXAMPLE_MISSING /\nnamespace prose / overwrite layout]
    E --> C
    D -- No, remainingWorkItems=0 --> F[Build-backed verification\n--build-api-model\n--validate-samples\n--verify-docfx-build]
    F --> G{summary.canClaimCompletion?}
    G -- false --> E
    G -- true --> H[Completion\nDeterministic exit code + --json report]

    subgraph CI [GitHub Actions]
        I[validate-skill-templates.yml] --> J[Install DocFX CLI]
        J --> K[validate-skill-templates.ps1]
        K --> L[test-quality.ps1\nSemantic quality regressions]
        K --> M[test-project-scoped.ps1\nDry-run, manifest, overwrite-writer regressions]
    end

Loading

_{Reviews (17): Last reviewed commit: "💬 update readme for assessment-queue ch..." | Re-trigger Greptile}