AGENT SKILL

x-review-observability

Observability specialist review: validates distributed tracing, metrics naming, structured logging, health checks, correlation IDs, and alerting configuration.

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

01 前言 Front Matter

name
x-review-observability
description
Observability specialist review: validates distributed tracing, metrics naming, structured logging, health checks, correlation IDs, and alerting configuration.
allowed-tools
Read, Grep, Glob, Bash
argument-hint
[PR number or file paths]
fragment-slot
{ "slot": "review-specialist", "fragment-id": "obs", "fragment-order": 40 }
user-invocable
true
requires-capabilities
[]

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: Observability Specialist Review

Purpose

Review code changes for observability best practices: distributed tracing with proper span attributes, metrics naming conventions, structured logging with mandatory fields, health check implementation, correlation ID propagation, and alerting configuration.

Activation Condition

Include this skill when observability.tool != "none" in the project configuration.

When to Use

  • Pre-PR quality validation for observability concerns
  • Reviewing logging and tracing implementations
  • Checking health check endpoints
  • Validating metrics and alerting configuration

Triggers

  • /x-review-observability 42 -- review PR #42 for observability
  • /x-review-observability src/main/java/com/example/config/ -- review specific paths
  • /x-review-observability -- review all current observability changes

Parameters

Parameter Type Required Default Description
target String No (current changes) PR number or file paths to review

Knowledge Pack References

Pack Files Purpose
observability skills/observability/SKILL.md Tracing, metrics, logging, health checks, correlation IDs

Checklist (9 Items, Max Score: /18)

Each item scores 0 (missing), 1 (partial), or 2 (fully compliant).

Distributed Tracing (OBS-01 to OBS-03)

# Item Score
OBS-01 Spans created for key operations (inbound requests, outbound calls, DB queries) /2
OBS-02 Span attributes include mandatory fields (service, operation, status) /2
OBS-03 Trace context propagated across service boundaries (W3C Trace Context headers) /2

Structured Logging (OBS-04 to OBS-06)

# Item Score
OBS-04 Logs are structured JSON with mandatory fields (timestamp, level, message, trace_id, span_id, service) /2
OBS-05 No sensitive data in logs (PII, credentials, tokens masked or excluded) /2
OBS-06 Log levels appropriate (DEBUG for development, INFO for operations, WARN/ERROR for issues) /2

Health Checks & Metrics (OBS-07 to OBS-09)

# Item Score
OBS-07 Health check endpoints implemented (liveness, readiness, startup) /2
OBS-08 Custom metrics follow naming convention ({service}{subsystem}{metric}_{unit}) /2
OBS-09 Correlation ID generated or propagated on every inbound request /2

Workflow

Step 1 -- Gather Context

Read the observability knowledge pack:

  • skills/observability/SKILL.md

Step 2 -- Identify Changed Files

Determine scope: configuration, middleware, service classes, health check endpoints.

Step 3 -- Tracing Review

Check span creation, attributes, and context propagation.

Step 4 -- Logging Review

Verify structured logging, mandatory fields, and sensitive data exclusion.

Step 5 -- Health Check Review

Verify liveness, readiness, and startup probe implementations.

Step 6 -- Metrics Review

Check custom metrics naming conventions and correlation ID propagation.

Step 7 -- Generate Report

Produce the scored report.

Output Format

ENGINEER: Observability
STORY: [story-id or change description]
SCORE: XX/18

STATUS: PASS | FAIL | PARTIAL

### PASSED
- [OBS-XX] [Item description]

### FAILED
- [OBS-XX] [Item description]
  - Finding: [file:line] [issue description]
  - Fix: [remediation guidance]

### PARTIAL
- [OBS-XX] [Item description]
  - Finding: [partial compliance details]

Error Handling

Scenario Action
No observability code found Report INFO: no observability code discovered
OpenTelemetry not configured Warn and check for alternative tracing libraries
Health check endpoints missing Report as FAILED for OBS-07

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