DavidROliverBA/.claude/skills/adr

/adr

Create a new Architecture Decision Record (ADR) following the official YourOrg ADR process.

Usage

/adr <title>
/adr <title> for <project>

Examples

/adr API Gateway Selection
/adr Kafka vs EventBridge for Project - MyDataIntegration
/adr Standalone Laptop for Offline Database Build

Instructions

1. Parse Command and Initial Setup

Parse the command for:

• title: The ADR name (required)
• project: Related project (optional)

2. Discover Relevant Organisational ADRs

IMPORTANT: Before creating a new ADR, search for existing organisational ADRs that may constrain or inform this decision.

Search the vault for relevant ADRs:

1. Search +Sync/Org-ADRs/ for ADRs with authority: organizational
2. Search vault root for ADRs with status: accepted
3. Look for keywords matching the decision topic

Display found ADRs to the user:

📋 Relevant Organisational ADRs Found:

**Must Follow** (authority: organizational):
- [[ADR - API Gateway Selection]] - Mandates Kong for API management
- [[ADR - Cloud Provider Selection]] - Requires AWS for new services

**Consider** (authority: team, related domain):
- [[ADR - Kafka Event Patterns]] - Event-driven patterns for integration
- [[ADR - Data Product Standards]] - Data exchange formats

Would you like to reference any of these in your new ADR's `dependsOn` field?

Store selected references for later inclusion in frontmatter.

3. Check for Existing Guardrail

CRITICAL STEP: Before creating an ADR, check if a relevant guardrail already exists.

Ask the user:

"Before creating this ADR, have you checked if there's an existing guardrail that covers this decision? If a guardrail exists, you should follow it instead of creating an ADR."

If user confirms no guardrail exists, proceed to step 4.

4. Determine ADR Type

Ask the user to select the ADR type (explain each):

Question: "What type of ADR is this?"

Options:

1. Technology_ADR - New technology/tool or significant change to existing technology

   • Examples: New database, cloud service, development tool, infrastructure component
   • Requires SME approvals for the specific technology area

2. Architecture_ADR - New guardrail, pattern, or standard

   • Examples: New architectural pattern, coding standard, design principle
   • Creates organizational standard - highest approval level required
   • Becomes future guardrail

3. Local_ADR - Following existing guardrails

   • Examples: Team-level decision within established patterns
   • Local architecture process only - minimal approvals

Store the selected type in adrType frontmatter field.

5. Identify Required Approvers

Based on the ADR type and subject area, identify required approvers using [[Page - YourOrg ADR Approvers and SME (Official)]].

Core Assessors (Always Required):

• Head of Architecture or Engineering
• Principal Solution Architect (if not already involved)
• Cyber Assurance (Security Lead or delegate)

Ask the user: "What subject areas does this ADR cover?"

Common Subject Areas (select all that apply):

• Application Database/Storage (Database SME / Integration Lead)
• Application Integration (Integration SME / Integration Lead)
• AI (AI/ML Lead / AI Architect)
• Cloud (AWS/Azure/GCP) (Cloud Architect / Cloud Lead)
• Data Products/Integration (Data Product Owner / Data Architect)
• Data Platform (Data Platform Lead / Data Architect)
• Data Privacy (Privacy Officer / [email protected])
• PC Hardware/Software (Endpoint Lead / Desktop Architect)
• Mobile (iOS/Android) (Mobile Lead / Mobile Architect)
• Networks (Network Architect / Network Lead)
• Cyber (Security Lead)
• IT Operations (Operations Manager / Service Delivery Lead)
• Software Engineering/DevSecOps (Engineering Lead / DevOps Architect)
• Power Platform (Low-Code Lead / Platform Owner)

Build the complete approvers list from Core + Subject-Specific SMEs.

6. Gather ADR Content

Ask the user for key information using the official YourOrg ADR template structure:

Context Questions:

1. Background: What is the architectural context? What problem led to this decision?
2. Problem Statement: What is the specific problem or requirement? What are the constraints?
3. Goals: What are the desired outcomes?

Alternatives Questions:

1. What alternatives did you consider? (minimum 2, recommend 3-5)
2. For each alternative:
   • Description
   • Pros
   • Cons
   • Fit with requirements
   • Why was it rejected?

Decision Questions:

1. What is the decision? (clear, specific statement)
2. Why this decision? (rationale)
3. How does this address the problem?

Consequences Questions:

1. Positive impacts: What are the benefits?
2. Negative impacts: What are the drawbacks or risks?
3. Mitigation strategies: How will you address negative consequences?

Implementation Questions:

1. Cost model: What are the costs (one-time, recurring)?
2. Deployment approach: How will this be implemented?
3. Operational model: How will this be operated and supported?
4. Migration/rollout: What are the phases?

Compliance Questions:

1. GDPR compliance: Does this process personal data?
2. Security classification: What data classification (Official, Official-Sensitive)?
3. Audit requirements: What audit/traceability is needed?

7. Create the ADR

Generate filename: ADR - {{title}}.md

Create the ADR in vault root using the structure from +Templates/ADR.md:

Frontmatter:

