lov-ataru-indexing

lov-ataru-indexing — make the local memory index searchable

Bring the Ataru index of this machine's AI session history to a searchable state, and hand back the result as a judgeable JSON report: whether retrieval is possible now, how much is still missing, and what was done this time. Retrieval itself belongs to lov-ataru-search。

Triggers

Activate when

• "The Ataru index seems out of date, help me rebuild it."
• "First confirm whether the local memory index is usable."
• Help me build or repair the local Ataru memory index before searching.

Do not activate when

• What the user wants is a retrieval result like "find out how a certain problem was solved last time" — hand it to lov-ataru-search, which will confirm the index state itself and point back to this Skill when it is not ready.
• The user is discussing Ataru's interface, releases, or code changes — that is a product development task, not index operations.

User Profile (cross-session)

skill.yaml declares user-profile/v1. At the start of each run, read the shared user, brand, workspace, preferences, and this Skill's skills.lov-ataru-indexing namespace.

The only record in this Skill worth keeping long-term is records.ataru_bin: the path to the usable Ataru executable on the user's machine. On the first successful resolution, or when the user states that path directly, use scripts/profile_store.py record to write it back and report the saved path; afterwards pass it as --bin to skip candidate probing every time. Do not hardcode it into this source. For the full contract see references/user-profile.md。

Skill Group Composition

See references/skill-composition.md. This source is an independent Single Skill, and with lov-ataru-search there is only an artifact-level handoff (index state), with no hidden sibling dependency.

Workflow (MANDATORY)

You MUST follow these steps in order.

Step 0: Resolve the binary before anything else

export SKILL_DIR="$HOME/.claude/skills/lov-ataru-indexing"
python3 "$SKILL_DIR/scripts/ataru_index.py" resolve-bin

The script resolves in the order "--bin explicit argument → ATARU_BIN environment variable → PATH → installed App bundle → local dev build found by searching upward from the current directory", and for each candidate first runs --version. Binaries below 0.41.3 do not recognize index statusand will treat it as a desktop launch argument open a windowand never return, so the version gate must pass first.

On failure the script returns ATARU_BIN_NOT_FOUND or ATARU_BIN_TOO_OLD, and lists the rejected candidates and their versions. Hand this raw text to the user; do not guess the path yourself.

Step 1: Read state before deciding to build

python3 "$SKILL_DIR/scripts/ataru_index.py" status

On top of the raw state, the report directly gives three judgment fields:

Field	Meaning
needsBuild	The index is not searchable and must be built
isBuilding	Another process (usually the desktop app) is building; do not contend
progressPercent	Share of messages processed, used to tell the user how much longer to wait

isBuilding When true, do not start a build. The build lock only takes effect within a process; although cross-process concurrent builds are backstopped by "write to a temp directory then atomically replace", they will waste a full pass of CPU.

Step 2: Bring the index to searchable

python3 "$SKILL_DIR/scripts/ataru_index.py" ensure --timeout 3600

ensure is idempotent: if already ready, return already-readydirectly; if there is an increment, run catch-up-build; if someone else is building, first waited-for-running-build. Add --force（full-rebuildonly when the user explicitly asks for a "full rebuild", because it discards the existing index and rescans all sessions.

The first full build is a minutes-long operation on a machine with tens of thousands of sessions, with a default budget of 3600 seconds. Do not shorten --timeout to "fail fast" — a timeout only leaves a half-finished state.

Step 3: Report, and only then hand off

Relay actions、state、totalSessions、totalMessages、indexSizeBytes to the user faithfully. Still state: error or searchAvailable: false , the script exits with code 1 and the error field in the report is the reason; hand it over as-is.

The optional semantic index is billed separately; estimate it first when needed:

python3 "$SKILL_DIR/scripts/ataru_index.py" semantic-preview

The current JSON CLI retrieval only uses keyword mode; the semantic index only serves the desktop client; do not promise users that the command line can get hybrid results.

Dependencies

• Python 3.8+ (standard library only)
• Ataru 0.41.3 or newer installed locally

General feedback loop

When a user raises revision feedback during a Skill-driven task, before continuing with the current artifact you must do the following:

1. First determine whether the feedback is task-specific(this time only) or reusable(reusable across tasks).
2. task-specific Only modify the current task, not the Skill.
3. reusable First determine the scope: for domain rules, update the corresponding canonical Skill first; for rules that apply to all Skills, update the shared specification first.
4. After completing the rule update, versioning, lint, and distribution verification, then apply the changes to the current task.
5. reusable The modification invalidates previous "confirm," "continue," and "send it" instructions; after completing the current artifact modification and read-back, you must stop and wait for the user's next instruction, and must not automatically proceed to publishing, committing, or other external writes.