Knowledge Index

Knowledge Index Generator

Purpose: Scan all solution files, extract YAML frontmatter, and write a compact markdown index to docs/knowledge/index.md. This index enables single-read knowledge lookups instead of multiple Grep+Read tool calls.

Overview

The index file contains:

• A header with solution count, module count, and generation timestamp
• A Critical Patterns digest (titles + file refs from critical-patterns.md)
• A Modules table with file counts, key components, and relationships per module
• A Solutions table with all frontmatter fields from every solution file

One Read of this file replaces 3-4 Grep calls + N frontmatter reads + a Read of critical-patterns.md + module doc exploration.

Process

Step 1: Verify Knowledge Base

Check that docs/knowledge/solutions/ exists. If not, report: "No knowledge base found. Run /setup first."

Step 2: Gather All Solution Files

Glob: pattern="docs/knowledge/solutions/**/*.md"

Step 3: Read Critical Patterns

Read: docs/knowledge/patterns/critical-patterns.md

Extract each numbered pattern heading and its associated solution file reference. Format as:

- [Pattern Name] -> [relative/path/to/solution.md]

If the file only has the placeholder comment, the Critical Patterns section will be empty.

Step 4: Scan Module Docs

Glob: pattern="docs/knowledge/modules/*.md"

If no files found, skip this step. The Modules section will be omitted from the index.

For each module doc found, read the first 40 lines. Extract:

• Module name: from the # {Name} Module heading
• File count: number of rows in the Connected Files table
• Key components: unique Category values from the table (max 4)
• Relationships: from the model relationships section (max 4 related modules)

Use parallel Read calls in batches of 10 for efficiency.

Step 5: Extract Frontmatter From Each Solution

For each solution file, read the first 20 lines to extract YAML frontmatter fields:

• module
• date
• problem_type
• component
• severity
• tags (join array as comma-separated string)
• title (from the first # heading after frontmatter, or from the filename)

Use parallel Read calls in batches of 10 for efficiency.

If a file has malformed or missing frontmatter, skip it and count it as skipped.

Step 6: Generate Index File

Write docs/knowledge/index.md with this exact structure:

# Knowledge Index
<!-- Auto-generated by knowledge-index skill. Regenerate with /knowledge-garden::reindex -->
<!-- Updated: YYYY-MM-DD -->
<!-- Solutions: N -->
<!-- Skipped: M (malformed frontmatter) -->
<!-- Modules: P -->

## Critical Patterns
- [Pattern Name] -> [category/filename.md]
- ...

## Modules
| Module | Files | Key Components | Relationships | Doc |
|--------|-------|----------------|---------------|-----|
| User | 14 | Controller, Service, DTO, Repository | Order, Profile | modules/user.md |
| ... | ... | ... | ... | ... |

## Solutions
| File | Module | Type | Component | Severity | Date | Tags |
|------|--------|------|-----------|----------|------|------|
| category/filename.md | ModuleName | problem_type | component | severity | YYYY-MM-DD | tag1, tag2 |
| ... | ... | ... | ... | ... | ... | ... |

File column: Use the path relative to docs/knowledge/solutions/ (e.g., performance-issues/n-plus-one-user-queries-20260210.md).

Sort order: By date descending (newest first).

Modules section: Only include if module docs were found in Step 4. If no module docs exist, use <!-- Modules: 0 --> and omit the table.

Empty knowledge base: If no solution files found, write:

# Knowledge Index
<!-- Auto-generated by knowledge-index skill. Regenerate with /knowledge-garden::reindex -->
<!-- Updated: YYYY-MM-DD -->
<!-- Solutions: 0 -->
<!-- Modules: 0 -->

## Critical Patterns

## Solutions
| File | Module | Type | Component | Severity | Date | Tags |
|------|--------|------|-----------|----------|------|------|

Step 7: Report

Knowledge index updated.

- Solutions indexed: N
- Skipped (malformed): M
- Critical patterns: P
- Modules indexed: Q
- Written to: docs/knowledge/index.md

Error Handling

No solutions directory:

• Suggest running setup: "Run /setup to initialize knowledge-garden first."

No solution files:

• Write an empty index (Solutions: 0). This allows the auto-read phase in workflow commands to detect an empty KB with a single Read.

Malformed frontmatter:

• Skip the file, increment skipped counter, report at the end.

No module docs:

• Skip the Modules section. Use <!-- Modules: 0 --> in the header and omit the Modules table.