Architecture Decision Record Summarization

Overview

This skill covers summarizing Architecture Decision Records (ADRs) in ServiceNow Enterprise Architecture:

• Retrieving and parsing ADR content including context, decision, rationale, and consequences
• Correlating ADRs with related business applications and technology standards
• Analyzing trade-offs documented across multiple ADRs
• Generating executive-level summaries with impact assessments
• Identifying decision patterns and potential conflicts between ADRs
• Linking ADRs to enterprise architecture diagrams and roadmaps

When to use: When stakeholders need consolidated views of architecture decisions, during architecture reviews, compliance audits, or when evaluating the impact of proposed changes on existing decisions.

Prerequisites

• Roles: ea_admin, ea_viewer, or admin
• Access: sn_ea_architecture_decision_record, cmdb_ci_business_app, sn_ea_tech_standard, sn_ea_diagram tables
• Plugins: Enterprise Architecture (com.snc.enterprise_architecture) must be activated
• Knowledge: ADR format (context, decision, status, consequences), enterprise architecture concepts
• Related Skills: Complete ea/business-app-insights for application-level context

Procedure

Step 1: Discover the ADR Table Schema

Before querying, understand the table structure.

Using MCP:

Tool: SN-Get-Table-Schema
Parameters:
  table_name: sn_ea_architecture_decision_record

Using REST:

GET /api/now/table/sn_ea_architecture_decision_record?sysparm_limit=1
Accept: application/json

Key Fields:

Field	Description
number	ADR number identifier
title	Decision title
status	Current status (proposed, accepted, deprecated, superseded)
context	Business or technical context driving the decision
decision	The architecture decision made
rationale	Reasoning behind the decision
consequences	Expected outcomes and trade-offs
business_application	Related business application reference
technology_standard	Associated technology standard
created_by	Decision author
sys_created_on	Creation date
sys_updated_on	Last modification date

Step 2: Query Architecture Decision Records

Retrieve all active ADRs:

Using MCP:

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: status=accepted^ORstatus=proposed
  fields: sys_id,number,title,status,context,decision,rationale,consequences,business_application,technology_standard,sys_created_on,sys_updated_on
  limit: 100

Using REST:

GET /api/now/table/sn_ea_architecture_decision_record?sysparm_query=status=accepted^ORstatus=proposed&sysparm_fields=sys_id,number,title,status,context,decision,rationale,consequences,business_application,technology_standard,sys_created_on,sys_updated_on&sysparm_limit=100
Accept: application/json

Filter ADRs by business application:

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: business_application=[app_sys_id]
  fields: sys_id,number,title,status,decision,rationale,consequences
  limit: 50

Filter ADRs by date range:

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: sys_created_on>=javascript:gs.dateGenerate('2025-01-01','00:00:00')^status=accepted
  fields: sys_id,number,title,status,decision,consequences
  limit: 100

Step 3: Retrieve Related Context

Get associated business application details:

Tool: SN-Query-Table
Parameters:
  table_name: cmdb_ci_business_app
  query: sys_id=[business_application_sys_id]
  fields: sys_id,name,short_description,business_criticality,lifecycle_stage,owned_by,managed_by

Get related technology standards:

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_tech_standard
  query: sys_id=[tech_standard_sys_id]
  fields: sys_id,name,status,description,category,lifecycle_stage

Get associated architecture diagrams:

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_diagram
  query: business_application=[app_sys_id]
  fields: sys_id,name,description,diagram_type,sys_updated_on
  limit: 20

Step 4: Analyze Trade-offs and Conflicts

For each ADR, extract and categorize:

1. Positive consequences - Benefits and advantages stated in the consequences field
2. Negative consequences - Risks, limitations, and costs acknowledged
3. Dependencies - Other systems or decisions referenced
4. Constraints - Technical or business constraints mentioned in the context

Identify potentially conflicting decisions:

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: status=accepted^technology_standard=[same_standard_sys_id]
  fields: sys_id,number,title,decision,consequences
  limit: 50

Step 5: Generate the Summary

Structure the ADR summary with these sections:

1. Decision Overview - Title, status, date, author
2. Context Summary - Condensed version of the business/technical context
3. Decision Statement - The core decision in one to two sentences
4. Rationale Highlights - Key reasons supporting the decision
5. Trade-off Analysis - Pros vs. cons matrix
6. Impact Assessment - Affected applications, standards, and teams
7. Related Decisions - Links to related or superseded ADRs
8. Recommendations - Suggested follow-up actions or reviews

Step 6: Store the Summary (Optional)

Update ADR with generated summary:

