agentleFS
all-source-osall-source-os/all-source/.claude/skills/allsource-debug/SKILL.md

allsource-debug

Skill4 starsChanged yesterdayApache-2.0View on GitHub

Debug AllSource-backed applications by inspecting projections, querying events, tracing replay, and diagnosing stale or corrupt state. Triggers on: "debug allsource", "inspect events", "why is projection wrong", "stale state", "missing events", "projection mismatch", "event replay", "debug entity". Use MCP tools directly — they read from the data directory without a running server: Every command opens the store read-only, so it is safe to run while the app is writing. Symptom: UI shows runsCount: 0 but you know there are runs. Steps:…

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 11 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use MCP tools directly — they read from the data directory without a running server:

    line 13
  2. Distinctive:

    Every command opens the store read-only, so it is safe to run while the app is writing.

    line 49
  3. Distinctive:

    Check if the events have the fields the projection expects:

    line 72
  4. Distinctive:

    Check if events are actually persisted:

    line 93
  5. Distinctive:

    Check WAL vs Parquet:

    line 97
  6. Distinctive:

    Verify the entity has recent events:

    line 101
  7. Distinctive:

    Start with explain_entity for the overview

    line 132
  8. Distinctive:

    Use event_timeline for the detailed sequence

    line 133
  9. Distinctive:

    Use analyze_changes with time bounds to focus on a specific period

    line 134
  10. Distinctive:

    Use reconstruct_state to see the final folded state

    line 135
  11. Distinctive:

    Use quick_stats to check durability status:

    line 140

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

AllSource Debug

Debug AllSource-backed applications by inspecting projections, querying events, tracing replay, and diagnosing stale or corrupt state.

Triggers on: "debug allsource", "inspect events", "why is projection wrong", "stale state", "missing events", "projection mismatch", "event replay", "debug entity".


Tools Available

If allsource-mcp is configured (preferred)

Use MCP tools directly — they read from the data directory without a running server:

ToolUse When
query_eventsFind events for an entity or event type
quick_statsGet store overview (counts, types, date range)
event_timelineSee chronological event sequence for an entity
explain_entityGet human-readable lifecycle summary
reconstruct_stateFold events to rebuild current state
get_snapshotGet projection/snapshot state
analyze_changesCompare state between two time points
sample_eventsDiscover what event types exist

If allsource-inspect CLI is available

# Which data directory? An app can keep several (per profile, per workspace)
allsource-inspect stores --root <app-support-dir>

# Find all events for an entity
allsource-inspect events --data-dir <path> --entity-id "workflow:abc-123" --format json

# Find events by type prefix, printing only the payload keys
allsource-inspect events --data-dir <path> --event-type-prefix "workflow_run." --keys --format json

# Current state of every run in one pass
allsource-inspect lifecycle --data-dir <path> --event-type-prefix "workflow_run." \
  --states started,completed,failed --format json

# Storage summary
allsource-inspect summary --data-dir <path>

# Events still in the WAL
allsource-inspect wal --data-dir <path> --format json

Every command opens the store read-only, so it is safe to run while the app is writing.

Default data directory locations

PlatformAppPath
macOSLonghand~/Library/Application Support/Longhand/allsource/
LinuxLonghand~/.local/share/longhand/allsource/
DockerCore/app/data/ (mapped via volume)

Debugging Workflows

1. Projection shows wrong count or missing data

Symptom: UI shows runsCount: 0 but you know there are runs.

Steps:

  1. Query raw events for the entity:
    Use query_events with entity_id="<entity>" to see all events
  2. Check if the events have the fields the projection expects:
    Use event_timeline with entity_id="<entity>" to see event sequence
  3. Compare projection state vs reconstructed state:
    Use get_snapshot for the projection view
    Use reconstruct_state to fold events manually
    Compare the two — differences indicate projection bugs

Common causes:

  • Event missing a field the projection indexes on (e.g., definition_id)
  • Projection filter doesn't match event type pattern
  • Events ingested with wrong entity_id format

2. Stale projection state

Symptom: Projection shows old data, new events aren't reflected.

Steps:

  1. Check if events are actually persisted:
    Use quick_stats to see total event count and latest timestamp
  2. Check WAL vs Parquet:
    Use quick_stats — if wal_entries > 0 and parquet is behind, events may be in WAL only
  3. Verify the entity has recent events:
    Use query_events with entity_id and since=<recent timestamp>

Common causes:

  • Events in WAL but not yet flushed to Parquet
  • Projection registered after events were ingested (missed replay)
  • Application crash before WAL fsync

3. Duplicate or missing events in replay

Symptom: Event count doesn't match expected, or state has duplicates.

Steps:

  1. Get full event timeline:
    Use event_timeline with entity_id — check for gaps in version numbers
  2. Look for duplicates:
    Use query_events with entity_id — check for duplicate timestamps or event types
  3. Check version sequence:
    • Versions should be monotonically increasing per entity
    • Gaps indicate missed events
    • Duplicate versions indicate replay issues

4. Understanding an entity's lifecycle

Steps:

  1. Start with explain_entity for the overview
  2. Use event_timeline for the detailed sequence
  3. Use analyze_changes with time bounds to focus on a specific period
  4. Use reconstruct_state to see the final folded state

5. Verifying data after restart

Steps:

  1. Use quick_stats to check durability status:
    • durable: true means all events are persisted
    • wal_enabled: true with entries means WAL has data
    • parquet_files > 0 means long-term storage is working
  2. Query a known entity to verify data survived:
    Use query_events with a known entity_id

Key Concepts

  • Events are immutable — once ingested, they cannot be modified or deleted
  • Projections are derived — they're computed from events and can be rebuilt
  • WAL is the write path — events hit WAL first, then flush to Parquet
  • Parquet is the read path — queries read from Parquet + in-memory DashMap
  • Entity ID format — typically type:uuid (e.g., workflow:abc-123)
  • Event type format — dot-separated (e.g., workflow_run.started, workflow_run.completed)
  • System events — prefixed with _system. (tenants, config, auth, schemas)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.