# Spec Doc Linter

> Spec Doc Linter

- Skill: `liyown/spec-doc-linter` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add liyown/spec-doc-linter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liyown/spec-doc-linter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: liyown (https://skillmd.com/u/liyown)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/liyown/spec-doc-linter

---


# Spec Doc Linter

Sync two project-local doc conventions with the code they describe. Detect drift, propose a per-file patch, write only after per-file y/n/q confirmation.

## Required Loading

Always load:

- `prompts/linter.md` — core protocol: doc conventions, drift catalog, sentinel.
- `prompts/drift-checks.md` — Tier-1 static rules (extendable; one block per A.N).
- `prompts/semantic-review.md` — Tier-2 LLM-judgment rubric for Class B modes.
- `prompts/confirmation.md` — per-file diff display + y/n/q contract.

## When To Run

- After a non-trivial merge, before opening a PR.
- When the user says the spec or CONTEXT feels stale.
- When a module's DevAgent.md or a domain's CONTEXT.md was last touched months ago and the module's code has churned since.

## Two Doc Conventions This Skill Teaches

- `DevAgent.md` lives at a module's root (e.g. `src/main/java/com/example/order/DevAgent.md`). Sections (in order): `## Overview`, `## Public API`, `## Invariants`, `## Anti-patterns`, `## Dependencies`, `## File Map`.
- `CONTEXT.md` lives at a domain folder's root (e.g. `domains/billing/CONTEXT.md`). Sections (in order): `## Bounded Context`, `## Owns`, `## Does Not Own`, `## Upstream Contexts`, `## Downstream Contexts`, `## Critical Invariants`.

A doc that is missing a required section is itself a drift finding (mode `STRUCT-MISSING-SECTION`).

`prompts/linter.md` defines the canonical section lists and parsing rules.

## Output Contract

- If no drift is found, output exactly the sentinel:
  `未发现文档与代码漂移。`
- When drift is found, output a drift report grouped by file; each finding carries `file:line`, drift-mode id, evidence, suggested fix. See the canonical sample in `examples/linter-output.md`.
- Mutations are gated by `prompts/confirmation.md`. No `--fix-all` flag: every file is a separate y/n/q prompt.

## Examples

Each `bad-*` doc has a matching `good-*` in `examples/` showing the minimum sync. Read them side by side to calibrate drift severity. The canonical "what the agent should emit" sample ships as `examples/linter-output.md`.