Tool: SN-Update-Record
Parameters:
  table_name: sn_ea_architecture_decision_record
  sys_id: [adr_sys_id]
  data:
    work_notes: |
      AI-Generated Summary (as of YYYY-MM-DD):

      Decision: [condensed decision statement]

      Key Trade-offs:
      + [positive consequence 1]
      + [positive consequence 2]
      - [negative consequence 1]
      - [negative consequence 2]

      Impact: Affects [N] business applications
      Related Standards: [standard names]

      Recommendation: [follow-up action]

Using REST:

PATCH /api/now/table/sn_ea_architecture_decision_record/[adr_sys_id]
Content-Type: application/json
{
  "work_notes": "AI-Generated Summary: ..."
}

Tool Usage

Tool	Purpose
SN-Get-Table-Schema	Discover ADR table fields and relationships
SN-Query-Table	Retrieve ADRs, applications, standards, and diagrams
SN-Get-Record	Get detailed single ADR with all fields
SN-Update-Record	Store generated summaries back to ADR records
SN-Create-Record	Create new summary records or tasks

Best Practices

• Batch by domain: Summarize ADRs grouped by business domain or application for coherent narratives
• Preserve original language: When quoting rationale, keep the original phrasing to avoid misrepresentation
• Flag stale decisions: Highlight ADRs not reviewed in over 12 months for potential re-evaluation
• Cross-reference standards: Always check whether referenced technology standards are still active
• Version tracking: Note the sys_updated_on date to indicate summary freshness
• Stakeholder context: Tailor summary depth based on audience (executive vs. technical)
• Conflict detection: When summarizing multiple ADRs, actively look for contradictory decisions
• Include superseded history: When an ADR supersedes another, include the chain of decisions

Troubleshooting

No ADRs Returned from Query

Symptom: Query returns empty result set Causes:

1. Enterprise Architecture plugin not activated
2. No ADRs created in the instance
3. Insufficient permissions Solution:

Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: ORDERBYDESCsys_created_on
  fields: sys_id,number,title,status
  limit: 5

Missing Business Application References

Symptom: business_application field is empty on ADRs Cause: ADRs created without linking to business applications Solution: Query cmdb_ci_business_app separately and correlate by name or description keywords

ADR Content Fields Are Empty

Symptom: context, decision, or rationale fields return blank Cause: ADRs may use custom fields or journal fields Solution: Check table schema for custom columns or use work_notes/comments fields

Tool: SN-Get-Table-Schema
Parameters:
  table_name: sn_ea_architecture_decision_record

Permission Denied Errors

Symptom: 403 or insufficient privileges error Cause: User lacks ea_viewer or ea_admin role Solution: Verify role assignment or request elevated access

Examples

Example 1: Summarize a Single ADR

# Step 1: Get the ADR
Tool: SN-Get-Record
Parameters:
  table_name: sn_ea_architecture_decision_record
  sys_id: abc123def456

# Result contains:
#   title: "Adopt Kubernetes for Container Orchestration"
#   status: "accepted"
#   context: "Our microservices deployment requires automated scaling..."
#   decision: "Adopt Kubernetes as the standard container orchestration platform..."
#   rationale: "Kubernetes provides auto-scaling, self-healing, and wide ecosystem..."
#   consequences: "Requires team training, increases infrastructure complexity..."

# Step 2: Get related application
Tool: SN-Query-Table
Parameters:
  table_name: cmdb_ci_business_app
  query: sys_id=[business_application_value]
  fields: name,business_criticality,lifecycle_stage

# Step 3: Generate summary output:
# ADR-0042: Adopt Kubernetes for Container Orchestration
# Status: Accepted | Created: 2025-06-15
# Application: Cloud Platform Services (Business Critical)
#
# Context: Microservices architecture requires automated container management
# Decision: Standardize on Kubernetes for all container orchestration
#
# Trade-offs:
# + Auto-scaling and self-healing capabilities
# + Large ecosystem and community support
# - Requires significant team training investment
# - Increases infrastructure complexity
#
# Impact: Affects 12 microservices across 3 business applications

Example 2: Batch Summarize ADRs by Domain

# Step 1: Get all ADRs for a specific business domain
Tool: SN-Query-Table
Parameters:
  table_name: sn_ea_architecture_decision_record
  query: status=accepted^contextLIKEcloud^ORtitleLIKEcloud
  fields: sys_id,number,title,status,decision,consequences,sys_created_on
  limit: 50

# Step 2: For each ADR, fetch related records and build consolidated summary
# Step 3: Output a domain-level summary with decision timeline and dependency map

Related Skills

• ea/business-app-insights - Application health and dependency analysis
• genai/app-summary - Scoped application analysis
• security/audit-compliance - Compliance implications of architecture decisions
• cmdb/relationship-mapping - Understanding CI dependencies affected by ADRs