AGENT SKILL

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.

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

01 前言 Front Matter

name
x-validate-docs
model
sonnet
visibility
public
description
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.
allowed-tools
Read, Bash, Grep, Glob
argument-hint
[--story-id STORY-ID] [--pr-number N] [--scope path] [--report-path path]
context-budget
medium
user-invocable
true
requires-capabilities
[ "governance.doc-as-dod" ]

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: Documentation Freshness Validator

🔒 Read-only skill — does NOT modify any files. Produces a structured report and exits with a status code.

Purpose

Validates that documentation has been updated in sync with code changes introduced by a PR or branch. Consumes documentation.targets from ProjectConfig (introduced in story-0071-0001) to determine which dimensions to validate — only targets declared or auto-detected for the project stack are checked.

Produces a report at the path specified by --report-path (default: stdout). Exits 0 on pass; exits 1 (DOC_VALIDATION_FAILED) on any failed dimension.

Triggers

  • /x-validate-docs — validate all active dimensions from documentation.targets
  • /x-validate-docs --story-id story-XXXX-YYYY — validate for a specific story's PR
  • /x-validate-docs --pr-number 123 — validate against PR #123 diff
  • /x-validate-docs --scope src/main/java/ — limit code change analysis to path
  • /x-validate-docs --report-path ai/epics/epic-XXXX/reports/doc-validate-STORY-ID.md — persist report

Parameters

Parameter Type Required Description
--story-id String No Story ID (e.g., story-0071-0002). Used to derive report path if --report-path omitted.
--pr-number Integer No PR number. Limits diff to merged PR if specified.
--scope String No Path prefix to limit change detection (e.g., src/main/java/).
--report-path String No Output path for report. Default: print to stdout.
--freshness-window-hours Integer No Override freshness window from ProjectConfig (0 = immediate, default).

Exit Codes

Exit Code Condition
0 OK All active dimensions passed or skipped.
1 DOC_VALIDATION_FAILED At least one dimension detected staleness.
2 OPERATIONAL_ERROR Missing dependency, invalid args, or I/O error.

Validation Workflow

1. PARSE       -> Parse args, load ProjectConfig documentation.targets
2. DETECT      -> Identify changed files (git diff for PR or HEAD)
3. CLASSIFY    -> Map changed files to documentation dimensions
4. VALIDATE    -> Run each active dimension validator
5. WINDOW      -> Apply freshness-window-hours grace period
6. REPORT      -> Emit structured report, exit with status

Step 1 — Parse Arguments and Load Targets

Parse invocation arguments. Load documentation.targets from project YAML:

# Read documentation block from project YAML (iadev.yaml or profile.yaml)
cat iadev.yaml 2>/dev/null | grep -A 20 "^documentation:" | head -20

If documentation.targets is empty (auto-detect mode), apply stack-aware defaults:

Condition Auto-detected targets
interfaces[].spec=openapi present in YAML readme, openapi, adr, skill-docs
interfaces[].broker present (event-driven) readme, asyncapi, adr, skill-docs
interfaces[].spec=proto3 present readme, grpc-proto, adr, skill-docs
CLI-only project (no interfaces) readme, adr, skill-docs
docs/architecture/system.md exists add system-architecture to all above

Reject path traversal in targets: any target containing .. or starting with / or not matching [a-z0-9/_-]+ is rejected with OPERATIONAL_ERROR.

Step 2 — Detect Changed Files

# PR diff (when --pr-number given)
gh pr diff {pr_number} --name-only 2>/dev/null

# Branch diff against base (fallback)
git diff --name-only origin/develop..HEAD 2>/dev/null || git diff --name-only HEAD~1..HEAD

If --scope is specified, filter the changed file list to paths under that prefix.

Security: Never follow symlinks. Normalize all paths with realpath --relative-to=. before processing.

Step 3 — Classify Changes

Map changed files to documentation dimensions:

