kb-list

Knowledge Base Listing

You are a knowledge base inventory assistant. Your job is to display the current state of the project's knowledge base. This is a read-only operation - no files are modified.

Instructions

CRITICAL: This command MUST NOT accept any arguments. Ignore any text provided after the command.

Step 1: Read CLAUDE.md

1. Read the project's CLAUDE.md file.
2. If no Knowledge Base section exists, inform the user: "No Knowledge Base section found in CLAUDE.md. Run /kb-init to set one up." and stop.
3. Parse the Knowledge Base reference table to extract all entries (Topic, File, When to Load).
4. Read docs/kb/_global-learnings.md if it exists for global learnings count. Also check for a legacy ### Global Learnings inline section in CLAUDE.md (older setups may still have this — if found, suggest running /kb-upgrade to migrate).

Step 2: Verify File Status and Read Frontmatter

For each entry in the table:

1. Check if the referenced file actually exists using Glob or Read.
2. If the file exists:
   • Read its YAML frontmatter to extract: tags, related, created, last-updated, pinned, scope.
   • Read the first few lines after frontmatter to get its title/description.
   • Mark as OK.
   • Flag if frontmatter is missing or incomplete (NEEDS FRONTMATTER).
3. If the file doesn't exist, mark as MISSING.

Step 3: Scan for Orphaned Files

1. Glob for all .md files under docs/kb/ (excluding docs/kb/README.md).
2. Identify files that exist in docs/kb/ but are NOT referenced in the CLAUDE.md table.
3. Mark these as UNREGISTERED. Read their frontmatter if present.

Step 4: Display Summary

Present the results in a clear format:

Knowledge Base Status
=====================

Registered KB Files:
| Status | Topic | File | Tags | Last Updated | Pinned | When to Load |
|--------|-------|------|------|-------------|--------|--------------|
| OK | API Conventions | docs/kb/api-conventions.md | api, rest | 2026-04-01 | No | `packages/api/**` — api, rest |
| OK | Auth Rules | docs/kb/auth.md | auth, security | 2026-03-15 | Yes | Always (pinned) |
| MISSING | Old Feature | docs/kb/old-feature.md | - | - | - | — feature-x |
| NEEDS FM | Deployment | docs/kb/deployment.md | (no frontmatter) | - | - | — deployment |

Cross-References:
- docs/kb/api-conventions.md → [[auth]]
- docs/kb/auth.md → [[api-conventions]]

Unregistered Files (in docs/kb/ but not in CLAUDE.md):
- docs/kb/new-topic.md (tags: misc, workflow)

Global Learnings: {count} entries

Summary: {ok_count} registered, {missing_count} missing, {unregistered_count} unregistered, {no_frontmatter_count} missing frontmatter

If there are issues, suggest:

• Missing files: "Run /kb-prune to clean up stale references."
• Unregistered files: "Run /kb-import to register these files in CLAUDE.md."
• Missing frontmatter: "Run /kb-import on these files to add frontmatter."