#932·skills

Should agents review existing ADRs before creating or updating an ADR?

Author: bembem1011Created Aug 22, 2026Updated Sep 15, 2026

I have a question about the intended ADR workflow in grill-with-docs, domain-modeling, and setup-matt-pocock-skills.

From my understanding:

setup-matt-pocock-skills checks whether ADR directories exist and configures their locations. grill-with-docs delegates the documentation work to domain-modeling. domain-modeling checks whether a decision qualifies for an ADR and provides rules for creating one.

However, I could not find an explicit instruction requiring the agent to read relevant existing ADRs before proposing, creating, or updating an ADR.

I am concerned that an agent could:

Create an ADR that duplicates an existing decision. Propose something that conflicts with an active ADR. Directly change an accepted ADR when it should create a new ADR that supersedes the old one. Miss important architectural context recorded in an existing ADR.

I expected the workflow to be something like:

Find and read relevant existing ADRs. Compare the proposed decision with them. Decide whether the proposal follows, clarifies, conflicts with, or replaces an existing ADR. Update an existing ADR only for minor corrections or clarifications. For a material decision change, create a new ADR and mark the old one as superseded. Create a new ADR only when no existing ADR already covers the decision.

Was leaving this verification step out intentional? If so, could you explain the intended way for these skills to handle existing ADRs and changes to previous architectural decisions?

I would like to understand your design idea before suggesting any change. Thank you!