hugorcd/evlog

Overview

This skill guides you through adding a new built-in enricher to the evlog TypeScript package. It covers the six mandatory touchpoints: source code, tests, documentation updates, overview cards, AGENTS.md, and README entries. Follow the naming and architecture conventions to ensure consistent behavior across enrichers.

How this skill works

The skill explains how to implement the enricher factory, define the Info interface, and use helpers like getHeader() and mergeEventField() to set a single event field (ctx.event.{name}). It requires adding unit tests that exercise header parsing, overwrite behavior, and edge cases. Finally, it walks through updating three documentation locations plus the agents table so the enricher appears in the docs and README.

When to use it

• Adding derived context to wide events (deployment metadata, tenant context, feature flags, etc.).
• When you need a consistent, non-invasive way to augment events from headers or request data.
• When adding built-in enrichers that must ship with the evlog package.
• When you want automatic tests and docs alongside the implementation.

Best practices

• Follow the exact naming placeholders: {name} (camelCase), {Name} (PascalCase), {DISPLAY} (human-readable).
• Implement create{Name}Enricher(options?: EnricherOptions) that returns (ctx: EnrichContext) => void and accepts overwrite option.
• Always return early if required headers are missing; enrichers must not throw, log, or produce side effects beyond mutating ctx.event.
• Use getHeader() for case-insensitive header lookup and mergeEventField() to respect overwrite semantics.
• Add a full test suite covering header presence, missing headers, overwrite behavior, and edge cases (empty/malformed values).
• Complete all six touchpoints in a single PR before considering the work done.

Example use cases

• Add a deployment metadata enricher that reads X-Deploy-ID header and populates event.deployment.
• Create a tenant enricher that extracts a tenant ID header and merges tenant context into the event.
• Implement a feature-flag enricher that parses a flags header into event.featureFlags for downstream routing.
• Add a user agent enricher that derives structured browser/os fields from the User-Agent header and documents the output shape.