Architecture Decision Records

The problem

Engineering teams often lose the "why" behind critical architectural choices. Months later, developers struggle to understand why a specific database, framework, or communication protocol was chosen, leading to costly relitigation or brittle workarounds.

What it does

• Scans the repository to identify existing ADR patterns and determines the next sequence number.
• Analyzes codebase constraints, including manifests, lockfiles, and CI configurations.
• Drafts comprehensive Engineering Choice Records covering tradeoffs, rejected alternatives, and rollout plans.
• Generates actionable validation criteria and migration steps for implementers.
• Maintains a searchable history of decisions by linking related records and marking superseded notes.

Why this beats prompting it yourself

Generic prompts often produce shallow summaries that lack technical rigor or honest tradeoffs. This skill enforces a structured engineering discipline, ensuring every record includes concrete system impact estimates, ASCII diagrams, and specific rollback strategies that a standard LLM would likely omit.

Use cases

• Documenting the transition from REST to GraphQL for internal service communication.
• Justifying the selection of a specific state-management library in a frontend project.
• Recording the decision to move from local JSON storage to an embedded database like SQLite.
• Defining service boundaries and ownership during a monolith-to-microservices migration.

Known limitations

Requires an existing directory structure or permission to create one. Performance and cost impact estimates are based on provided context and not live telemetry.