lint-kb

验证并强制执行知识库文档格式、完整性和完整性。检查最近的文档（未提交或最近N次提交）是否符合知识库标准。检查内容： 1. 格式 - 文档遵循所需模板（标题、章节） 2. 完整性 - 工单/问题包含所有必需文件（1-5） 3. 完整性 - index.md中的所有工单、roadmap.md中的各阶段 4. 模式 - 具有状态：打开|已解决 5. 命名 - 文件遵循约定（动词-名词、feat-、comp-等）适用场景： - 在提交知识库文档前 - 创建工单/问题后 - 定期维护 - 用户说“lint知识库”、“检查文档”、“验证知识库”

SKILL.md

--- frontmatter

name: lint-kb
description: |
  Validate and enforce KB documentation formats, completeness, and integrity.
  Checks recent docs (uncommitted or last N commits) against KB standards.

  CHECKS PERFORMED:
  1. FORMAT - Documents follow required templates (headers, sections)
  2. COMPLETENESS - Tickets/issues have all required files (1-5)
  3. INTEGRITY - All tickets in index.md, phases in roadmap.md
  4. PATTERNS - Have Status: open|resolved
  5. NAMING - Files follow conventions (verb-noun, feat-, comp-, etc.)

  Use when:
  - Before committing KB docs
  - After creating tickets/issues
  - Periodic maintenance
  - User says "lint kb", "check docs", "validate kb"

Lint KB Documentation

Validate and enforce KB documentation formats, completeness, and integrity.

Prerequisites

ALWAYS run /pmc:kb first to understand KB structure and formats.

Check Modes

Mode	Scope	Command
Recent	Uncommitted + last 3 commits	`/lint-kb` (default)
Full	All KB docs	`/lint-kb full`
Tickets	Only tickets/issues	`/lint-kb tickets`

Step 1: Identify Docs to Check

use /pmc:kb first.

Recent Mode (Default)

bash

# Uncommitted changes
git status --porcelain .pmc/docs/

# Recently committed (last 3)
git log -3 --name-only --pretty=format: -- .pmc/docs/ | sort -u

Full Mode

code

Glob: .pmc/docs/**/*.md

Step 2: Ticket/Issue Completeness

Required Files

Each ticket/issue directory MUST have these files:

File	Required	Purpose
`1-definition.md`	Always	What: scope, success criteria
`2-plan.md`	Always	How: steps, decisions
`3-spec.md`	Always*	TDD: tests, edge cases
`4-progress.md`	In progress	Log: TDD cycles, notes
`5-final.md`	On completion	Done: status, learnings

*3-spec.md may be minimal for trivial tickets (TDD: no in constraints).

Check Procedure

code

Glob: .pmc/docs/tickets/T*/

For each directory:

•List files present
•Report missing required files
•Check 5-final.md has Status: COMPLETE or Status: BLOCKED

Report Format

code

## Ticket Completeness

| Ticket | 1-def | 2-plan | 3-spec | 4-prog | 5-final | Status |
|--------|-------|--------|--------|--------|---------|--------|
| T00021 | OK    | OK     | OK     | OK     | OK      | COMPLETE |
| T00022 | OK    | OK     | MISSING| -      | -       | In Progress |

Step 3: Index Integrity

Tickets Index

code

Read: .pmc/docs/tickets/index.md
Glob: .pmc/docs/tickets/T*/

Check:

•Every T*/ directory has entry in index.md
•No orphan entries (listed but directory missing)
•Format: T0000N Brief Title (one per line)

Roadmap Integrity

code

Read: .pmc/docs/3-plan/roadmap.md

Check:

•ALL active tickets appear in roadmap (single or in phase)
•Phase ticket references exist as directories
•No stale references to archived tickets

Critical: Every ticket in tickets/ (not archived) MUST be in roadmap.md - whether as a single item or within a phase.

Report Format

code

## Index Integrity

### tickets/index.md
- Missing entries: T00023, T00024
- Orphan entries: none

### 3-plan/roadmap.md
- Stale reference: T00015 (archived)
- Missing from roadmap: T00021

Step 4: Format Validation

All format requirements are in kb/references/:

Document Type	Reference	Key Requirements
PRDs	prd-format.md	Header, Overview/Scope, prefix (feat-/comp-/infra-)
SOPs	sop-format.md	Header, Steps, verb-noun filename
Patterns	pattern-format.md	Status field (open/resolved), Problem section
Code Maps	codemap-format.md	Header, Last updated, Key Files
Tickets	ticket-formats.md	All 5 docs with required sections

Read the relevant reference file to understand what to validate.

Report Format

code

## Format Validation

| File | Issue |
|------|-------|
| 4-patterns/caching.md | Missing Status field |
| 2-sop/deploy.md | Filename should be verb-noun |
| tickets/T00022/1-definition.md | Missing Scope section |

Step 5: Fix or Report

Auto-fixable Issues

Some issues can be auto-fixed:

•Add missing Status: open to patterns
•Add ticket to index.md
•Create stub files for missing ticket docs

Manual Review Required

•Format violations in existing content
•Stale roadmap references
•Incorrect naming conventions

How It Works

This is a Claude-interpreted skill (no CLI script). When invoked:

•Claude reads this SKILL.md for validation rules
•Claude performs checks using Glob/Grep/Read tools
•Claude reports issues and can fix them on request

Usage:

code

/lint-kb              # Claude performs validation, reports issues
/lint-kb fix patterns # Claude fixes specific category

Quick Checks

One-liner Integrity Check

bash

# Tickets not in index
comm -23 <(ls -1 .pmc/docs/tickets/ | grep '^T' | sort) \
         <(grep -oE 'T[0-9]+' .pmc/docs/tickets/index.md | sort)

# Patterns without Status
grep -L -i 'Status:' .pmc/docs/4-patterns/*.md

Checklist

Completeness

• All tickets have 1-definition.md
• All tickets have 2-plan.md
• All tickets have 3-spec.md (or TDD: no)
• Completed tickets have 5-final.md

Integrity

• All tickets in index.md
• ALL active tickets in roadmap.md (single or in phase)
• No stale references to archived items

Format

• PRDs have required sections
• SOPs follow verb-noun naming
• Patterns have Status field
• Code maps have Last updated
• Ticket definitions have Scope

Example Run

code

$ /lint-kb

Checking KB documentation...

## Scope
- Mode: recent (uncommitted + last 3 commits)
- Files to check: 8

## Ticket Completeness

| Ticket | Files | Status |
|--------|-------|--------|
| T00021 | 5/5   | COMPLETE |
| T00022 | 2/5   | Missing: 3-spec, 4-progress, 5-final |

## Index Integrity

tickets/index.md:
- Missing: T00022

3-plan/roadmap.md:
- OK

## Format Validation

4-patterns/new-pattern.md:
- Missing: Status field (add "Status: open" or "Status: resolved")

## Summary
- Errors: 2
- Warnings: 1
- Auto-fixable: 1 (run with --fix)