kb-rebuild-indexes

Files (2)

• SKILL.md
• shelf-index-example.md · templates/

SKILL.md (first lines)

# Rebuild Knowledge Base Indexes

> **Script-based**: This skill runs `build_shelf_index.py` via Bash — no agent dispatch needed and no library file content loaded into session context.

Rebuild the shelf-index for the knowledge base. Incremental by default: compares each library file's content hash against the recorded hash in the index, and only re-extracts entries whose hash has changed.

## Arguments

- `--full` — Force complete rebuild. Re-extracts every entry even when the hash matches. Use this when:
  - The extraction logic itself has changed (you updated this skill)
  - You suspect the index has drifted in a way the hash check missed
  - You're starting from a deleted or corrupted index

  Without this flag, the rebuild is incremental and skips unchanged files.
- `--dry-run` — Report what would change (including the `Scanned:` / `Excluded:` breakdown) without writing `_shelf-index.md` or `log.md`.
- `--force` — Override the bulk-add safety rail (see "Safety rail" below). **Never pass this on your own initiative** — only after the user has seen the breakdown and confirmed.

## Excluding directories: `.kb-index-ignore`

The rebuild indexes every `.md` file under the library, except the top-level `raw/` directory (always excluded). To keep other directories out of the index — vendored dumps, scraped reference material, anything that is not a curated library file — create `<library_path>/.kb-index-ignore`:

```
# one library-relative directory per line
iso20022/
vendor/standards
```

- One directory path per line, relative to the library root; a trailing `/` is optional.
- A path matches that directory and everything under it. No globs.
- `#` comments and blank lines are ignored.
- Absolute paths and `..` entries are rejected. An entry that matches nothing produces a warning.

## Preflight

Verify the project has a knowledge base. The `[Knowledge Base]` section in `CLAUDE.md` should declare:

- `library_path` — default `library/`
- `shelf_index_path` — default `library/_shelf-index.md`

If `CLAUDE.md` does not contain a `[Knowledge Base]` section, report: "No knowledge base configured. Add a `[Knowledge Base]` section to CLAUDE.md (see `plugins/sdlc-knowledge-base/skills/kb-init/templates/claude-md-section.md`) before running this skill."

If the library path does not exist, report: "Library directory `<path>` does not exist. Create it or run `/sdlc-knowledge-base:kb-init` before running this skill."

## Steps

### 1. Read knowledge base configuration

Read `CLAUDE.md` and locate the `[Knowledge Base]` section. Extract:
- `library_path` — default `library/`
- `shelf_index_path` — default `library/_shelf-index.md`

Stop with the preflight errors above if either check fails.

### 2. Verify build_shelf_index module importable

```bash
python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts', INIT,
        submodule_search_locations=[SCRIPTS])
    if spec and spec.loader:
        module = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = module
        spec.loader.exec_module(module)
try:
    import sdlc_knowledge_base_scripts.build_shelf_index  # noqa: F401
    print('OK')
except ImportError:
    print('MISSING')
"
```

If output is `MISSING`: report "build_shelf_index module not found. Update the sdlc-knowledge-base plugin." and stop.

### 3. Run the rebuild script

Construct the argument list from Step 1 and the skill argument (`--full` if provided):

```bash
python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts', INIT,
        submodule_search_locations=[SCRIPTS])
    if spec and spec.loader:
        module = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = module
        spec.loader.exec_module(module)
from sdlc_knowledge_base_scripts.build_shelf_index import main
args = ['<library_path>', '--shelf-index-path', '<shelf_index_path>']
# Append flags the skill was called with:
# args.append('--full')       # skill argument --full
# args.append('--dry-run')    # skill argument --dry-run
# args.append('--force')      # ONLY on the re-run after the user confirms a safety-rail refusal
sys.exit(main(args))
"
```

Replace `<library_path>` and `<shelf_index_path>` with the values from Step 1. Uncomment each `args.append(...)` line that applies: `--full` and `--dry-run` when the skill argument included them, and `--force` only on the re-run after the user has confirmed a safety-rail refusal (see below). Never add `--force` on the first run.

### 4. Report results

Print the script output directly to the user. Expected format:

```
Shelf-index rebuilt: library/_shelf-index.md

  Mode: incremental
  Files scanned: 22
  Unchanged:    18  (skipped)

From SteveGJones/ai-first-sdlc-practices, MIT.

More from SteveGJones/ai-first-sdlc-practices