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)

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

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

Full Mode

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

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

For each directory:

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

Report Format

## 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

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

Check:

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

Roadmap Integrity

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

Check:

1. ALL active tickets appear in roadmap (single or in phase)
2. Phase ticket references exist as directories
3. 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

## 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

## 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:

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

Usage:

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

---

Quick Checks

One-liner Integrity Check

# 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

$ /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)