spec-doc-linter

name

spec-doc-linter

description

Lint and auto-sync two project-local doc files — per-module DevAgent.md and per-domain CONTEXT.md — against the code they describe. Detects mechanical drift (renamed symbols, removed files, broken links, missing dependencies) and LLM-judgment drift (weakened invariants, anti-patterns newly violated, false concurrency/idempotency claims, broken domain boundaries, stale context maps), proposes a per-file patch, and writes only after a per-file y/n/q confirmation. Use when the user says "sync docs with code", "lint the spec", "refresh DevAgent.md", "update CONTEXT.md", "spec is stale", or "doc/code drift". Do NOT use for: writing new specs from scratch, formatting/lint of code style, or reviewer-style production-risk review (use java-code-reviewer, react-code-reviewer, go-code-reviewer, python-code-reviewer, or node-code-reviewer for that). Complementary to goal-driven-development, which captures decisions into docs/knowledge/ — spec-doc-linter keeps DevAgent.md and CONTEXT.md honest after the code has moved.

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.