Lint KB Documentation

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

---

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:

*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/:

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)