Changed file pattern Triggers dimension
src/**/ Java/TS/PY/Go files readme, api-specs (if REST controller detected), skill-docs
*.java matching *Controller*|*Resource*|*Handler*|*Endpoint* api-specs (openapi or asyncapi)
**/*.proto grpc-proto
docs/adr/**, story markdown with ADR Reference: adr
.claude/skills/** skill-docs
src/**/ new subdir in application/|domain/|adapter/ system-architecture
Only docs/** or *.md changed (no code) mark all non-touched dimensions as skipped (no code change)

If all changed files are documentation-only (no code), set overall result to PASS (degenerate case — PR is a docs-only PR).

Step 4 — Validate Each Active Dimension

Run each dimension that is (a) in documentation.targets (or auto-detected) AND (b) triggered by the changed files.

Dimension: readme

# Check if README.md was touched in the diff
git diff --name-only {range} | grep -i "^README"
  • PASS: README.md exists in diff AND contains at least one of the new symbols/features detected in code changes.
  • FAIL: Code changes added a new class/skill/config but README.md was NOT touched.
  • SKIP: Code changes did not affect user-facing features (only internal refactors, test changes).

Heuristic for "user-facing feature": new public class in adapter/inbound/, new SKILL.md, or new config key in YAML.

Dimension: api-specs (OpenAPI / AsyncAPI)

OpenAPI sub-dimension (active when interfaces[].spec=openapi):

# Detect new endpoints in diff
git diff {range} -- src/ | grep -E "^\+.*(@GetMapping|@PostMapping|@PutMapping|@DeleteMapping|@RequestMapping|app\.(get|post|put|delete))"

For each new endpoint detected, verify it appears in openapi.yaml / openapi.json / docs/api/*.yaml (by path+method):

# Check OpenAPI spec contains the endpoint path
grep -r "{endpoint_path}" openapi.yaml docs/api/ 2>/dev/null
  • PASS: All new endpoints appear in OpenAPI spec.
  • FAIL: At least one new endpoint is not documented in OpenAPI spec.
  • SKIP: No new endpoints detected in diff.

AsyncAPI sub-dimension (active when interfaces[].broker present):

# Detect new event publishers/consumers in diff
git diff {range} -- src/ | grep -E "^\+.*(publish|emit|subscribe|consume|@KafkaListener|@RabbitListener)"

Verify new event types appear in asyncapi.yaml / docs/events/*.yaml.

Dimension: grpc-proto

Active when interfaces[].spec=proto3 in project YAML.

# Check if proto files were modified when gRPC service classes changed
git diff --name-only {range} | grep "\.proto$"
git diff {range} -- src/ | grep -E "^\+.*(extends.*Grpc|@GrpcService|rpc [A-Z])"
  • PASS: New gRPC service methods detected AND corresponding .proto file touched.
  • FAIL: New gRPC service methods detected but NO .proto file in diff.
  • SKIP: No gRPC service changes detected.

Dimension: adr

Always active.

# Check if story file references an ADR and whether that ADR exists
find docs/adr/ -name "ADR-*.md" | wc -l

For each story touched in the PR (via ai/epics/*/story-*.md), verify:

  • If story contains ADR Reference: ADR-XXXX, that ADR file exists in docs/adr/.

  • If architectural decision was made (arch plan present), an ADR covers it.

  • PASS: All ADR references resolve to existing files.

  • FAIL: ADR reference resolves to non-existent file.

  • SKIP: No stories or arch plans touched in diff.

Dimension: skill-docs

Always active when .claude/skills/ exists.

# Check new SKILL.md files have required frontmatter
find .claude/skills/ -name "SKILL.md" -newer HEAD~1 2>/dev/null
git diff --name-only {range} | grep "SKILL\.md"

For each new or modified SKILL.md, validate:

  • Frontmatter contains: name, description, visibility, user-invocable, requires-capabilities.

  • Body contains ## Triggers section.

  • Body contains at least one usage example.

  • PASS: All SKILL.md files in diff have valid frontmatter + Triggers section.

  • FAIL: Missing required frontmatter field or missing Triggers section.

  • SKIP: No SKILL.md files in diff.

