Skip to content

bug: skill enrichment race condition — early sessions miss keyword-based auto-loading #316

@Aaronontheweb

Description

@Aaronontheweb

Problem

Skill keyword enrichment runs as a fire-and-forget Task.Run() in SystemSkillSyncService.RescanAndUpdateIndex() (line 330). Sessions that start before enrichment completes get no keyword matches because the _enrichedKeywords dictionary in SkillRegistry is empty for those skills.

Root Cause

  1. SystemSkillSyncService.StartAsync() calls RescanAndUpdateIndex() synchronously
  2. RescanAndUpdateIndex() registers skills in the registry and updates the skill index
  3. Enrichment is fired as _ = Task.Run(() => EnrichAllSkillsAsync()) — no await
  4. The daemon is ready to accept Slack events immediately
  5. First user message arrives → MatchByKeywords() → skill not in _enrichedKeywords → skipped

The enrichment process hits the LLM for each skill (with a 30s timeout per skill). With 6 system skills, enrichment can take 30-180 seconds. Any session started during this window gets no auto-loaded skills.

Mitigating Factor

The keyword cache (~/.netclaw/skills/.system-keywords/) means enrichment only hits the LLM on first run or after skill content changes. Cached keywords load instantly. But after a fresh install, version upgrade, or cache invalidation, the race window is wide.

Expected Behavior

Skills should be usable from the moment the daemon accepts connections. Options:

  1. Block startup until enrichment completes (but this conflicts with "never blocks startup")
  2. Use fallback keywords immediately, upgrade to enriched keywords when ready — currently, if _chatClientProvider is available, fallback keywords are NOT applied (line 328-350). Only the else branch applies fallbacks.
  3. Apply fallback keywords first, then enrich in background — best of both worlds

Relevant Code

  • SystemSkillSyncService.cs:316-351RescanAndUpdateIndex() fire-and-forget
  • SystemSkillSyncService.cs:516-544ApplyFallbackKeywords (only used when no provider)
  • SkillRegistry.cs:91-149MatchByKeywords skips un-enriched skills (line 113-114)

Incidents

Session D0AC6CKBK5K/1774023557.531309 (0.7.1) could not load any skills on first interaction.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions