Skill: Architecture Decision Record (ADR) Generation

Purpose

Create Architecture Decision Records to document significant technical decisions.

When to Use

• New technology or framework being introduced
• Significant architectural change
• Decision with long-term implications
• Trade-off between competing approaches
• Decision that future developers will question

MCP Tools Used

Tool	Purpose
Atlassian:createConfluencePage	Create ADR page
Atlassian:searchConfluenceUsingCql	Find existing ADRs for numbering
Atlassian:getConfluencePage	Read existing ADRs

Configuration

{
  "cloudId": "{{confluence.cloudId}}",
  "spaceId": "{{confluence.spaceId}}",
  "spaceKey": "{{confluence.spaceKey}}",
  "prefix": "{{documentation.adrPrefix}}"
}

ADR Template

# ADR-{{number}}: {{title}}

## Status

**{{status}}**

_Proposed | Accepted | Deprecated | Superseded by [ADR-XX]_

## Date

{{date}}

## Context

[Describe the issue motivating this decision. What is the problem? What constraints exist? What forces are at play?]

## Decision

[State the decision clearly. What are we going to do?]

## Consequences

### Positive

- [Benefit 1]
- [Benefit 2]
- [Benefit 3]

### Negative

- [Drawback 1]
- [Drawback 2]

### Neutral

- [Side effect that is neither clearly positive nor negative]

## Alternatives Considered

### {{Alternative 1 Name}}

**Description:** [What is this alternative?]

**Pros:**
- [Advantage 1]
- [Advantage 2]

**Cons:**
- [Disadvantage 1]
- [Disadvantage 2]

**Why Not Chosen:** [Specific reason this was rejected]

### {{Alternative 2 Name}}

...

## Related

- **Jira:** [PROJECT-XX] - Related story/epic
- **ADRs:** [ADR-XX] - Related decisions
- **Specs:** [Link to technical spec]

## References

- [External documentation, articles, or resources consulted]

Example: Create ADR

// First, find existing ADRs to determine next number
const search = await Atlassian:searchConfluenceUsingCql({
  cloudId: "{{confluence.cloudId}}",
  cql: "space = '{{confluence.spaceKey}}' AND title ~ 'ADR-*' ORDER BY created DESC",
  limit: 1
});

// Determine next number (e.g., ADR-016)
const nextNumber = /* parse from results */;

// Create the ADR
Atlassian:createConfluencePage({
  cloudId: "{{confluence.cloudId}}",
  spaceId: "{{confluence.spaceId}}",
  title: "ADR-016: Use PostgreSQL for Primary Database",
  body: `# ADR-016: Use PostgreSQL for Primary Database

## Status

**Accepted**

## Date

2025-01-06

## Context

We need to select a primary database for the Restaurant SaaS platform. Requirements include:
- Multi-tenant data isolation
- Strong ACID compliance for financial transactions
- JSON support for flexible menu structures
- Horizontal scalability for growth
- Cost-effective managed hosting options

Current team has experience with SQL Server and MySQL.

## Decision

We will use **PostgreSQL** as our primary database, hosted on a managed service (e.g., AWS RDS, Azure Database for PostgreSQL).

## Consequences

### Positive

- Excellent JSON/JSONB support for flexible schemas
- Strong multi-tenancy patterns (row-level security, schemas)
- Open source - no licensing costs
- Extensive ecosystem and community
- Best-in-class ACID compliance

### Negative

- Team needs PostgreSQL-specific training
- Different syntax from SQL Server for some operations
- Migration from any existing SQL Server code

### Neutral

- Performance comparable to other RDBMS for our scale
- Will need to establish new backup/maintenance procedures

## Alternatives Considered

### SQL Server

**Description:** Microsoft's enterprise RDBMS

**Pros:**
- Team familiarity
- Excellent tooling (SSMS)
- Strong Azure integration

**Cons:**
- Licensing costs at scale
- Less flexible JSON support
- Vendor lock-in

**Why Not Chosen:** Licensing costs would be significant as we scale to multiple restaurant clients.

### MySQL

**Description:** Popular open-source RDBMS

**Pros:**
- Free and open source
- Wide hosting availability
- Simple to operate

**Cons:**
- Weaker JSON support than PostgreSQL
- Less robust for complex queries
- Fewer advanced features

**Why Not Chosen:** PostgreSQL's superior JSON support and advanced features better fit our needs.

## Related

- **Jira:** MDDEV-12 - Database selection task
- **Specs:** [Database Architecture Spec]

## References

- [PostgreSQL Multi-tenancy Patterns](https://example.com)
- [PostgreSQL vs MySQL Comparison](https://example.com)`
})

Used By Agents

• Software Architect - Primary author of ADRs
• Senior Developer - May propose ADRs for implementation decisions
• Engineering Manager - Reviews and tracks ADR status