Summary
The Hookdeck CLI v1.9.0-beta.1 added metrics commands under hookdeck gateway metrics. The event-gateway skill should provide minimal guidance on when to use metrics and point to live docs for syntax/details.
Current State
skills/event-gateway/references/cli-workflows.md mentions metrics at line 226 with a brief example and link to docs. This is good! However, metrics aren't integrated into the monitoring/debugging workflow guidance.
Proposed Minimal Changes
Following the principle "only add context agents don't already have" - the skill should NOT duplicate command syntax (that's in the docs). Instead, provide use-case context for when/why agents should reach for metrics.
1. Add metrics decision point to references/monitoring-debugging.md
Add a brief section explaining when to use metrics vs event list:
## Metrics vs Event Inspection
**Use metrics** (`hookdeck gateway metrics`) when you need aggregate views:
- Overall health checks (error rates, volume trends)
- Identifying problematic resources (group failures by destination, source, connection)
- Queue depth monitoring (delivery backlog)
- Time-based trend analysis
**Use event list/inspect** (`hookdeck gateway event`) when you need individual event details:
- Inspecting specific event payloads
- Retrying individual events
- Detailed attempt history
For metrics command reference and examples, fetch [/docs/cli/metrics.md](https://hookdeck.com/docs/cli/metrics.md).
2. Update references/04-iterate.md
Add one line suggesting metrics as a starting point:
## Debug Workflow
Before diving into individual events, consider using `hookdeck gateway metrics events` to understand scope (isolated vs systemic failure, when it started, trends). See [Metrics docs](https://hookdeck.com/docs/cli/metrics.md).
Then proceed with event list/inspect/retry...
3. Keep existing cli-workflows.md as-is
The current line 226 already points to docs - that's sufficient. Don't add command examples (they'll go stale).
Rationale
Per AGENTS.md:
- "Only add context agents don't already have" - provide the decision context (when to use metrics), not syntax
- "Always link to live docs" - let docs be the source of truth for command details
- "Avoid time-sensitive information" - don't embed example commands that might change
Metrics are a monitoring workflow enhancement, so the main additions should be in monitoring-debugging.md (decision criteria) and 04-iterate.md (integration into debug workflow).
Anti-Pattern to Avoid
Do NOT add:
- Full command examples with all flags (that's in docs)
- Lists of available measures (that's in CLI help / docs)
- Syntax reference (that's in docs)
Impact
Minimal, focused additions (~10-15 lines total) that help agents know when metrics are useful, while keeping docs as the source of truth for how to use them.
Summary
The Hookdeck CLI v1.9.0-beta.1 added metrics commands under
hookdeck gateway metrics. The event-gateway skill should provide minimal guidance on when to use metrics and point to live docs for syntax/details.Current State
skills/event-gateway/references/cli-workflows.mdmentions metrics at line 226 with a brief example and link to docs. This is good! However, metrics aren't integrated into the monitoring/debugging workflow guidance.Proposed Minimal Changes
Following the principle "only add context agents don't already have" - the skill should NOT duplicate command syntax (that's in the docs). Instead, provide use-case context for when/why agents should reach for metrics.
1. Add metrics decision point to
references/monitoring-debugging.mdAdd a brief section explaining when to use metrics vs event list:
2. Update
references/04-iterate.mdAdd one line suggesting metrics as a starting point:
3. Keep existing
cli-workflows.mdas-isThe current line 226 already points to docs - that's sufficient. Don't add command examples (they'll go stale).
Rationale
Per AGENTS.md:
Metrics are a monitoring workflow enhancement, so the main additions should be in
monitoring-debugging.md(decision criteria) and04-iterate.md(integration into debug workflow).Anti-Pattern to Avoid
Do NOT add:
Impact
Minimal, focused additions (~10-15 lines total) that help agents know when metrics are useful, while keeping docs as the source of truth for how to use them.