177 lines
12 KiB
Markdown
177 lines
12 KiB
Markdown
---
|
|
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.
|