AyCode.Core/.github/skills/docs-check/SKILL.md

name	description	compatibility	metadata
docs-check	Evaluate loaded `.md` documentation at the end of every code-modifying response — detect drift vs code, missing topic coverage, csproj-glob registration gaps for new `.md` files, and new issue/TODO candidates. Emit the `[DOCUMENTATION CHECK]` section per the protocol (or `[DOCUMENTATION CHECK] None.` when nothing to report). Use at the end of ANY response that creates, modifies, or deletes source code or documentation files. Does NOT trigger new Read/Grep — operates only on files already in LOADED_DOCS context. Read-only; never modifies files (user approves patches per Rule	Designed for Claude Code and GitHub Copilot. Invoked at the end of code-modifying responses. Uses only content already in LOADED_DOCS.	author Fullepi

docs-check

Evaluate the documentation state at the end of a code-modifying response and emit the [DOCUMENTATION CHECK] section. This skill encapsulates the former Rule #18 sub-rules (keep in sync, identify missing, topic separation, file registration, issue/TODO surfacing, ENFORCEMENT). The rule in each repo's copilot-instructions.md now points here; the full procedure lives in this file.

Before you start

Read-only. This skill MUST NOT:

• Trigger new Read / Grep / get_file / code_search calls on source content — evaluate only files already in LOADED_DOCS.
• Modify any file — all proposals surface as draft patches for user approval per the active repo's Rule #5 (EXPLICIT CONSENT FOR MODIFICATIONS).

The one allowed exception: Glob / file_search / Test-Path for metadata checks (e.g., locating the nearest .csproj in Step 4). These don't read content.

Step 1 — Triggering condition

Invoke this skill only at the end of a response that:

• Created, modified, or deleted any source code file (.cs, .csproj, .razor, .cshtml, .sln, etc.)
• Created, modified, or deleted any .md file
• Created or updated any .github/ configuration file (copilot-instructions.md, skill, LLM_PROTOCOL_DECISIONS.md, etc.)

Do NOT invoke on pure read/analysis/planning responses — the output would be None. and consume tokens unnecessarily.

Step 2 — Evaluate loaded .md for code/docs drift

For each .md file in LOADED_DOCS:

• Compare its stated rules/behaviour against the code you touched this turn.
• Flag concrete discrepancies only — "doc says X; code does Y" with quotable evidence.
• One line per mismatch.

Only use evidence from already-loaded docs and the code you modified this turn. Do NOT scan other sources.

Step 3 — Identify missing documentation (main topic docs)

During this turn, did you work with a pattern, class, or behaviour that:

• Is used frequently in the codebase
• Would likely be re-discovered by a future LLM session (wasting tokens)
• Is NOT captured anywhere in the loaded .md files

If yes, propose adding documentation to the appropriate TOPIC/README.md, or creating a new topic folder. One line per missing concept.

Related but distinct from Step 5 — Step 3 covers main topic docs (TOPIC/README.md); Step 5 covers paired companions (TOPIC_ISSUES.md / TOPIC_TODO.md).

Step 4 — File registration (new .md outside csproj glob)

For any .md file created (or proposed to be created) during this turn:

1. Identify the nearest .csproj (walk up from the file's directory).
2. Check whether the file is already covered by a glob or explicit entry:
   • <None Include="docs\**\*.md" /> — covers Pattern B docs/ folder contents
   • <None Include="**\README.md" Exclude="$(DefaultItemExcludes);docs\**" /> — covers folder-level README.md files in code directories
   • An explicit <None Include="<path>" /> entry
3. If the file is NOT covered → propose the csproj patch (narrowest appropriate glob or explicit include).

Common cases (file under docs/, folder-level README.md) are already covered cluster-wide → zero-cost skip. Surface only for unusual locations.

Do NOT apply the patch — output it in the [DOCUMENTATION CHECK] section. User approves per Rule #5.

Files missing from the csproj are invisible in Visual Studio Solution Explorer.

Step 5 — Issue / TODO surfacing (PASSIVE DETECTION & ASK FIRST)

If during code reading or modification you observed a concrete:

• Issue — bug, broken contract, inconsistent behaviour, observable edge case
• Planned work — refactor, missing feature, optimization

propose a draft entry.

Prerequisites (ALL must hold — else stay silent)

1. Companion loaded — the matching <TOPIC>_ISSUES.md or <TOPIC>_TODO.md MUST be in LOADED_DOCS. Without it, no reliable duplicate check → SKIP.
2. High confidence — you can quote the offending code line or spec inconsistency. Speculative "might be" / "could be" / "possibly" → SKIP.
3. Concrete — a developer could act on it without further clarification. Stylistic hunches ("this could be cleaner", "consider renaming") → SKIP.
4. Not duplicate — if a similar item already exists in the loaded companion, even if phrased differently → SKIP.

Draft entry format

• Proposed ID: <PREFIX>-<TOPIC>-<TYPE>-<RAND> per the workspace registries — <PREFIX> from AyCode.Core/.github/REPO_PREFIXES.md (use the active repo's prefix), <TOPIC> and <TYPE> from the active repo's references/TOPIC_CODES.md (consumer repos may host their own; otherwise fall back to AyCode.Core's canonical). Types: I (issue), T (TODO), B (bug — confirmed broken), C (critical — severity override). <RAND> = 4-character random alphanumeric [A-Z0-9]; generate then verify uniqueness against the topic's active companion + year-bucketed archive files; regenerate on rare collision (~1.7M-combination space per <PREFIX>-<TOPIC>-<TYPE> triple). Marked [tentative] since the user verifies prefix/topic choices at apply-time.
• Priority: P1 (high) / P2 (important) / P3 (nice-to-have). Note: C type already implies emergency; priority is still stated for precision.
• Rationale: 1-2 sentences. What's wrong or what's planned.
• Affected: file/class/method reference (with line number if known)
• Sub-category (optional): if the entry relates to a known sub-area (e.g., SignalR protocol, logger DI factory), state in body header: ## ACCORE-SIG-I-K7M2 [PROTO]: .... Do NOT encode sub-category in the ID itself — ID stays flat.

Topic code selection:

• Pick from the active repo's registry (<repo>/.github/skills/docs-check/references/TOPIC_CODES.md if the repo has one, otherwise fall back to AyCode.Core's canonical at AyCode.Core/.github/skills/docs-check/references/TOPIC_CODES.md) — the registry is the authoritative list of topic codes and type codes; this skill does not hardcode them.
• Topic codes need NOT be globally unique across repos — the <PREFIX> component (per REPO_PREFIXES.md) disambiguates. The framework's ACCORE-LOG topic and any other repo's own LOG topic (scoped to that repo's prefix) can coexist as separate logger topics — the prefix differentiates.
• If the observation spans ≥2 topics within the same repo → use that repo's XCUT topic code (see the XCUT row in the relevant TOPIC_CODES.md for its "Docs location"), with short cross-refs from each affected topic's file. Cross-repo XCUT (spanning topics across multiple repos) is a separate case — currently not formalized; surface as a question if encountered.
• If a new topic is needed → surface a proposal ("suggest new topic code NEWTOPIC in <active-repo>'s TOPIC_CODES.md — reason: ...") in the output, do NOT auto-assign. User adds via Decision Log entry (LLMP-DEC-N) + registry update per TOPIC_CODES.md Registry maintenance workflow.

Volume cap

Maximum 3 surfaced items per response. If more candidates exist, triage for highest-confidence + highest-impact. Noise cost > marginal insight.

Negative examples (do NOT surface)

• "This variable could have a better name" — stylistic, skip.
• "This might have a race condition if ..." — speculative, skip.
• "Consider refactoring the whole class to use a strategy pattern" — vague, not actionable without clarification.

Step 6 — Status update on close

If code changes in this response close a concrete entry that IS listed in a loaded <TOPIC>_ISSUES.md or <TOPIC>_TODO.md:

• Surface a suggestion to mark that entry Status: Closed (YYYY-MM-DD) with a ### Resolution sub-section (per references/TOPIC_CODES.md Status field conventions). Include commit / ADR / PR reference in the Resolution body.
• Same prerequisites + cap apply.
• Counts against the 3-item cap in Step 5.

Example surface: LOGGING_ISSUES.md#accore-log-i-k7m2 → mark Status: Closed (NopLogWriter ctor signature fixed in this response; add ### Resolution with commit ref).

Step 7 — Emit the [DOCUMENTATION CHECK] section

Collect findings from Steps 2-6. Emit at the end of the response (after the main answer content):

If any findings exist

[DOCUMENTATION CHECK]

**Drift / missing concepts** (if any):
- [concrete statement of what doc says vs what code does]

**New .md files needing csproj registration** (if any):
- `<file path>` → needs `<proposed csproj patch>`

**Issue / TODO draft entries** (capped at 3):
- `[tentative: <PREFIX>-<TOPIC>-<TYPE>-<RAND>]` [P1/P2/P3] [rationale] — [affected file:line]

**Status: FIXED suggestions** (if any):
- `<file>#<id>` → mark FIXED (fix in <context>)

Apply which, if any?

Omit sub-sections that have no content for this turn — keep the output minimal.

If NO findings

Emit the one-liner:

[DOCUMENTATION CHECK] None.

No prose padding. No "I checked X, Y, Z and everything looked fine" — just the line.

Edge cases

• No .md files in LOADED_DOCS — Steps 2 and 5 fall through (no context to evaluate). Step 4 still runs if any .md was created. Output usually None..
• Companion _ISSUES.md / _TODO.md not loaded — Step 5 SKIPS surfacing for that topic. Do NOT load it during docs-check (this skill is read-only on loaded context).
• Massive code modification — if the response refactored 20+ files, stay focused: Step 5's 3-item cap applies strictly. Report the most important; note in output if triage was needed (e.g., "12 additional minor observations suppressed per volume cap").
• Response created 5 new .md files — Step 4 reports all registration gaps (not capped, unlike Step 5).
• Skill invoked on pure-analysis response — Step 1 says: do NOT invoke. If already triggered, output None. and move on.
• Ambiguous duplicate match — if unsure whether an observation is already covered by an existing entry, default to SKIP. Silence beats noise.

Do NOT

• Trigger new Read / Grep / code_search on source content — this is a review skill, not a search skill.
• Apply any patches — surface as proposals. User approves per Rule #5.
• Generate verbose prose — output is telegraphic: bullet lists, one-line-per-item.
• Fire on every response — only at the end of code-modifying responses (Step 1).
• Surface low-confidence hunches — prerequisites in Step 5 are strict.
• Assign IDs to draft issue/TODO entries — the user assigns at apply-time.

Tool usage

This skill is tool-neutral and mostly read-only:

• Reading LOADED_DOCS list — implicit (conversation context)
• Verifying .csproj path — Glob / file_search / Test-Path (metadata only, no content)
• Output generation — normal response text

Explicitly forbidden: get_file / Read for content inspection during this skill, Grep / code_search for patterns during this skill.