---
type: Adr
title: {{title}}
description: {{one-line summary}}
status: draft
adrType: {{Technology_ADR | Architecture_ADR | Local_ADR}}
tags: [ADR, architecture, {{additional relevant tags}}]
created: {{DATE}}
modified: {{DATE}}
deciders: [Engineering Architecture Team, {{project team if applicable}}]
approvers:
  # Core Assessors (Required)
  - Head of Architecture or Engineering
  - Principal Solution Architect
  - Cyber Assurance (Security Lead or delegate)
  # Subject-Specific SMEs (from user selections)
  {{list of SME approvers based on subject areas}}
  # Stakeholders
  {{project stakeholders if applicable}}
project: {{project_link or null}}
jiraTicket: null  # To be added when JIRA ticket created

# Source/Provenance
source: local                         # local | confluence
sourcePageId: null                    # Confluence page ID (once published)
sourceSpace: null                     # Confluence space key
sourceUrl: null                       # Link to authoritative version
sourceVersion: null                   # Version number

# Publication
isPublished: false                    # Updated when published to Confluence
publishedDate: null                   # YYYY-MM-DD
publishedUrl: null                    # Confluence URL

# Authority Level
authority: draft                      # draft → local → team → organizational

# Relationships
relatedTo: []
supersedes: []
dependsOn: {{selected_dependencies_from_discovery_step}}

# Quality Indicators
confidence: medium
freshness: current
verified: false
reviewed: {{DATE}}

# Context
summary: {{one-line summary}}
assumptions: []
stakeholders: {{list from approvers}}
---

Content: Use official YourOrg ADR template structure with all sections filled in from user responses.

Include at the top:

> **Based on Official YourOrg ADR Template**: [[Page - YourOrg ADR Template (Official)]]
>
> **ADR Process**: [[Page - YourOrg ADR Process (Official)]]
>
> **Required Approvers**: [[Page - YourOrg ADR Approvers and SME (Official)]]

8. Provide Next Steps Guidance

After creating the ADR, display:

✅ ADR created: ADR - {{title}}.md

📋 Next Steps (Official YourOrg ADR Process):

1. ⏳ REVIEW ADR CONTENT
   - Review all sections for completeness
   - Ensure alternatives are well-documented
   - Verify approvers list is correct

2. ⏳ CREATE JIRA TICKET (CRITICAL - ADR not complete without this)
   - Project: {{user's project or ARCH}}
   - Issue Type: ADR
   - Label: "{{adrType}}"
   - Summary: "ADR - {{title}}"
   - Link this ADR document to JIRA ticket

3. ⏳ ADD APPROVERS IN JIRA
   Use '@' function in Jira to add:
   {{list all approvers from frontmatter}}

4. ⏳ CREATE/LINK CONFLUENCE PAGE
   - Create Confluence page with ADR content
   - Link Confluence page to JIRA ticket

5. ⏳ UPDATE ADR STATUS
   - After JIRA ticket created, update status: draft → proposed
   - Add JIRA ticket reference to frontmatter

6. ⏳ STAKEHOLDER REVIEW
   - Approvers review in Jira
   - Discussion via Jira comments
   - All approvers must agree

7. ⏳ ADR ACCEPTANCE
   - All approvals confirmed in Jira
   - Update status: proposed → accepted

8. ⏳ POST-APPROVAL
   - Close JIRA ticket
   - Tidy Confluence page
   - Add appropriate labels

9. ⏳ PUBLISH TO CONFLUENCE (Final Step)
   - Create Confluence page with ADR content
   - Update vault ADR frontmatter:
     - isPublished: true
     - publishedDate: {{today}}
     - publishedUrl: {{confluence URL}}
     - authority: team (or organizational if it becomes a guardrail)
     - status: accepted

🔄 Authority Progression:
- draft → ADR being created (local work)
- local → Personal decision, not yet shared
- team → Approved by team, in Confluence
- organizational → Company-wide standard/guardrail

📚 References:
- [[Page - YourOrg ADR Process (Official)]] - Full process documentation
- [[Page - YourOrg ADR Approvers and SME (Official)]] - Approvers reference
- [[Page - YourOrg ADR Template (Official)]] - Template structure

⚠️ REMEMBER: ADRs are not complete until JIRA ticket is raised!

9. Create Associated Task (Optional)

Ask the user: "Would you like me to create a task to track this ADR through the approval process?"

If yes, create a task: Task - Create ADR - {{title}}.md with:

• Checklist of all workflow steps above
• Due date (ask user)
• Project reference
• Links to ADR, official process docs

Important Notes

1. JIRA Ticket is Mandatory: Always emphasize that ADR is not complete without JIRA ticket
2. Official Process: Always reference the official YourOrg ADR process documentation
3. Approvers are Required: Must identify and document required approvers before proceeding
4. Confluence Integration: ADRs live in Confluence with JIRA as anchor
5. Status Progression: draft → proposed (after JIRA) → accepted (after approvals)
6. Three ADR Types: Technology_ADR (most common), Architecture_ADR (new guardrail), Local_ADR (within guardrails)

Error Handling

• If user skips checking for existing guardrail, remind them this is required
• If user cannot identify appropriate approvers, suggest reviewing [[Page - YourOrg ADR Approvers and SME (Official)]]
• If ADR type is unclear, explain each type with examples
• If user wants to skip JIRA ticket, explain it's mandatory per official process

Reference Documentation

All guidance based on:

• [[Page - YourOrg ADR Process (Official)]]
• [[Page - YourOrg ADR Approvers and SME (Official)]]
• [[Page - YourOrg ADR Template (Official)]]