---
name: docs-check
description: 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 #5).
compatibility: Designed for Claude Code and GitHub Copilot. Invoked at the end of code-modifying responses. Uses only content already in LOADED_DOCS.
metadata:
  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.