AGENT SKILL

traceability-review

Review explicit architecture traceability metadata for gaps, inconsistencies, unsupported claims, stale links, dangling references, and metamodel violations. Use when Codex needs to inspect artifact relations, validate ADR-to-risk or quality-scenario coverage, propose relation updates, or produce an evidence-backed traceability review report.

License 许可
MIT
最近更新
2026-11-10
Stars
★ 4
Forks
2

01 前言 Front Matter

name
traceability-review
description
Review explicit architecture traceability metadata for gaps, inconsistencies, unsupported claims, stale links, dangling references, and metamodel violations. Use when Codex needs to inspect artifact relations, validate ADR-to-risk or quality-scenario coverage, propose relation updates, or produce an evidence-backed traceability review report.

03 SKILL.md 正文

Traceability Review Skill

Purpose

Review explicit architecture traceability metadata for gaps, inconsistencies, and unsupported claims. Treat every AI-suggested relation, finding, and impact claim as proposed until a human reviewer accepts it in the repository.

This skill is guidance and reusable content only. Do not implement AI execution, do not implement a generator, and do not add automation as part of using this skill.

Apply the repository contract hierarchy: this skill narrows AGENTS.md, and AGENTS.md adapts general-semantic-contracts.md. Do not duplicate general metadata, anchor, Docs-as-Code, arc42, or traceability rules here unless the traceability review workflow needs a stricter rule.

Core Workflow

  1. Inspect the requested documentation scope before writing findings.
  2. Read artifact metadata and relation metadata from repository source files.
  3. Inspect the relevant AsciiDoc prose only to verify relation rationale, visible references, anchors, and evidence.
  4. Inspect relevant source code, tests, configuration, or operational evidence only when relation claims depend on those artifacts.
  5. Validate relation endpoints, relation types, ownership, status, rationale, and review state against the metamodel.
  6. Compare explicit metadata relations with visible AsciiDoc xref links when both are expected.
  7. Identify missing, weak, stale, dangling, conflicting, or unsupported relations.
  8. Propose relation additions or changes as proposed; do not silently create accepted relations.
  9. Update affected artifacts with outgoing relations only when the user requested edits. Never create reciprocal incoming relations; they are derived automatically during generation.
  10. Prefer deterministic ordering by source ID, relation type, target ID, then rationale.
  11. Prefer small, reviewable patches.
  12. Run the repository validator after changes if one is available.

Required Reading

Read these references as needed:

  • ../../src/docs/arc42/04-solution-strategy/doc-04001-metamodel.adoc before reviewing artifact metadata, artifact types, lifecycle states, or relation semantics.
  • ../references/metadata-rules.md before reviewing YAML front matter.
  • ../references/relation-rules.md before proposing or updating relations.
  • ../references/adr-writing-guide.md before reviewing ADR relations.
  • ../references/risk-writing-guide.md before reviewing risk relations.
  • ../references/quality-scenario-guide.md before reviewing quality scenario relations.

Use these templates:

  • ../../templates/impact-report.adoc for review reports when the user wants analysis without direct artifact changes.

Inputs

  • Artifact metadata conforming to metamodel/artifact.schema.yaml.
  • Relation metadata conforming to metamodel/relations.schema.yaml.
  • Relevant AsciiDoc source documents.
  • Review focus, such as ADR-to-risk coverage or quality-scenario coverage.
  • Optional evidence sources, such as code, tests, configuration, deployment files, issue references, or operational data.
  • Review scope: report-only, update proposed relations, or validate a changed artifact set.

Output

Produce a review report with:

  • Missing or weak relations.
  • Stale, dangling, or conflicting relations.
  • Suggested relation additions marked as proposed.
  • Questions for human reviewers.
  • Validation notes against the metamodel.

