Architecture Decision Records (ADR) FAQs

Question 1

Does this skill help maintain the main ARCHITECTURE.md file?

Accepted Answer

Yes, during the Merge phase, the skill automatically updates the Key Decisions table in your ARCHITECTURE.md to ensure the living documentation reflects the latest decisions.

Question 2

What is the 4-phase ADR lifecycle?

Accepted Answer

The lifecycle consists of Research (verifying external dependencies), Draft (writing prose and performing critiques), Hold (waiting for explicit human authorization), and Merge (finalizing the record and updating architecture docs).

Question 3

Can I skip the Research phase if I already know what I want?

Accepted Answer

No, this skill enforces a 'research-before-writing' constraint. It requires documented evidence of dependency behavior to prevent decisions based on stale assumptions.

Question 4

Why does this skill create CLAUDE.md and AGENTS.md files?

Accepted Answer

These guard files act as instructions for AI agents, preventing them from treating historical ADR reasoning as current implementation directives and redirecting them to the main ARCHITECTURE.md.

Question 5

What happens if a reviewer doesn't respond during the HOLD phase?

Accepted Answer

This skill operates on a 'silence is not consent' policy. Explicit authorization is required to move from the HOLD phase to MERGE; silence or lack of feedback blocks the process.

Architecture Decision Records (ADR)

Architecture Decision Records (ADR)

Key Features

Use Cases

Key Features

Use Cases