skills.rest
gmanch94
gmanch94COMMUNITY
Explore all skills by this author →
GitHub

saga-trace

Convert Agora saga_event rows into readable timelines with anomaly detection.

Updated May 2, 2026
Search Tags:#debugging#database#idempotency#saga#event sourcing#ledger#agora
One-click install
npx skills add https://github.com/gmanch94/agora --skill saga-trace
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: saga-trace
Source: https://github.com/gmanch94/agora/tree/main/.claude/skills/saga-trace
Command: npx skills add https://github.com/gmanch94/agora --skill saga-trace

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps you understand why an Agora saga ended unexpectedly by translating the event-sourced saga ledger into a scan-friendly timeline.

Core Features & Use Cases

  • Pretty-print saga_event timelines: Renders one human-readable line per ledger event with aligned columns for quick inspection.
  • Supports multiple input modes: Pulls from the live database when DB env vars are set, or renders from a JSON file (events array or full dump) / pasted JSON.
  • Detects ledger anomalies: Flags inconsistencies like gate-without-forward, forward-without-gate (treated as a bug), compensator without a committed forward, non-contiguous sequence numbers, duplicate idempotency keys, and terminal state with pending outcomes.
  • Safety-oriented guidance: Provides guardrails to avoid writing saga rows, and warns against dumping huge payloads inline.

Quick Start

Ask to trace saga <uuid> to get a five-second human-readable timeline of its forward steps, gates, compensators, outcomes, and any anomalies.

Frequently Asked Questions about saga-trace

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a stuck saga by reading its event sourcing ledger?▼

To debug a stuck saga, you convert saga_event rows into a readable event timeline by querying a live database or parsing a JSON payload. This renders forward steps, gates, and compensators into scan-friendly aligned columns for quick inspection.

What is a saga ledger anomaly and how do I detect it in event sourcing?▼

A saga ledger anomaly is an inconsistency like a forward-without-gate, non-contiguous sequence numbers, or duplicate idempotency keys. Anomaly detection scans the saga ledger and flags these issues alongside the rendered timeline.

Can I trace an Agora saga timeline from a pasted JSON payload without a database connection?▼

Yes, you can trace an Agora saga timeline from a pasted JSON payload or JSON file without a live database connection. Timeline rendering and anomaly detection work directly from the provided events array or full dump offline.

How do I verify that saga gates and compensators were actually committed?▼

To verify that saga gates and compensators were committed, trace the saga identifier to generate a human-readable timeline. This timeline explicitly shows committed forward steps and compensator executions, flagging any gate-without-forward anomalies.

What are the limitations when debugging a saga ledger with large payloads?▼

A limitation when debugging a saga ledger is that dumping huge payloads inline is discouraged to avoid performance issues. Safety guardrails also warn against writing saga rows directly during the debugging process.

Related Skills

Explore More Software Engineering Skills→
heinschulieheinschulie

database

Provision managed PostgreSQL, Redis, MySQL, and MongoDB databases via Railway templates.

Community
Intermediate
statesetstateset

commerce-events

Inspect and replay commerce events, idempotency keys, and outbox states for debugging.

Official
Advanced
gmanch94gmanch94

lifecycle-extend

Extend Agora's ILL lifecycle with new states while preserving saga invariants.

Community
Advanced
marlo9981marlo9981

schema-exploration

List tables, describe columns and data types, and identify foreign keys.

Community
Intermediate