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
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.
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.
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.
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.
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.
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.