ADR Suggestion Skill

When you detect an architectural decision being made, gently suggest documenting it.

What Qualifies as ADR-Worthy

Decisions that:

• Affect multiple parts of the codebase
• Are difficult or costly to reverse
• Involve trade-offs between competing concerns
• Establish patterns that future code should follow
• Change how the system behaves architecturally

What Does NOT Need an ADR

• Bug fixes
• Minor refactoring
• Adding features within existing patterns
• Routine dependency updates
• Code style changes

How to Suggest

After completing significant architectural work, suggest:

This change introduces [pattern/technology/approach]. Consider documenting this decision with an ADR to capture the context and reasoning. You can run /adr:create to create one.

Suggestion Guidelines

• Suggest once per decision, not repeatedly
• Frame as optional, not required
• Only suggest after the work is done, not before
• Include what makes this ADR-worthy (e.g., "introduces a new caching layer")
• Keep suggestions brief - one sentence plus the command reference