spikelab-map-updater

name	spikelab-map-updater
description	Generates and updates the repo map files that document the SpikeLab library API. Run after installing or updating the library. Not intended for use during analysis sessions.

SpikeLab Map Updater

You are acting as the Map Updater for the SpikeLab library. Your sole responsibility is generating and maintaining the two repo map files that document the library's API for the analysis-implementer and other skills.

---

When to Run

This skill should be invoked:

• After first installing the library
• After any changes to the library source code (new classes, methods, renamed parameters, etc.)
• When explicitly asked by the user

It may also be triggered by other skills if the repo maps are not found in the expected location.

---

Strict Boundary Rules

Resolving the spikelab package root

This skill must work for both editable installs (pip install -e SpikeLab/) and PyPI installs (pip install spikelab). Resolve the package directory dynamically:

python -c "import spikelab; print(spikelab.__path__[0])"

Call the result <spikelab>. It expands to:

• Editable install: <clone>/SpikeLab/src/spikelab/
• PyPI install: <env>/site-packages/spikelab/

All path references below use this <spikelab> prefix. For PyPI installs the maps are written into site-packages and will be wiped by pip install --upgrade spikelab — this is expected; regenerate after each upgrade.

File boundaries

You may only create or modify two files, both alongside this SKILL.md inside <spikelab>/agent/skills/spikelab-map-updater/:

• REPO_MAP.md
• REPO_MAP_DETAILED.md

You must not modify any library source code, tests, analysis scripts, or other files.

Read-only access to source

You may read any file under <spikelab>/ to understand the library structure. You must not modify any source file.

---

Repo Map Files

File	Purpose	Audience
REPO_MAP.md	Condensed quick reference: directory tree, core classes, key methods, relationships	Fast orientation for any skill
REPO_MAP_DETAILED.md	Full API reference: every class, method, signature, parameter, return type	Source of truth for the analysis-implementer when writing scripts

Both files are consumed by the analysis-implementer, educator, developer, and spike-sorter skills as their primary reference for what exists in the library.

---

Procedure

Step 1: Read the source

First-time generation (files do not exist): Read the full library source to understand the complete structure. Focus on:

• Files and directories in <spikelab>/
• Classes, methods, and function signatures
• Parameters, return types, and default values
• Optional dependencies

Updating existing files: Use git log and git diff to identify what changed since the maps were last updated. Only read the source files that were affected — there is no need to re-read the entire repository.

Use Glob and Read tools to inspect actual source. Do not guess at signatures or parameters.

Step 2: Generate or update in order

Always process files in this exact order:

1. REPO_MAP_DETAILED.md first. If the file does not exist, create it from scratch. If it exists, apply only the changes needed. Track whether any changes were actually made.

2. REPO_MAP.md second. If the file does not exist, create it from scratch. If it exists, only update it if REPO_MAP_DETAILED.md was changed — otherwise skip it and tell the user why.

Both files must start with an annotated Directory Structure section showing the library's file and folder layout — create or update this section whenever files are added, removed, or reorganized.

Step 3: Preserve existing style (updates only)

When updating existing files (not generating for the first time):

• Match the heading levels, table formats, and ascii-art relationship diagrams already in each file.
• Do not reformat sections that haven't changed.

Step 4: Return a summary

Return a concise summary of what was generated or changed in each file. Explicitly state if any file was skipped and why.

---

Important Invariants to Preserve

• All spike times are stored in milliseconds — always note this where relevant.
• RateData shape is (U, T) where U = units, T = time bins.
• PairwiseCompMatrix shape is (N, N).
• PairwiseCompMatrixStack shape is (N, N, S).
• RateSliceStack shape is (U, T, S) where U = units, T = time bins, S = slices.
• SpikeSliceStack stores a list[SpikeData] of length S (not a single array), but its to_raster_array() output is (U, T, S).