AGENT SKILL

x-review-events

Validates event schemas, producer/consumer patterns, error handling, dead letter topics, and operational readiness for event-driven architectures.

License 许可
MIT
最近更新
2026-10-27
Stars
★ 0
Forks
1

01 前言 Front Matter

name
x-review-events
description
Validates event schemas, producer/consumer patterns, error handling, dead letter topics, and operational readiness for event-driven architectures.
allowed-tools
Read, Grep, Glob, Bash
argument-hint
[event-name or consumer/producer class]
fragment-slot
{ "slot": "review-specialist", "fragment-id": "events", "fragment-order": 60 }
context-budget
medium
user-invocable
true
requires-capabilities
[]

02 资源文件 1

03 SKILL.md 正文

Global Output Policy

  • Language: English ONLY.
  • Tone: Technical, Direct, and Concise.
  • Efficiency: Remove all conversational fillers and greetings to save tokens.

Skill: Event-Driven Review

Purpose

Reviews event-driven patterns: event schema design, producer/consumer implementation, error handling, dead letter topics, and operational readiness. Covers CloudEvents envelope, schema registry integration, and saga patterns.

Activation Condition

Include this skill when the project uses event-driven interfaces (interfaces contains type: event-consumer or type: event-producer).

Triggers

  • /x-review-events OrderCreated -- review a specific event
  • /x-review-events PaymentConsumer -- review a consumer class
  • /x-review-events -- review all event-driven patterns

Parameters

Parameter Type Required Default Description
target String No (all) Event name, consumer/producer class name

Knowledge Pack References

Pack Files Purpose
protocols skills/protocols/references/event-driven-conventions.md CloudEvents envelope, event naming, schema registry, ordering guarantees, broker patterns

Prerequisites

  • Event definitions exist (event classes, Avro/Protobuf schemas, or JSON Schema)
  • Message broker dependency configured (Kafka, RabbitMQ, SQS, etc.)
  • Producer and/or consumer implementations exist

Workflow

Step 1 — Discover Event Definitions

Scan for event classes, schemas, Avro/Protobuf definitions:

  • List all event types with their schemas
  • Identify event envelope structure

Step 2 — Discover Producers

Scan for classes publishing events:

  • Map producers to topics and event types
  • Identify publishing patterns (outbox, direct)

Step 3 — Discover Consumers

Scan for classes consuming events:

  • Map consumers to topics and consumer groups
  • Identify idempotency mechanisms

Step 4 — Validate Event Design

Check naming, envelope, versioning:

  • Past tense event names
  • CloudEvents spec compliance
  • Schema registry integration
  • Data minimization

Step 5 — Validate Producer Patterns

Check reliability:

  • Outbox or at-least-once delivery
  • Acknowledgment levels
  • Error handling and retry

Step 6 — Validate Consumer Patterns

Check processing:

  • Idempotency implementation
  • Offset commit strategy
  • Dead letter topic configuration
  • Graceful shutdown

Step 7 — Validate Operational Readiness

Check monitoring:

  • Consumer lag monitoring
  • Dead letter topic alerts
  • Schema registry health

Step 8 — Generate Report

Summarize findings as checklist:

  • List compliant items
  • List violations with file paths and line numbers
  • Suggest fixes for each violation

Event Design Checklist (10 points)

Schema & Naming (1-4)

  1. Event names use past tense (OrderCreated, PaymentProcessed, InventoryReserved)
  2. Event envelope follows CloudEvents spec or project-standard envelope (type, source, id, time, data)
  3. Schema registered in schema registry (Avro, Protobuf, or JSON Schema)
  4. Event versioning strategy defined: additive-only changes in same version, new event type for breaking changes

Data Design (5-7)

  1. Events contain only necessary data (data minimization, no full entity dump)
  2. Correlation ID present for distributed tracing
  3. No sensitive data in event payload (or encrypted if absolutely required)

Topic/Queue Design (8-10)

  1. Topic naming follows convention: {domain}.{entity}.{event} (e.g., payment.transaction.created)
  2. Partition key chosen for ordering guarantees (e.g., entity ID for per-entity ordering)
  3. Message retention and compaction policy documented

Producer Checklist (8 points)

  1. Transactional outbox pattern used for reliable publishing (database + event in same transaction)
  2. OR: at-least-once delivery with consumer idempotency (if outbox not used, document why)
  3. Producer acknowledgment level appropriate (all replicas for critical events)
  4. Serialization uses registered schema (not ad-hoc JSON serialization)
  5. Error handling: failed publishes logged, retried with backoff, dead-lettered after max retries
  6. Idempotency key on producer if exactly-once semantics required
  7. Event published AFTER successful business operation (not before)
  8. Trace context propagated in event headers (W3C Trace Context)

Consumer Checklist (10 points)

  1. Consumer is idempotent (processing same event twice produces same result)
  2. Idempotency key stored and checked (event ID + consumer group, or business key)
  3. Consumer group ID follows convention: {service}.{purpose} (e.g., billing.invoice-generator)
  4. Offset commit strategy: commit after successful processing (not auto-commit)
  5. Error handling: failed processing -> retry with backoff -> dead letter topic after N retries
  6. Dead letter topic monitored with alerts
  7. Consumer lag monitored (alert if lag exceeds threshold)
  8. Deserialization errors handled gracefully (poison pill protection)
  9. Processing timeout configured (prevent infinite blocking)
  10. Graceful shutdown: stop consuming, finish in-flight, commit offsets, then exit

Saga Pattern Checklist (conditional -- if multi-step workflows)

  1. Saga orchestrator or choreography pattern documented
  2. Compensation actions defined for each saga step
  3. Saga state persisted (recoverable after crash)
  4. Timeout on saga completion (trigger compensation if exceeded)

Output Format

## Event-Driven Review — [Event/Change Description]

### Event Design: HIGH / MEDIUM / LOW
### Producer Quality: HIGH / MEDIUM / LOW
### Consumer Quality: HIGH / MEDIUM / LOW

### Event Design Findings
1. [Finding with file, line, issue, fix]

### Producer Findings
1. [Finding with file, line, issue, fix]

### Consumer Findings
1. [Finding with file, line, issue, fix]

### Operational Readiness
- Dead Letter Topic: [configured / missing]
- Consumer Lag Monitoring: [configured / missing]
- Schema Registry: [configured / missing]

### Checklist Results
[Items that passed / failed / not applicable]

### Verdict: APPROVE / REQUEST CHANGES

Error Handling

Scenario Action
No event definitions found Report INFO: no event-driven code discovered
Missing schema registry REQUEST CHANGES with remediation guidance
Consumer not idempotent REQUEST CHANGES with idempotency pattern example

Rules

  • REQUEST CHANGES if consumer is not idempotent
  • REQUEST CHANGES if no dead letter topic configured
  • REQUEST CHANGES if sensitive data in event payload
  • REQUEST CHANGES if no schema validation/registry
  • REQUEST CHANGES if event published before business operation completes
  • Flag missing outbox pattern (suggest it, don't block if documented alternative exists)

04 同仓库更多 Skills

review-bench
review-bench/edercnj_ia-dev-environment

x-parallel-eval

Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

parallelism-heuristics

Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-watch-pr-ci

Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-validate-docs

Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-update-system-architecture

Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-update-architecture

Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.

★ 0