ADR Verify is a crucial tool designed for developers and teams managing Architecture Decision Records (ADRs). It acts as a companion to adr-index, providing essential checks on the integrity of your ADR graph after it has been populated. By reading the persisted graph, ADR Verify surfaces potential issues such as dangling references, supersede cycles, and status mismatches. This ensures that your ADR management remains reliable and that all references are valid and up-to-date.

The skill identifies three main types of integrity issues. First, it detects dangling references, which occur when an edge points to an ADR ID that does not exist in the adr-patterns. This often happens when an ADR is deleted or exists in a sibling repository. Second, it checks for supersede cycles, a critical issue where two or more ADRs reference each other as superseding, indicating data corruption. Lastly, ADR Verify flags status mismatches, where an ADR is the source of a supersede edge but does not have its own status updated accordingly.

To use ADR Verify effectively, it is recommended to run it immediately after adr-index to confirm that the graph is healthy. Additionally, it can be integrated into Continuous Integration (CI) pipelines as a fail-closed gate, ensuring that any integrity issues are caught before they can affect production. The skill also allows for optional configurations, such as outputting results in JSON format or enforcing strict verification that exits with an error code on any detected issue.

While ADR Verify is robust, it does have limitations. It cannot detect ADRs that have been deleted from disk without any references, which can lead to discrepancies in reported ADR counts. In such cases, running adr-reindex is necessary to reconcile these discrepancies. Overall, ADR Verify is an essential tool for maintaining the integrity of ADRs in any development environment.