traceability-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

From docs-as-code-toolkit/architecture-knowledge-toolkit, MIT.

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