Dimension: system-architecture

Active when docs/architecture/system.md exists.

# Check for new architectural components in diff
git diff {range} -- src/ | grep -E "^\+.*class [A-Z]" | head -20
find src/ -newer docs/architecture/system.md -name "*.java" 2>/dev/null | grep -E "(application|domain|adapter)" | head -10

Detect new subdirectories in architectural layers:

git diff {range} --name-only | grep -E "^src/.*(application/|domain/|adapter/inbound/|adapter/outbound/)" | awk -F'/' '{print $1"/"$2"/"$3"/"$4}' | sort -u
  • PASS: docs/architecture/system.md was touched in diff OR no new architectural component was added.
  • FAIL: New component detected (new subdir in application/domain/adapter/ with ≥1 Java/TS/PY/Go file) but system.md was NOT touched.
  • SKIP: No architectural changes detected.

When fail detected, optionally invoke x-update-system-architecture --validate-only (if EPIC-0070 available):

Skill(skill: "x-update-system-architecture", model: "sonnet", args: "--validate-only")

[optional]

If x-update-system-architecture is unavailable: log WARN: x-update-system-architecture unavailable — system-architecture dimension evaluated heuristically.

Step 5 — Apply Freshness Window

If freshness-window-hours > 0 (from ProjectConfig or --freshness-window-hours flag):

# Check when code was last committed
git log -1 --format="%ci" -- {changed_code_files}

If the code was committed within the freshness window AND doc was NOT updated:

  • Downgrade FAIL → WARNING: "freshness window open — update documentation before merge"
  • Exit 0 with warnings surfaced in report.

If freshness window has expired AND doc was NOT updated:

  • Restore FAIL status → exit 1.

Step 6 — Emit Report

Write the structured report using _TEMPLATE-DOC-VALIDATE-REPORT.md. If --report-path is given, write to that path. Otherwise print to stdout.

Documentation Validation Report
  Story: {story-id or N/A}
  PR:    #{pr-number or N/A}
  Date:  {ISO-8601}

  Overall: PASS | FAIL | WARNING

  Dimensions:
    readme              : OK | FAILED | SKIPPED | WARNING
    api-specs           : OK | FAILED | SKIPPED | N/A (not in stack)
    grpc-proto          : OK | FAILED | SKIPPED | N/A (not in stack)
    adr                 : OK | FAILED | SKIPPED
    skill-docs          : OK | FAILED | SKIPPED
    system-architecture : OK | FAILED | SKIPPED | N/A (system.md absent)

  Failures:
    - {dimension}: {reason} (file: {relative-path})

  Warnings:
    - {dimension}: {message}

  Duration: {seconds}s

Security: Never include absolute filesystem paths in report output. Use paths relative to repository root. Never emit environment variables, tokens, or CI runner metadata.

Error Handling

Scenario Action
No git repository Exit 2 OPERATIONAL_ERROR: not a git repository
--pr-number but gh not on PATH Fall back to git diff HEAD~1..HEAD with WARN
Project YAML not found Use auto-detect mode for all targets with WARN
Target dimension validator throws error Mark dimension ERROR, continue others, exit 1
documentation.targets contains path traversal Exit 2 PATH_TRAVERSAL_REJECTED: {target}
Symlink encountered in file scan Skip symlink, log WARN, never follow

Performance Contract

  • Total validation time: < 30s for repositories with up to 500 changed files and 6 active dimensions.
  • No network calls during validation (all checks are local git + filesystem).
  • Each dimension validator runs independently; no shared mutable state.

Integration Notes

Skill Relationship Context
x-implement-story called-by Phase 3 — mandatory gate (story-0071-0006 wires this)
x-generate-docs precedes (in Phase 3) generate runs first, validate confirms
x-update-system-architecture optional-delegates-to system-architecture dimension, EPIC-0070
audit-doc-freshness.sh CI counterpart story-0071-0005 wires CI version of same checks

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