Inspection Rules

  • Prefer reviewed repository source files over conversational memory.
  • Do not load derived output as evidence or architecture context. This includes generated/, build/, dist/, target/, out/, rendered HTML/PDF, generated indexes, traceability views, and assembled documentation.
  • Treat explicit metadata as authoritative over inferred prose.
  • Treat visible xref links as documentation references, not as substitutes for metadata relations when traceability is required.
  • Check the artifact and relation schemas before declaring a relation invalid.
  • Check existing artifact IDs before suggesting new IDs.
  • Never add reciprocal relations. Incoming relations are derived from outgoing relations during generation.
  • Preserve accepted or reviewed relations unless repository evidence justifies a proposed update.

Output Rules

  • Do not silently create accepted relations.
  • Identify dangling references by stable ID.
  • Mark AI-suggested additions as status: proposed and reviewed: false.
  • Prefer precise relation types over relates_to.
  • Prefer deterministic ordering by source ID, relation type, target ID, then rationale.
  • Keep findings actionable and evidence-backed.
  • Check metadata, relation, anchor, and xref rules from general-semantic-contracts.md.

Review Checklist

  • All relation endpoints exist.
  • Relation types match the intended semantics.
  • Accepted relations have evidence or rationale.
  • AI-suggested additions are not marked as reviewed.
  • Visible references to documentation artifacts use valid anchor-based AsciiDoc xref links where required.
  • Visible references use the explicit target anchors from source files, not raw numbered chapter file names.
  • Open questions identify the human decision needed to resolve each uncertain relation.

Validation

After edits, run the repository validator if available. Prefer existing commands from the repository documentation or scripts. If no validator exists, report that validation was not available and describe the manual checks performed.

04 同仓库更多 Skills

docs-as-code-toolkit
docs-as-code-toolkit/architecture-knowledge-toolkit

slice-issues

Slice GitHub parent issues into reviewable real sub-issues. Use when Codex is asked to split, slice, decompose, refine, or plan a GitHub issue into child issues, sub-issues, implementation slices, or reviewable follow-up issues before implementation work begins.

★ 4
docs-as-code-toolkit
docs-as-code-toolkit/architecture-knowledge-toolkit

risk

Create proposed architecture risk artifacts and analyze their traceability to ADRs, quality scenarios, requirements, components, controls, and evidence. Use when Codex needs to identify, draft, update, prioritize, or review architecture risks, separate risks from issues and decisions, propose mitigations, or produce a risk impact report without deciding acceptance.

★ 4
docs-as-code-toolkit
docs-as-code-toolkit/architecture-knowledge-toolkit

quality-scenario

Create proposed quality scenarios and analyze their traceability to quality objectives, ADRs, risks, requirements, architecture artifacts, and code evidence. Use when Codex needs to draft or update measurable quality scenarios, inspect existing arc42 Chapter 10 quality requirements, derive scenarios from source evidence without inventing targets, propose metadata relations, or produce a quality scenario impact report.

★ 4
docs-as-code-toolkit
docs-as-code-toolkit/architecture-knowledge-toolkit

presentation

Create or update docs-as-code presentation material as AsciiDoc reveal.js decks rendered with docs-toolbox. Use when Codex needs to prepare talks, meetup or conference proposals, speaker notes, demo scripts, event-specific artifacts under talks/, or slide decks that must remain repository-native rather than PowerPoint or Google Slides files.

★ 4
docs-as-code-toolkit
docs-as-code-toolkit/architecture-knowledge-toolkit

pr-review

Review GitHub pull requests and proposed branch changes for correctness, regressions, missing tests, documentation-contract violations, traceability gaps, and reviewability. Use when an AI assistant is asked to review a PR, review pull request changes, inspect a PR branch before merge, or produce PR review comments.

★ 4
docs-as-code-toolkit
docs-as-code-toolkit/architecture-knowledge-toolkit

post-merge-sync

Synchronize a local checkout after a pull request has been integrated: verify a clean worktree, switch to the base branch, fast-forward from the remote, confirm the PR changes are present, and clean up local and remote PR branches when safe. Use when an agent is asked to clean up after an integrated PR or return the repository to the latest base branch.

★ 4