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
- Inspect the requested documentation scope before writing findings.
- Read artifact metadata and relation metadata from repository source files.
- Inspect the relevant AsciiDoc prose only to verify relation rationale, visible references, anchors, and evidence.
- Inspect relevant source code, tests, configuration, or operational evidence only when relation claims depend on those artifacts.
- Validate relation endpoints, relation types, ownership, status, rationale, and review state against the metamodel.
- Compare explicit metadata relations with visible AsciiDoc
xreflinks when both are expected. - Identify missing, weak, stale, dangling, conflicting, or unsupported relations.
- Propose relation additions or changes as
proposed; do not silently create accepted relations. - Update affected artifacts with outgoing relations only when the user requested edits. Never create reciprocal incoming relations; they are derived automatically during generation.
- Prefer deterministic ordering by source ID, relation type, target ID, then rationale.
- Prefer small, reviewable patches.
- 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.adocbefore reviewing artifact metadata, artifact types, lifecycle states, or relation semantics.../references/metadata-rules.mdbefore reviewing YAML front matter.../references/relation-rules.mdbefore proposing or updating relations.../references/adr-writing-guide.mdbefore reviewing ADR relations.../references/risk-writing-guide.mdbefore reviewing risk relations.../references/quality-scenario-guide.mdbefore reviewing quality scenario relations.
Use these templates:
../../templates/impact-report.adocfor 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
xreflinks 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: proposedandreviewed: 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
xrefrules fromgeneral-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
xreflinks 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
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.
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.
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.
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.
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.
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.