seongsu-kang/tycono/akb-linter

AKB Document Linter

"Only keep documents that AI can read and act on accurately."

Core Problem

Checks (9 items)

Category A: AI Confusion (Critical)

1. History Contamination

AI takes documents literally. Humans skip "old stuff" but AI gets confused.

BAD: "Previously we used v1, then migrated to v2"
GOOD: "Currently using v2"
(History goes to separate archive)

Keywords: previously, former, deprecated, no longer, migrated, legacy, v1

2. Placeholder/Empty Documents

Search noise. Grep matches useless files.

BAD: < 10 lines, only "TODO"/"TBD", frontmatter only
ACTION: Fill content or delete

3. Duplicate/Conflict Check

Same info in 2 places = Single Source of Truth violation.

BAD: Two docs on same topic with slightly different info
ACTION: Merge into one, or clearly separate roles (Hub vs Node)

4. Implementation Code Check

AKB = semantics (why, relationships). Code repo = implementation (how).

BAD: .py/.js/.ts/.sql files in AKB doc folders
BAD: Full function implementations in docs
GOOD: Architecture decisions, design philosophy
GOOD: Code coordinates -> "See src/web/src/components/"
 
EXCEPTIONS:
- .claude/ (infrastructure)
- src/ (source code submodule)
- Short code snippets in docs (<10 lines, for explanation)

Category B: Structure Quality (Warning)

5. TL;DR Section

• PASS: ## TL;DR exists (3-5 lines)
• WARN: Missing

6. Document Length (200-line threshold)

• PASS: <= 200 lines
• WARN: 200-300 lines (split recommended)
• FAIL: > 300 lines (split required)

7. Context Links

• PASS: Links with context in body text
• WARN: Only ## Related list (AI doesn't know why to follow)
• FAIL: No links (isolated document)

8. Filename Keywords

• PASS: competitor-analysis-openclaw.md
• WARN: analysis.md (ambiguous)
• FAIL: doc1.md, temp.md

9. Frontmatter

---
title: "..."       # Required
akb_type: hub|node # Recommended
tags: [...]        # Recommended
status: active     # Recommended
---

Severity

Core Principles

"More docs is not better"

"Only keep docs AI can act on accurately"

1. History -> archive - Current state only in active docs
2. Empty -> delete - Remove noise
3. Duplicates -> merge - Single Source of Truth
4. Links with context - Give AI reason to follow
5. Semantics vs implementation - AKB = "why", code = "how"