Model Doc Sync

Model README and Docs Sync

Use this skill when updating model documentation, benchmark tables, sample-result images, or docs reference pages for an anomalib model.

Purpose and scope

Use this skill to keep model READMEs, docs pages, images, and benchmark/sample references aligned.

Request changes when

• a model README changes but the matching docs page is left stale;
• image references point to missing assets;
• benchmark tables do not match committed artifacts;
• sample-result sections imply coverage that the repo does not actually contain.

Keep these surfaces aligned

• src/anomalib/models/**/README.md
• docs/source/markdown/guides/reference/models/**
• docs/source/images/**
• benchmark and run artifacts under results/

Canonical repo paths

Model READMEs

• Image model READMEs usually live at src/anomalib/models/image/<model>/README.md.
• Video model READMEs may live at src/anomalib/models/video/<model>/README.md.
• There are also category-level READMEs such as src/anomalib/models/image/README.md and src/anomalib/models/video/README.md.

Model docs pages

• Image model docs pages usually live at docs/source/markdown/guides/reference/models/image/<model>.md.
• Video model docs pages usually live at docs/source/markdown/guides/reference/models/video/<model>.md.
• Keep docs/source/markdown/guides/reference/models/**/index.md up-to-date.
• The docs pages should also contain architecture image and description.

Image assets

• Model images typically live at docs/source/images/<model>/.
• Common patterns include architecture.* and results/0.png, results/1.png, results/2.png.
• Some models use nonstandard names or multiple architecture images, for example docs/source/images/cs_flow/.

Result artifacts

• Measured artifacts may exist under results/<ModelName>/....
• Treat results/ as evidence for benchmark/sample claims, not as a place to invent values from partial runs.

Required workflow

1. Inspect before editing

For the target model:

1. Read the model README.
2. Read the matching docs page if it exists.
3. Inspect docs/source/images/<model>/ or the repo-specific variant actually used.
4. Check whether measured artifacts already exist in results/.
5. Check whether referenced sample-result images exist and are still valid.

Never update only one of README or docs when both exist.

2. Keep these sections synchronized

If present in the README, verify that the docs page and assets do not contradict it:

• title and model name
• description
• architecture section and image references
• usage section
• benchmark section
• sample results section
• TODO notes about missing benchmarks or images

Docs pages do not need to duplicate the full README, but they must stay consistent with it.

3. Benchmark update rules

• Prefer the repository's existing benchmarking workflow, starting with tools/experimental/benchmarking/.
• Use measured results only.
• Source values from committed artifacts such as files under results/.
• Do not fabricate averages, rows, or per-category scores.
• If only part of the benchmark is complete, fill only the supported values and leave the rest clearly blank or TODO.
• If benchmarking is still in progress, say so explicitly.

4. Sample image rules

• Only add sample-result images from completed model outputs.
• Confirm the referenced output is not degenerate or misleading.
• Do not publish obviously broken masks, empty masks, NaN-driven outputs, or placeholder images as final examples.
• Copy or export valid final images into the matching docs/source/images/... location.
• If fewer than three valid sample images exist, use a precise TODO note instead of broken links or bad examples.