Corpus Index Enhancement

When to Use vs Other Skills

State Flow

Step 1              Step 2                Step 3             Step 4               Step 5              Step 6
────────────────────────────────────────────────────────────────────────────────────────────────────────────────
computed.sources -> computed.index     -> computed.topic  -> computed.findings -> computed.proposed -> computed
computed.config     computed.index_type   computed.goal      computed.sources     _changes             .entries
                    computed.sections     computed.depth      _searched           computed              _added
                                          computed.keywords  computed.new_docs    .keywords_applied

Process

1. VALIDATE  →  2. READ INDEX  →  3. ASK USER  →  4. EXPLORE  →  5. ENHANCE  →  6. SAVE

Step 1: Validate Prerequisites

Inputs: invocation args (topic, corpus_path) Outputs: computed.config, computed.sources See: lib/corpus/patterns/config-parsing.md and lib/corpus/patterns/status.md

Before proceeding, verify the corpus is ready for enhancement:

VALIDATE_PREREQUISITES():
  computed.config = Read("config.yaml")
  IF computed.config IS error:
    DISPLAY "No config.yaml found. Are you in a corpus skill directory?"
    DISPLAY "Valid locations: ~/.claude/skills/{name}/, {repo}/.claude-plugin/skills/{name}/"
    EXIT

  computed.sources = extract_sources(computed.config)
  IF len(computed.sources) == 0:
    DISPLAY "No sources configured. Run hiivmind-corpus-add-source first."
    EXIT

  index_content = Read("index.md")
  IF index_content IS error:
    DISPLAY "No index.md found. Run hiivmind-corpus-build first."
    EXIT
  IF index_content matches /Run hiivmind-corpus-build/:
    DISPLAY "Index is a placeholder. Run hiivmind-corpus-build first."
    EXIT

  computed.index_raw = index_content

Step 2: Read Index

Inputs: computed.index_raw (from Step 1) Outputs: computed.index, computed.index_type, computed.sections See: lib/corpus/patterns/paths.md for path resolution.

GUARD_STEP_2():
  IF computed.index_raw IS null:
    DISPLAY "Cannot proceed: Step 1 (Validate) has not completed."
    EXIT

Load the current index to understand existing coverage.

DETECT_INDEX_STRUCTURE():
  sub_indexes = Glob("index-*.md")
  IF sub_indexes IS error:
    DISPLAY "Failed to scan for sub-index files: " + sub_indexes.message
    # Non-fatal — assume single index
    sub_indexes = []

  IF len(sub_indexes) > 0:
    computed.index_type = "tiered"
    computed.sub_indexes = sub_indexes
    # Ask user which index to target
  ELSE:
    computed.index_type = "single"
    computed.sub_indexes = []

  computed.index = computed.index_raw
  computed.sections = extract_sections(computed.index)

Detect Index Structure

Single index: Only index.md exists Tiered index: Multiple files like index.md, index-reference.md, index-guides.md

For tiered indexes:

• Main index.md contains section summaries and links to sub-indexes
• Sub-indexes contain detailed entries for each section
• User may want to enhance main index OR a specific sub-index

Ask user: "This corpus uses tiered indexing. Do you want to enhance the main index overview, or a specific section like index-reference.md?"

Identify Enhancement Opportunities

• Current sections and their depth
• Topics with minimal entries
• Areas that could benefit from subsections
• Sections that link to sub-indexes (tiered only)

Step 3: Ask User

Inputs: computed.sections, computed.index_type (from Step 2) Outputs: computed.topic, computed.goal, computed.depth, computed.keywords

GUARD_STEP_3():
  IF computed.sections IS null:
    DISPLAY "Cannot proceed: Step 2 (Read Index) has not completed."
    EXIT

Present the current structure and ask:

1. Which topic to enhance?

   • "Which section would you like to expand?"
   • "Is there a specific feature or concept you need more detail on?"

2. What's the goal?

   • "What are you trying to accomplish with this topic?"
   • "Any specific questions you want the index to help answer?"

3. Desired depth?

   • "Should I find all related docs, or focus on the essentials?"
   • "Do you want subsections, or just more entries?"

4. Operational keywords? (if applicable)

   • "Is this corpus paired with a routing guide or decision tree?"
   • "Should entries include searchable keywords for operational lookup?"
   • "What vocabulary does your routing system use?"

   If the user has a routing guide, ask to see the keyword vocabulary.

Step 4: Explore

Inputs: computed.topic, computed.goal, computed.sources (from Steps 1, 3) Outputs: computed.findings, computed.sources_searched, computed.new_docs See: lib/corpus/patterns/scanning.md and lib/corpus/patterns/sources/README.md

GUARD_STEP_4():
  IF computed.topic IS null:
    DISPLAY "Cannot proceed: Step 3 (Ask User) has not completed."
    EXIT
  IF computed.sources IS null OR len(computed.sources) == 0:
    DISPLAY "Cannot proceed: no sources available."
    EXIT

Search for relevant documentation not yet in the index.

Identify Target Sources

IDENTIFY_TARGETS():
  computed.sources_searched = []
  computed.findings = []
  computed.new_docs = []

  IF user specified a source name:
    targets = [s for s in computed.sources if s.id == user_source]
    IF len(targets) == 0:
      DISPLAY "Source '" + user_source + "' not found in config.yaml."
      DISPLAY "Available sources: " + join(s.id for s in computed.sources, ", ")
      EXIT
  ELSE:
    targets = computed.sources  # search all

Search by Source Type

SEARCH_SOURCES(targets, topic):
  FOR source IN targets:
    computed.sources_searched.append(source.id)

    SWITCH source.type:
      CASE "git":
        base = ".source/" + source.id + "/" + source.docs_root
        results = Glob(base + "/**/*.md")
        IF results IS error:
          DISPLAY "Warning: could not scan " + base + " — " + results.message
          CONTINUE
        keyword_hits = Grep(topic, path=base, glob="*.md", output_mode="files_with_matches")

      CASE "local":
        base = "uploads/" + source.id
        results = Glob(base + "/**/*.md")
        keyword_hits = Grep(topic, path=base, glob="*.md", output_mode="files_with_matches")

      CASE "web":
        base = ".cache/web/" + source.id
        results = Glob(base + "/*.md")
        keyword_hits = Grep(topic, path=base, glob="*.md", output_mode="files_with_matches")

      CASE "self":
        repo_root = Bash("git rev-parse --show-toplevel").strip()
        docs_root = source.docs_root
        IF docs_root == ".": docs_root = ""
        base = repo_root + ("/" + docs_root IF docs_root ELSE "")
        results = Glob(base + "/**/*.md", exclude=".hiivmind/**")
        keyword_hits = Grep(topic, path=base, glob="*.md", output_mode="files_with_matches")

    # Filter to docs not already in the index
    FOR hit IN keyword_hits:
      entry_path = source.id + ":" + relative_path(hit, base)
      IF entry_path NOT IN computed.index:
        computed.new_docs.append({
          source: source.id,
          source_type: source.type,
          path: entry_path,
          file: hit
        })

    computed.findings.append({
      source: source.id,
      type: source.type,
      total_files: len(results),
      keyword_hits: len(keyword_hits),
      new_docs: len([d for d in computed.new_docs if d.source == source.id])
    })

Git sources (.source/{source_id}/):

If no local clone, use raw GitHub URLs (see lib/corpus/patterns/paths.md):