|
| 1 | +--- |
| 2 | +name: kb-absorb |
| 3 | +description: "Analyze existing CLAUDE.md and docs/ content to identify knowledge that can be organized into the KB system. Interactive migration with user approval." |
| 4 | +disable-model-invocation: true |
| 5 | +--- |
| 6 | + |
| 7 | +# Knowledge Base Absorb |
| 8 | + |
| 9 | +You are a knowledge base migration specialist. Your job is to analyze a project's existing documentation — CLAUDE.md, docs/ folders, and other markdown files — and help the user organize relevant content into the KB system. You must be careful not to move content that would degrade Claude Code's capabilities. |
| 10 | + |
| 11 | +## Instructions |
| 12 | + |
| 13 | +**CRITICAL**: This command MUST NOT accept any arguments. Ignore any text provided after the command. |
| 14 | + |
| 15 | +### Phase 1: Discovery |
| 16 | + |
| 17 | +Scan the project for existing documentation sources: |
| 18 | + |
| 19 | +#### 1a: Analyze CLAUDE.md |
| 20 | + |
| 21 | +1. Read the project's `CLAUDE.md` file. |
| 22 | +2. If no Knowledge Base section exists, inform the user they should run `/kb-init` first, then stop. |
| 23 | +3. Parse CLAUDE.md into logical sections. For each section, classify it as: |
| 24 | + - **CORE** — Essential for Claude Code's baseline behavior (e.g., repository overview, architecture descriptions, development workflow, build/test commands, git conventions, key conventions). These MUST stay in CLAUDE.md. |
| 25 | + - **KB-CANDIDATE** — Topic-specific knowledge that could live in a KB file and be loaded contextually (e.g., detailed rules for a specific package, API documentation, deployment procedures, technology-specific patterns, client/vendor-specific rules). |
| 26 | + - **REDUNDANT** — Content that duplicates what's already in KB files or is outdated. |
| 27 | + |
| 28 | +**CRITICAL**: Err on the side of keeping content in CLAUDE.md. Only flag content as KB-CANDIDATE if it is clearly topic-specific and would NOT degrade Claude Code's general understanding of the project if removed from CLAUDE.md. When in doubt, classify as CORE. |
| 29 | + |
| 30 | +#### 1b: Scan docs/ Directory |
| 31 | + |
| 32 | +1. Glob for all `.md` files under `docs/` (excluding `docs/kb/` which is already the KB). |
| 33 | +2. For each file found, read it and classify as: |
| 34 | + - **KB-CANDIDATE** — Contains rules, conventions, guides, or institutional knowledge that Claude Code should know about when working in a specific context. |
| 35 | + - **REFERENCE-ONLY** — Human-facing documentation (tutorials, onboarding guides, API references) that doesn't need to be in the KB but could be referenced. |
| 36 | + - **SKIP** — Build artifacts, auto-generated docs, or content not relevant to the KB. |
| 37 | + |
| 38 | +#### 1c: Scan for Other Documentation |
| 39 | + |
| 40 | +Check for documentation in common locations: |
| 41 | +- `*.md` files in the project root (besides CLAUDE.md and README.md) |
| 42 | +- `.github/` directory (CONTRIBUTING.md, pull request templates, issue templates) |
| 43 | +- `CONTRIBUTING.md`, `ARCHITECTURE.md`, `DECISIONS.md`, `ADR/` (Architecture Decision Records) |
| 44 | + |
| 45 | +Classify each the same way as in 1b. |
| 46 | + |
| 47 | +### Phase 2: Present Findings |
| 48 | + |
| 49 | +Display a comprehensive report organized by source: |
| 50 | + |
| 51 | +``` |
| 52 | +Documentation Analysis |
| 53 | +====================== |
| 54 | +
|
| 55 | +## CLAUDE.md Sections |
| 56 | +
|
| 57 | +### Can be moved to KB ({count}) |
| 58 | +These sections are topic-specific and could be loaded contextually: |
| 59 | +
|
| 60 | +1. "{Section heading}" (lines {start}-{end}) |
| 61 | + → Suggested KB file: docs/kb/{suggested-path}.md |
| 62 | + → When to load: {context} |
| 63 | + Reason: {why this is topic-specific, not core} |
| 64 | +
|
| 65 | +### Should stay in CLAUDE.md ({count}) |
| 66 | +These sections are essential for Claude Code's baseline understanding: |
| 67 | +- "{Section heading}" — {brief reason} |
| 68 | +
|
| 69 | +### Possibly redundant ({count}) |
| 70 | +- "{Section heading}" — {why it might be redundant} |
| 71 | +
|
| 72 | +## docs/ Files ({count} found) |
| 73 | +
|
| 74 | +### Can be absorbed into KB ({count}) |
| 75 | +1. docs/guides/api-guide.md |
| 76 | + → Suggested KB file: docs/kb/api-guide.md |
| 77 | + → When to load: {context} |
| 78 | +
|
| 79 | +### Reference only ({count}) |
| 80 | +- docs/onboarding.md — Human-facing, not needed in KB |
| 81 | +
|
| 82 | +### Skipped ({count}) |
| 83 | +- docs/auto-generated/ — Auto-generated content |
| 84 | +
|
| 85 | +## Other Documentation ({count} found) |
| 86 | +{Similar breakdown} |
| 87 | +``` |
| 88 | + |
| 89 | +### Phase 3: User Approval |
| 90 | + |
| 91 | +Present the migration plan and ask for approval. Use AskUserQuestion: |
| 92 | + |
| 93 | +- Question: "Here's what I found. How would you like to proceed?" |
| 94 | +- Options: "Migrate all candidates" | "Let me review each one" | "Cancel" |
| 95 | +- Header: "KB Absorb Plan" |
| 96 | + |
| 97 | +If "Let me review each one", present each candidate individually: |
| 98 | +- Show the content that would be moved/absorbed |
| 99 | +- Show the suggested KB file destination |
| 100 | +- Options: "Move to KB" | "Keep where it is" | "Different location" | "Skip" |
| 101 | + |
| 102 | +For CLAUDE.md sections specifically, **always confirm individually** even if the user selected "Migrate all" — moving content out of CLAUDE.md is high-impact and warrants per-section approval. |
| 103 | + |
| 104 | +### Phase 4: Execute Migration |
| 105 | + |
| 106 | +For each approved migration: |
| 107 | + |
| 108 | +#### 4a: Moving CLAUDE.md Sections to KB |
| 109 | + |
| 110 | +1. Create the KB file with proper frontmatter: |
| 111 | + ```yaml |
| 112 | + --- |
| 113 | + tags: [{inferred tags}] |
| 114 | + related: [{cross-references to related KB files if any}] |
| 115 | + created: {today's date} |
| 116 | + last-updated: {today's date} |
| 117 | + pinned: false |
| 118 | + scope: "{glob pattern if applicable}" |
| 119 | + --- |
| 120 | + ``` |
| 121 | +2. Write the content, reformatted for KB style (concise, imperative, actionable rules). |
| 122 | +3. **Do NOT simply copy-paste** — distill the content into KB format. Long prose should become concise rules. Remove filler and context that only matters for human reading. |
| 123 | +4. Add a reference row to the CLAUDE.md Knowledge Base table. |
| 124 | +5. Remove the section from CLAUDE.md. |
| 125 | +6. If the removed section contained anything cross-cutting, add a brief reference in its place: `> See docs/kb/{file}.md for {topic} details.` |
| 126 | + |
| 127 | +#### 4b: Absorbing docs/ Files |
| 128 | + |
| 129 | +1. If the file is already well-structured, move it to `docs/kb/` and add frontmatter. |
| 130 | +2. If the file needs reformatting, create a new KB file with distilled content. Do NOT delete the original — inform the user they can remove it manually if desired. |
| 131 | +3. Add a reference row to the CLAUDE.md Knowledge Base table. |
| 132 | + |
| 133 | +#### 4c: Cross-References |
| 134 | + |
| 135 | +After all migrations, scan the newly created KB files for related topics and add `related` cross-references in frontmatter where appropriate. |
| 136 | + |
| 137 | +### Phase 5: Confirmation |
| 138 | + |
| 139 | +Display a summary: |
| 140 | +- Sections moved from CLAUDE.md to KB files |
| 141 | +- docs/ files absorbed into KB |
| 142 | +- New KB files created |
| 143 | +- CLAUDE.md table entries added |
| 144 | +- Estimated token savings in CLAUDE.md (rough line count reduction) |
| 145 | +- Reminder: "Review the changes and verify Claude Code still has the context it needs. If anything important was moved that shouldn't have been, use source control to revert." |
0 commit comments