| name | architecture-docs |
| description | Use this skill when creating, updating, or maintaining ARCHITECTURE.md files, when users ask about "my architecture documentation" or "architecture", when generating presentations/slides/PowerPoint from architecture documentation, when generating diagrams from architecture documentation, when validating/checking/auditing architecture (including BIAN alignment, META layers, standards compliance), or when answering questions about documented components, data structures, integrations, security, performance, deployment, technology stack, or architectural decisions |
Architecture Documentation Skill
This skill provides comprehensive guidelines for creating and maintaining ARCHITECTURE.md files using the standardized template from ARCHITECTURE_DOCUMENTATION_GUIDE.md.
When This Skill is Invoked
Automatically activate when:
- User asks to create architecture documentation
- User asks to update or edit ARCHITECTURE.md
- User mentions documenting system architecture
- User requests architecture review, audit, or analysis (triggers Design Drivers calculation prompt)
- User explicitly asks to "calculate design drivers" or "update design drivers"
- User asks about architecture documentation structure or best practices
- User edits Section 1 Executive Summary Key Metrics (triggers metric consistency check)
- User requests metric consistency check, verify metrics, or audit metrics
- User asks informational questions about the documented architecture (if ARCHITECTURE.md exists)
- "What is our [authentication/scaling/data flow/etc.] approach?"
- "How does [component/system/integration] work?"
- "What technologies do we use for [purpose]?"
- "Tell me about the architecture of [system]"
- User asks to generate, create, or add diagrams to architecture documentation (triggers Workflow 9)
- "Generate my architecture diagrams"
- "Create Mermaid diagrams from ARCHITECTURE.md"
- "Add diagrams to my architecture"
Query Pattern Triggers
This skill automatically activates when users ask questions about documented architecture, including:
Reference Patterns:
- "According to my architecture documentation..."
- "Based on the architecture..."
- "What does the architecture use/require/implement for..."
- "My architecture documentation shows/says..."
- "The architecture specifies/defines..."
- "Check/Validate/Verify the architecture [aspect]..."
- "Audit the [architecture component/pattern]..."
Technical Query Keywords:
- Components: "components", "services", "modules", "microservices", "systems"
- Data: "data structures", "data flow", "database", "schema", "models", "entities"
- Integration: "APIs", "integrations", "external systems", "endpoints", "interfaces"
- Security: "authentication", "authorization", "encryption", "security", "compliance"
- Performance: "scaling", "performance", "SLA", "capacity", "throughput", "latency"
- Deployment: "deployment", "cloud provider", "infrastructure", "environments", "regions"
- Technology: "tech stack", "languages", "frameworks", "tools", "libraries", "versions"
- Decisions: "why choose", "decision", "trade-offs", "alternatives", "ADR", "rationale"
- Validation: "check", "validate", "verify", "audit", "alignment", "BIAN", "META", "service domain", "layer", "standards", "compliance check"
Multi-section Queries:
- Questions requiring synthesis across multiple sections
- Cross-cutting concerns (e.g., "How does authentication work with external systems?")
- Implementation details spanning components, data, and deployment
🎯 AUTOMATIC WORKFLOW DETECTION
IMPORTANT: Immediately upon skill invocation, analyze the user's request to detect their intent.
Detection Logic
Check the user's original message (before /architecture-docs was invoked) for these patterns:
Workflow 8: Presentation Generation
Triggers:
- Keywords: "generate", "create", "make" + "presentation", "slides", "PowerPoint", "pptx", "deck", "markdown presentation"
- Examples: "generate presentations", "create slides", "make PowerPoint", "generate presentation MD"
- Stakeholder mentions: "business presentation", "architecture slides", "compliance deck"
- Language: "presentación en español", "slides in English"
Action when detected:
- Confirm: "I'll help you generate an architecture presentation Markdown file for Claude PowerPoint."
- Jump directly to Workflow 8, Step 1 (Stakeholder Type Selection)
- Do NOT ask which workflow - proceed automatically
Workflow 9: Diagram Generation
Triggers:
- Keywords: "generate", "create", "add", "update", "make" + "diagram", "diagrams", "Mermaid diagram", "architecture diagram"
- Examples: "generate my architecture diagrams", "create diagrams from ARCHITECTURE.md", "add diagrams to my architecture"
- Section-specific: "generate diagrams for Section 4", "create data flow diagrams"
- Format mentions: "Mermaid diagrams", "visual diagrams", "architecture diagrams"
Action when detected:
- Confirm: "I'll help you generate architecture diagrams."
- Jump directly to Workflow 9, Step 1 (Diagram Type Selection)
- Do NOT ask which workflow - proceed automatically
Other Workflows
If the user's request matches other documented workflows (1-7, 9-10), follow their respective trigger patterns.
If No Pattern Matches
If the user's request doesn't match any workflow triggers:
- Acknowledge the skill invocation
- Ask which workflow they want to use
- Provide brief description of available workflows
File Naming Convention
IMPORTANT: All architecture documents MUST be named ARCHITECTURE.md
- When creating a new architecture document, always use the filename:
ARCHITECTURE.md
- When updating existing architecture, work with the file:
ARCHITECTURE.md
- Do NOT use alternative names like: architecture.md, ARCH.md, system-architecture.md, etc.
- Each project/system should have ONE primary ARCHITECTURE.md file
Location
- Place ARCHITECTURE.md in the root of the project or in a
/docs directory
- For multi-project repositories, each project subdirectory gets its own ARCHITECTURE.md
Working with ARCHITECTURE.md - Context Optimization
IMPORTANT: When working with ARCHITECTURE.md, optimize for context by loading sections incrementally, NOT the entire document at once.
Context-Efficient Workflow
-
Initial Assessment
- Read ONLY lines 1-50 of ARCHITECTURE.md to locate the Document Index
- The Document Index provides exact line ranges for each section
- Use the index to plan which sections need work
- Identify which specific section(s) need work
-
Section-Based Editing
- Use the Document Index to find exact line ranges for your target section
- Use the Read tool with
offset and limit parameters to load ONLY the relevant section
- Add context buffer: Read ±10-20 lines beyond the section boundaries
- Work on one section at a time
- Example: Index shows Section 5 is lines 601-850, read lines 590-860 (with 10-line buffer)
-
Incremental Updates
- Make edits to individual sections using the Edit tool
- Avoid reading the full document unless absolutely necessary
- For multi-section updates, work sequentially section by section
- Update the Document Index line ranges if section size changes significantly
-
Verification
- After edits, read ONLY the modified section to verify changes
- Use Grep to search for specific content without loading full file
- Update "Index Last Updated" date in the Document Index after major changes
Using the Document Index
Every ARCHITECTURE.md should include a Document Index (before Section 1) with exact line ranges.
Index Format Example:
## Document Index
**Quick Navigation:**
- [Section 1: Executive Summary](#1-executive-summary) → Lines 1-80
- [Section 2: System Overview](#2-system-overview) → Lines 81-150
- [Section 3: Architecture Principles](#3-architecture-principles) → Lines 151-350
- [Section 4: Architecture Layers](#4-architecture-layers) → Lines 351-600
- [Section 5: Component Details](#5-component-details) → Lines 601-850
- [Section 6: Data Flow Patterns](#6-data-flow-patterns) → Lines 851-1000
- [Section 7: Integration Points](#7-integration-points) → Lines 1001-1150
- [Section 8: Technology Stack](#8-technology-stack) → Lines 1151-1300
- [Section 9: Security Architecture](#9-security-architecture) → Lines 1301-1550
- [Section 10: Scalability & Performance](#10-scalability--performance) → Lines 1551-1750
- [Section 11: Operational Considerations](#11-operational-considerations) → Lines 1751-1950
- [Section 12: Architecture Decision Records (ADRs)](#12-architecture-decision-records-adrs) → Lines 1951-end
**Index Last Updated:** YYYY-MM-DD
How to Use the Index:
- Find the Index: Read lines 1-50 to locate the Document Index
- Identify Target Section: Check the index for exact line ranges
- Load with Context Buffer: Read target section ± 10-20 lines for context preservation
- Example:
# To edit Section 5 (Component Details):
# Index shows: Lines 601-850
# Load with 10-line buffer:
Read(file_path="ARCHITECTURE.md", offset=590, limit=270)
# This reads lines 590-860
Context Buffer Guidelines:
| Edit Type | Buffer Size | Use Case |
|---|
| Minimal | ±5-10 lines | Small edits (single paragraph, config value) |
| Standard | ±10-20 lines | Section edits (rewriting subsection, adding components) |
| Extended | ±20-50 lines | Cross-section edits (changes referencing adjacent sections) |
Maintaining the Index:
After significant edits:
- Use
grep -n "^## [0-9]" ARCHITECTURE.md to find actual section line numbers
- Update the Document Index with current line ranges
- Update "Index Last Updated" date
- Verify index accuracy periodically (quarterly reviews)
Note: The Document Index is part of the ARCHITECTURE_DOCUMENTATION_GUIDE.md template and should be included in all new ARCHITECTURE.md files.
Architecture Type Selection Workflow
PURPOSE: When creating a new ARCHITECTURE.md, prompt the user to select their architecture type. This determines the structure and content of Section 4 (Meta Architecture) and Section 5 (Component Details).
When to Trigger
Activate this workflow when:
- ✅ User asks to create a NEW ARCHITECTURE.md document
- ✅ User explicitly requests to "change architecture type" or "select architecture type"
- ✅ User is updating an existing ARCHITECTURE.md and mentions changing from one architecture type to another
Skip this workflow when:
- ❌ Editing an existing ARCHITECTURE.md (type already selected)
- ❌ User is only updating specific sections unrelated to architecture type
- ❌ Document type is already clear from context
Available Architecture Types
- Microservices Architecture (Recommended) - Cloud-native distributed systems with independent services
- META Architecture - 6-layer enterprise model (Channels → UX → Business Scenarios → Business → Domain → Core) with BIAN V12.0 alignment for Layer 5 Domain service domains
- 3-Tier Architecture - Classic web application pattern (Presentation → Application/Business Logic → Data)
- N-Layer Architecture - Customizable patterns (DDD, Clean Architecture, Hexagonal)
- BIAN Architecture - 5-layer BIAN-compliant model (Channels → BIAN Business Scenarios → BIAN Business Capabilities → BIAN Service Domains → Core Systems) with full BIAN V12.0 compliance across layers 2-4
BIAN Standard for META: BIAN V12.0 is the default and recommended version for META architecture. Use the BIAN Service Landscape V12.0 to identify and define service domains for Layer 5 (Domain).
Workflow Steps
Step 1: Present Architecture Type Options
When creating a new ARCHITECTURE.md, present the user with architecture type selection:
📐 **Architecture Type Selection**
Before creating your ARCHITECTURE.md, please select the architecture type that best describes your system:
**1. Microservices Architecture (Recommended)** (Cloud-Native Distributed)
- Best for: Cloud-native systems, independently deployable services, modern applications
- Components: API Gateway → Services → Data Stores → Event Bus
- Complexity: High
- Team Size: Large (10+)
- Why Recommended: Industry standard for scalable, resilient modern applications
**2. META Architecture** (6-Layer Enterprise)
- Best for: Large enterprise systems, financial services, complex integrations
- Layers: Channels → UX → Business Scenarios → Integration → Domain → Core
- Complexity: Very High
- Team Size: Large (10+)
**3. 3-Tier Architecture** (Classic Web Application)
- Best for: Web apps, REST APIs, standard CRUD systems
- Tiers: Presentation → Application/Business Logic → Data
- Complexity: Low
- Team Size: Small-Medium (2-8)
**4. N-Layer Architecture** (Customizable Patterns)
- Best for: DDD, Clean Architecture, Hexagonal Architecture
- Patterns: 4-Layer DDD, 5-Layer Extended, Clean Architecture, Hexagonal
- Complexity: Medium-High
- Team Size: Medium (4-10)
**5. BIAN Architecture** (5-Layer BIAN-Compliant)
- Best for: Banking systems requiring BIAN V12.0 certification, full BIAN compliance
- Layers: Channels → BIAN Business Scenarios → BIAN Business Capabilities → BIAN Service Domains → Core Systems
- Complexity: Very High
- Team Size: Large (10+)
- BIAN Compliance: Full BIAN V12.0 across layers 2-4
For detailed comparison and decision guidance, refer to: `templates/ARCHITECTURE_TYPE_SELECTOR.md`
**Which architecture type best describes your system? (1-5, or type name)**
Note: Option 1 (Microservices) is recommended for most modern cloud-native applications.
Step 2: Capture User Selection
Wait for user response (1, 2, 3, 4, or 5) or architecture type name.
Valid inputs:
- Numeric:
1, 2, 3, 4, 5
- Type names:
Microservices, META, 3-Tier, N-Layer, BIAN
- Variations:
microservices, meta, three-tier, n-layer, bian
If user is unsure:
- Offer to load
templates/ARCHITECTURE_TYPE_SELECTOR.md decision guide
- Provide quick decision tree questions
- Default to Microservices (Recommended) for modern cloud-native systems
- Default to META if user has enterprise requirements and regulatory compliance needs
- Default to 3-Tier if user wants maximum simplicity and minimal operational complexity
Step 3: Load Type-Specific Templates
Based on user selection, load the appropriate templates:
| Selection | Section 4 Template | Section 5 Template |
|---|
| Microservices (1) | templates/SECTION_4_MICROSERVICES.md | templates/SECTION_5_MICROSERVICES.md |
| META (2) | templates/SECTION_4_META.md | templates/SECTION_5_META.md |
| 3-Tier (3) | templates/SECTION_4_3TIER.md | templates/SECTION_5_3TIER.md |
| N-Layer (4) | templates/SECTION_4_NLAYER_PATTERNS.md | (Use generic component template) |
| BIAN (5) | templates/SECTION_4_BIAN.md | templates/SECTION_5_BIAN.md |
Loading Process:
- Read the appropriate Section 4 template file
- Read the appropriate Section 5 template file (if exists)
- Extract template content (excluding metadata comments)
- Prepare for insertion into ARCHITECTURE.md at correct section boundaries
Step 4: Add Architecture Type Metadata
When creating the ARCHITECTURE.md, add an HTML comment metadata tag at the beginning of Section 4 to track the selected architecture type:
Valid metadata values:
<!-- ARCHITECTURE_TYPE: META --><!-- ARCHITECTURE_TYPE: 3-TIER --><!-- ARCHITECTURE_TYPE: MICROSERVICES --><!-- ARCHITECTURE_TYPE: N-LAYER --><!-- ARCHITECTURE_TYPE: BIAN -->
Purpose:
- Enables type detection for future edits
- Used by validation rules
- Used by Design Drivers calculation
- Used by architecture compliance skill
Step 5: Create ARCHITECTURE.md with Type-Specific Content
Create the complete ARCHITECTURE.md using:
- Standard sections 1-3 (same for all types)
- Type-specific Section 4 (from loaded template)
- Type-specific Section 5 (from loaded template)
- Standard sections 6-12 (same for all types)
Include:
- Document Index (placeholder line ranges)
- Architecture type metadata comment in Section 4
- All template content properly formatted
- Placeholder values for customization
Step 6: Prompt for ADR Generation (Optional)
Trigger: Immediately after Step 5 completes successfully (ARCHITECTURE.md created)
Objective: Offer to generate ADR files from Section 12 table
Step 6.0: Present ADR Generation Prompt
After ARCHITECTURE.md is successfully created, display the following prompt:
✅ ARCHITECTURE.md created successfully!
═══════════════════════════════════════════════════════════
📋 Architecture Decision Records (ADRs) Setup
═══════════════════════════════════════════════════════════
Section 12 of your ARCHITECTURE.md includes an ADR table with placeholder
entries. I can automatically generate these ADR files using the standard
ADR template.
Would you like me to generate the ADR files now?
Options:
1. [Yes - Generate ADRs] - Create all ADR files listed in Section 12
2. [Preview First] - Show me which ADRs will be created
3. [No Thanks] - I'll create them manually later
4. [Learn More] - Tell me about ADRs and the template
Recommended: Option 1 (Generate ADRs) - Saves time and ensures consistency
Wait for user response: 1, 2, 3, 4, or keywords like "yes", "preview", "no", "learn more"
Step 6.1: Handle User Selection
If user selects Option 1 (Yes - Generate ADRs):
- Proceed to Step 6.2 (Locate Section 12)
If user selects Option 2 (Preview First):
- Proceed to Step 6.2 (Locate Section 12)
- After Step 6.3 (Extract ADR List), show preview
- Re-prompt: "Proceed with generation? (yes/no)"
- If yes: Continue to Step 6.4
- If no: Skip to Step 6.8 (Complete)
If user selects Option 3 (No Thanks):
- Skip to Step 6.8 (Complete with skip message)
If user selects Option 4 (Learn More):
Architecture Decision Records (ADRs) document important architectural choices,
providing context for future team members and explaining the "why" behind
technical decisions.
**What ADRs Document**:
- Technology selection rationale
- Architecture pattern choices
- Trade-offs and alternatives considered
- Consequences of decisions
**ADR Template Structure**:
- Context: Problem statement and requirements
- Decision: What was decided
- Rationale: Why this choice was made
- Consequences: Positive/negative outcomes
- Alternatives: Options that were considered but rejected
**Template Location**: skills/architecture-docs/adr/ADR-000-template.md
**Guide**: skills/architecture-docs/ADR_GUIDE.md
Would you like me to generate the ADR files now? (yes/no)
- Re-prompt with Options 1-3
- Wait for new response
Step 6.2: Locate Section 12
Method 1: Use Document Index (preferred)
grep -A 20 "^## Document Index" ARCHITECTURE.md | grep "Section 12"
Expected output: - [Section 12: Architecture Decision Records (ADRs)](#12-architecture-decision-records-adrs) → Lines 1750-1800
Parse line range: Extract start line 1750 and end line 1800
Method 2: Fallback - Find by Header
If Document Index method fails:
grep -n "^## 12\. Architecture Decision Records" ARCHITECTURE.md
Expected output: 1750:## 12. Architecture Decision Records (ADRs)
Parse line number: Extract 1750
Read until: Next section header or end of file (typically 50-100 lines)
Error Handling: If Section 12 not found:
⚠️ Section 12: Architecture Decision Records not found in ARCHITECTURE.md
This is unusual - all ARCHITECTURE.md files should include Section 12.
Would you like me to:
1. [Add Section 12] - Add the section with empty ADR table
2. [Skip ADR Generation] - Continue without generating ADRs
3. [Manual Review] - Let me check the document structure first
Recommended: Option 3 (Manual Review)
Step 6.3: Extract ADR List from Section 12
Read Section 12 content:
Read(file_path="ARCHITECTURE.md", offset=1750, limit=50)
Parse ADR table rows:
grep -E "^\| \[ADR-" ARCHITECTURE.md
Expected output (example):
| [ADR-001](adr/ADR-001.md) | [Title] | Accepted | YYYY-MM-DD | High/Medium/Low |
| [ADR-002](adr/ADR-002-database.md) | Database Choice | Proposed | 2024-01-20 | High |
Parse each row:
For each line matching the pattern ^\| \[ADR-:
- Extract ADR number:
001, 002, etc. (from [ADR-001])
- Extract file path from link:
adr/ADR-001.md (from (adr/ADR-001.md))
- Extract slug (if present): `` (empty) or
database (from ADR-002-database.md)
- Extract title: Column 2 (e.g.,
[Title] or Database Choice)
- Extract status: Column 3 (e.g.,
Accepted, Proposed)
- Extract date: Column 4 (e.g.,
YYYY-MM-DD or 2024-01-20)
- Extract impact: Column 5 (e.g.,
High/Medium/Low or High)
Regex Pattern for parsing:
^\| \[ADR-(\d{3})\]\(adr\/ADR-\d{3}(-[a-z0-9-]+)?\.md\) \| (.+?) \| (.+?) \| (.+?) \| (.+?) \|
Capture Groups:
- Group 1: ADR number (e.g.,
001)
- Group 2: Optional slug (e.g.,
-database or empty)
- Group 3: Title
- Group 4: Status
- Group 5: Date
- Group 6: Impact
Store in list:
adrs = [
{
"number": "001",
"slug": "",
"title": "[Title]",
"status": "Accepted",
"date": "YYYY-MM-DD",
"impact": "High/Medium/Low",
"file_path": "adr/ADR-001.md"
},
{
"number": "002",
"slug": "database",
"title": "Database Choice",
"status": "Proposed",
"date": "2024-01-20",
"impact": "High",
"file_path": "adr/ADR-002-database.md"
}
]
Error Handling: If no ADRs found (empty table):
ℹ️ Section 12 ADR table is empty or contains only placeholder entries.
No ADRs found to generate. This is normal for newly created ARCHITECTURE.md files.
Would you like me to:
1. [Skip ADR Generation] - Continue without creating ADR files
2. [Learn About ADRs] - Understand when to create ADRs
3. [Add Sample ADR] - Create one example ADR to get started
Recommended: Option 1 (Skip) - Create ADRs as architectural decisions are made
Validation:
- Check for duplicate ADR numbers (same number appears multiple times)
- Check for malformed rows (wrong column count)
If duplicates found:
⚠️ Duplicate ADR numbers detected in Section 12 table
Duplicates found: ADR-002 (appears 2 times)
This will cause file overwrites. Please fix the table before generating ADRs.
Would you like me to:
1. [Show Duplicates] - Display the conflicting rows
2. [Auto-Renumber] - Automatically renumber ADRs sequentially
3. [Skip ADR Generation] - Fix manually and regenerate later
Recommended: Option 1 (Show Duplicates)
Step 6.3a: Preview ADRs (if user selected Option 2)
If user selected "Preview First" in Step 6.1:
Display ADR list:
Found {count} ADRs in Section 12 table:
1. ADR-001: [Title] (Status: Accepted, Impact: High/Medium/Low)
→ Will create: adr/ADR-001-untitled.md
Note: Placeholder title - you can customize later
2. ADR-002: Database Choice (Status: Proposed, Impact: High)
→ Will create: adr/ADR-002-database.md
Proceed with generation? (yes/no)
Wait for response:
- If
yes or 1: Continue to Step 6.4
- If
no or 2 or skip: Skip to Step 6.8
Step 6.4: Prepare ADR Generation
Get ARCHITECTURE.md directory:
ARCH_DIR="."
Define ADR directory path:
ADR_DIR="${ARCH_DIR}/adr"
Create ADR directory if doesn't exist:
mkdir -p adr
Error Handling: If directory creation fails:
❌ Error: Unable to create adr/ directory
Reason: [Error message from mkdir]
Possible causes:
- Insufficient file permissions
- Path does not exist
- Disk space full
Would you like me to:
1. [Retry with Different Path] - Try creating in user home directory
2. [Skip ADR Generation] - Continue without creating ADR files
3. [Manual Instructions] - Show me how to create manually
Recommended: Option 3 (Manual Instructions)
Success message:
Generating ADR files in ./adr/
Step 6.5: Load ADR Template
Template path: Resolve dynamically — $PLUGIN_DIR/skills/architecture-docs/adr/ADR-000-template.md
Resolve plugin directory (run once per session if not already known):
PLUGIN_DIR=$(find "$HOME" -maxdepth 10 -type d -name "solutions-architect-skills" ! -path "*/node_modules/*" 2>/dev/null | head -1)
echo "$PLUGIN_DIR"
Load template using the resolved path:
Read(file_path="$PLUGIN_DIR/skills/architecture-docs/adr/ADR-000-template.md")
(Replace $PLUGIN_DIR with the actual path returned by the Bash command above)
Store template content in memory for reuse across all ADR files
Step 6.6: Generate Each ADR File
For each ADR in the adrs list from Step 6.3:
Step 6.6a: Generate File Path
if adr["slug"] == "":
slug = generate_slug(adr["title"])
else:
slug = adr["slug"]
file_name = f"ADR-{adr['number']}-{slug}.md"
file_path = f"adr/{file_name}"
Step 6.6b: Generate Slug from Title (if needed)
Slug Generation Rules:
- Convert title to lowercase
- Replace spaces with hyphens
- Remove special characters:
:?/*<>|" (keep alphanumeric and hyphens)
- Remove consecutive hyphens (replace
-- with -)
- Trim leading/trailing hyphens
- Limit to 50 characters
- If title is
[Title] or placeholder, use slug untitled
Examples:
Technology Stack Selection → technology-stack-selectionREST vs. gRPC: Which API? → rest-vs-grpc-which-apiPostgreSQL Database Choice → postgresql-database-choice[Title] → untitled
Step 6.6c: Check for Existing File
if [ -f "adr/ADR-${number}-*.md" ]; then
fi
If exists:
⚠️ ADR file conflict detected
Existing file: adr/ADR-001-old-title.md
New file: adr/ADR-001-technology-stack.md
Would you like me to:
1. [Skip This ADR] - Don't overwrite, keep existing file
2. [Rename New ADR] - Create as ADR-{next_available} instead
3. [Overwrite] - Replace existing file (destructive)
4. [Review Existing] - Show me what's in the existing file first
Recommended: Option 4 (Review Existing)
Conflict Resolution:
- Never auto-overwrite existing ADRs
- Always require user confirmation
- Suggest next available ADR number if renaming
Step 6.6d: Populate Template
adr_content = template_content
adr_content = adr_content.replace("ADR-XXX", f"ADR-{adr['number']}")
adr_content = adr_content.replace("[Short Decision Title]", adr["title"])
status_line_old = "**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX"
status_line_new = f"**Status**: {adr['status']}"
adr_content = adr_content.replace(status_line_old, status_line_new)
if adr["date"] == "YYYY-MM-DD" or adr["date"] == "[Date]":
current_date = datetime.now().strftime("%Y-%m-%d")
adr_content = adr_content.replace("**Date**: YYYY-MM-DD", f"**Date**: {current_date}")
else:
adr_content = adr_content.replace("**Date**: YYYY-MM-DD", f"**Date**: {adr['date']}")
adr_content = adr_content.replace("**Authors**: [Author names or team name]", "**Authors**: Architecture Team")
adr_content = adr_content.replace("**Related**: [Links to related ADRs, e.g., ADR-001, ADR-005]", "**Related**: []")
Special handling for placeholder titles:
if adr["title"] in ["[Title]", "[title]", "Title"]:
note = "\n> **TODO**: This ADR was auto-generated with a placeholder title. Please update the title, filename, and content with your actual architectural decision.\n"
lines = adr_content.split('\n')
for i, line in enumerate(lines):
if line.startswith('# ADR-'):
lines.insert(i + 1, note)
break
adr_content = '\n'.join(lines)
Step 6.6e: Write ADR File
Write(file_path=file_path, content=adr_content)
Error Handling: If write fails:
- Log error message
- Mark ADR as "failed" in tracking
- Continue with next ADR (don't abort entire batch)
Step 6.6f: Report Progress
✅ Created: adr/ADR-001-technology-stack.md
Repeat Steps 6.6a-6.6f for all ADRs in list
Step 6.7: Display Summary Report
After all ADRs processed:
Count results:
total_adrs = len(adrs)
created_adrs = count(created successfully)
skipped_adrs = count(skipped due to conflicts)
failed_adrs = count(failed to write)
Display summary:
═══════════════════════════════════════════════════════════
✅ ADR Generation Complete
═══════════════════════════════════════════════════════════
Successfully generated {created_adrs} of {total_adrs} ADR files in ./adr/
Created ADRs:
- adr/ADR-001-technology-stack.md
- adr/ADR-002-database-choice.md
- adr/ADR-003-api-protocol.md
{If skipped_adrs > 0:}
Skipped ADRs:
- ADR-004 (file already exists: adr/ADR-004-old-title.md)
{If failed_adrs > 0:}
Failed ADRs:
- ADR-005 (write error: permission denied)
Next steps:
1. Review and customize each ADR file
2. Fill in Context, Decision, and Rationale sections
3. Update placeholder titles (marked with TODO)
4. Link related ADRs in the "Related" field
5. Update status to "Accepted" once reviewed and approved
ADR Template Guide: skills/architecture-docs/ADR_GUIDE.md
Step 6.8: Complete Workflow
If user skipped ADR generation (Option 3 in Step 6.1):
ℹ️ Skipped ADR generation - you can create ADR files manually later
To create ADRs manually:
1. Update Section 12 table in ARCHITECTURE.md with your ADRs
2. Copy template: cp skills/architecture-docs/adr/ADR-000-template.md adr/ADR-001-your-title.md
3. Customize the ADR content
For guidance, see: skills/architecture-docs/ADR_GUIDE.md
Return to main workflow: Architecture Type Selection Workflow completes successfully
End of Step 6
Detecting Existing Architecture Type
When editing an existing ARCHITECTURE.md, detect the architecture type:
Detection Method 1: Metadata Comment
grep -n "<!-- ARCHITECTURE_TYPE:" ARCHITECTURE.md
If found, extract the type from the comment.
Detection Method 2: Section 4 Header Analysis
If no metadata comment, infer from Section 4 headers:
grep -E "(Layer 2: BIAN Business Scenarios|Layer 4: BIAN Service Domains)" ARCHITECTURE.md
grep -E "(Layer 1: Channels|Layer 5: Domain|Layer 6: Core)" ARCHITECTURE.md
grep -E "(Tier 1: Presentation|Tier 3: Data)" ARCHITECTURE.md
grep -E "(API Gateway|Service Mesh|Microservices Catalog)" ARCHITECTURE.md
grep -E "(Clean Architecture|Hexagonal|Ports & Adapters)" ARCHITECTURE.md
Inference Rules (in order of specificity):
- Contains "Layer 2: BIAN Business Scenarios" OR "Layer 4: BIAN Service Domains" → BIAN
- Contains "Layer 1: Channels" AND "Layer 5: Domain" AND "Layer 6: Core" → META
- Contains "Tier 1: Presentation" OR "Tier 3: Data" → 3-Tier
- Contains "API Gateway" AND "Service Mesh" → Microservices
- Contains "Clean Architecture" OR "Hexagonal" → N-Layer
- Cannot determine → Ask user or default to Microservices (Recommended)
Changing Architecture Type (Existing Document)
If user requests to change architecture type of an existing ARCHITECTURE.md:
Warning Steps:
-
Detect current type using detection methods above
-
Warn user about potential data loss:
⚠️ **Architecture Type Change Warning**
Current type: [DETECTED_TYPE]
Requested type: [NEW_TYPE]
Changing architecture type will:
- Replace Section 4 (Meta Architecture) with new structure
- Replace Section 5 (Component Details) with new organization
- Require manual component remapping
**Recommendation**: Review and backup current Sections 4 & 5 before proceeding.
Continue with architecture type change? (yes/no)
-
If user confirms:
- Load new type templates
- Replace Section 4 content
- Replace Section 5 content
- Update metadata comment
- Update Document Index
- Report changes to user
-
If user declines:
- Cancel operation
- Suggest manual editing approach
Type-Specific Validation
After selecting or detecting architecture type, apply type-specific validation rules:
BIAN Architecture:
- ✅ Must have all 5 layers (Channels, BIAN Business Scenarios, BIAN Business Capabilities, BIAN Service Domains, Core Systems)
- ✅ Layer 2 must map to BIAN Business Areas (5 areas)
- ✅ Layer 3 must map to BIAN Business Domains (30+ domains)
- ✅ Layer 4 must implement BIAN Service Domains from BIAN V12.0
- ✅ All Layer 4 service domain names validated against official BIAN Service Landscape V12.0
- ✅ Layer 4 components must include complete BIAN metadata (Official Name, BIAN ID, Version, Business Domain, Business Area, URL)
- ✅ Control records documented per BIAN specification for all Layer 4 service domains
- ✅ All mandatory BIAN service operations implemented (Initiate, Update, Retrieve, Control)
- ✅ Behavior qualifiers documented per BIAN spec
- ✅ Functional patterns documented per BIAN spec (Managed Object, Tracked Object, etc.)
- ✅ Full BIAN V12.0 compliance level documented
- ✅ BIAN hierarchy traceability: Service Domain → Business Domain → Business Area
- ✅ Layers documented in correct order
META Architecture:
- ✅ Must have all 6 layers (Channels, UX, Business Scenarios, Business, Domain, Core)
- ✅ Layer 5 must include BIAN alignment section
- ✅ Verify BIAN V12.0 is documented as the default version
- ✅ Validate BIAN service domain names (Capabilities) against the official BIAN Service Landscape V12.0
- ✅ Ensure BIAN IDs (SD-XXX) are used for internal document tracking only
- ✅ Validate Layer 5 (Domain) components include BIAN alignment subsection with official URLs
- ✅ Layers documented in correct order
3-Tier Architecture:
- ✅ Must have all 3 tiers (Presentation, Application, Data)
- ✅ No direct database access from Presentation tier
- ✅ Application tier should be stateless
Microservices Architecture:
- ✅ Must document API Gateway and Service Mesh (or justify omission)
- ✅ Database-per-service pattern followed
- ✅ Event bus and topics documented
- ✅ Circuit breakers configured
N-Layer Architecture:
- ✅ Must specify which pattern (4-Layer, 5-Layer, Clean, Hexagonal)
- ✅ Dependency direction documented
- ✅ Core/domain layer is framework-free (if applicable)
For detailed validation rules, see: VALIDATIONS.md § Type-Aware Validation
Best Practices
DO:
- ✅ Always prompt for architecture type when creating new ARCHITECTURE.md
- ✅ Add metadata comment to track architecture type
- ✅ Load appropriate templates based on selection
- ✅ Warn before changing architecture type of existing document
- ✅ Apply type-specific validation rules
DON'T:
- ❌ Assume architecture type without asking
- ❌ Mix templates from different architecture types
- ❌ Change architecture type without user confirmation
- ❌ Skip metadata comment (makes future edits harder)
Example Workflow
User: "Create architecture documentation for my microservices system"
Assistant:
- Detects new ARCHITECTURE.md creation
- Presents architecture type options (1-4)
- User selects "3" (Microservices)
- Loads
templates/SECTION_4_MICROSERVICES.md and templates/SECTION_5_MICROSERVICES.md
- Creates ARCHITECTURE.md with:
- Standard Sections 1-3
- Microservices Section 4 (API Gateway, Service Mesh, Services, Event Bus)
- Microservices Section 5 (Service catalog format)
- Standard Sections 6-12
- Metadata comment:
<!-- ARCHITECTURE_TYPE: MICROSERVICES -->
- Reports completion with architecture type confirmation
Automatic Index Updates
CRITICAL: After ANY edit that significantly changes section line numbers (>10 lines), automatically update the Document Index.
When to Update
Update if:
- ✅ Added/removed content shifting section boundaries (>10 lines)
- ✅ Modified section headers or structure
- ✅ User requests: "update the index"
Skip if:
- ❌ Minor edits (<10 lines)
- ❌ Only metadata changes
- ❌ Typo fixes
Workflow Overview
Quick Steps:
- Detect: Run
grep -n "^## [0-9]" ARCHITECTURE.md to find section boundaries
- Calculate: Parse output to determine line ranges (Section_Start to Next_Section_Start - 1)
- Update: Edit Document Index (typically lines 5-21) with new ranges
- Timestamp: Update "Index Last Updated" to current date
- Report: Inform user which sections changed
Example:
grep -n "^## [0-9]" ARCHITECTURE.md
Detailed Algorithm
For complete line range calculation algorithm, step-by-step examples, verification checklist, and edge cases:
→ METRIC_CALCULATIONS.md § Automatic Index Updates
Best Practices
DO:
- ✅ Update after significant edits
- ✅ Use grep for accuracy (don't guess)
- ✅ Update timestamp
- ✅ Report changes to user
DON'T:
- ❌ Update for tiny changes
- ❌ Skip timestamp update
- ❌ Change index format
Metric Consistency Detection & Management
CRITICAL: The Executive Summary (Section 1, Key Metrics subsection around lines 31-38) contains performance metrics that serve as the Source of Truth for system capacity, throughput, latency, and availability targets. These metrics are often duplicated across multiple sections (especially Section 6: Data Flow, Section 7: Integration Points, and Section 10: Scalability & Performance).
Problem: When metrics are updated in the Executive Summary, duplicates in other sections can become stale, creating inconsistencies.
Solution: This skill provides automatic metric consistency detection and review-based synchronization.
When to Trigger Metric Audit
Automatic Trigger:
- ✅ After editing Section 1 Executive Summary Key Metrics (typically lines 31-38)
- ✅ When user updates any metric values in the Key Metrics subsection
- ✅ After Edit tool completes on lines in Section 1 that contain metrics (TPS, latency, SLA, etc.)
Manual Trigger:
- User explicitly requests: "Check metric consistency", "Verify metrics", "Audit metrics", "Sync metrics"
- User updates Section 10 (Scalability & Performance) and asks to verify consistency with Exec Summary
- During quarterly documentation review or audit
Do NOT Trigger:
- ❌ Minor edits outside Key Metrics subsection (e.g., updating document version or date)
- ❌ Edits to narrative text that don't change numeric metric values
- ❌ Changes to other sections that don't involve performance metrics
Metric Audit Workflow
Step 1: Extract Executive Summary Metrics
Read ONLY lines 30-40 (Key Metrics section) using context-efficient approach:
Read(file_path="ARCHITECTURE.md", offset=30, limit=10)
Parse and extract all metrics with their values using these patterns:
| Metric Type | Pattern | Example Match |
|---|
| Average Read TPS | Average\s+Read\s+TPS:\s*(\d{1,3}(?:,\d{3})*)\s*transactions/second | "Average Read TPS: 1,500 transactions/second" |
| Peak Read TPS | Peak\s+Read\s+TPS:\s*(\d{1,3}(?:,\d{3})*)\s*transactions/second | "Peak Read TPS: 3,000 transactions/second" |
| Average Processing TPS | Average\s+Processing\s+TPS:\s*(\d{1,3}(?:,\d{3})*)\s*transactions/second | "Average Processing TPS: 450 transactions/second" |
| Peak Processing TPS | Peak\s+Processing\s+TPS:\s*(\d{1,3}(?:,\d{3})*)\s*transactions/second | "Peak Processing TPS: 1,000 transactions/second" |
| Average Write TPS | Average\s+Write\s+TPS:\s*(\d{1,3}(?:,\d{3})*)\s*transactions/second | "Average Write TPS: 300 transactions/second" |
| Peak Write TPS | Peak\s+Write\s+TPS:\s*(\d{1,3}(?:,\d{3})*)\s*transactions/second | "Peak Write TPS: 800 transactions/second" |
| Measurement Period | Measurement\s+Period:\s*(.+) | "Measurement Period: Average over last 30 days" |
| Percentile Latency | p(\d{2})\s*<\s*(\d+)ms | "p95 < 100ms", "p99 < 200ms" |
| Availability SLA | (\d{2,3}\.\d+)\s*% | "99.99%", "99.9%" |
| Concurrent Jobs | (\d{1,3}(?:,\d{3})*)\+?\s*concurrent | "10,000+ concurrent", "5000 concurrent" |
| Jobs per Hour | \[(\d{1,3}(?:,\d{3})*)\s*jobs?/hour\] | "[1,620,000 jobs/hour]" |
Build a metrics registry from parsed data:
METRICS_REGISTRY = [
{name: "Read TPS", value: 1500, unit: "TPS", category: "Read", stat_type: "Average", line: 32, measurement_period: "Average over last 30 days in production"},
{name: "Read TPS", value: 3000, unit: "TPS", category: "Read", stat_type: "Peak", line: 33, measurement_period: "Peak observed during Black Friday 2024"},
{name: "Processing TPS", value: 450, unit: "TPS", category: "Processing", stat_type: "Average", line: 35, measurement_period: "Average over last quarter"},
{name: "Processing TPS", value: 1000, unit: "TPS", category: "Processing", stat_type: "Peak", line: 36, measurement_period: "Peak during end-of-month batch processing"},
{name: "Write TPS", value: 300, unit: "TPS", category: "Write", stat_type: "Average", line: 38, measurement_period: "Average over last month"},
{name: "Write TPS", value: 800, unit: "TPS", category: "Write", stat_type: "Peak", line: 39, measurement_period: "Peak during data migration events"},
{name: "System Availability", value: 99.99, unit: "%", line: 42},
{name: "Latency p95", value: 100, unit: "ms", line: 43},
{name: "Latency p99", value: 200, unit: "ms", line: 43},
{name: "Concurrent Jobs", value: 10000, unit: "jobs", line: 44}
]
Step 2: Scan Document for Metric References
Use Grep to find all occurrences of each metric value (context-efficient, no full file load):
Grep(pattern="Average\s+Read\s+TPS:\s*1,?500", path="ARCHITECTURE.md", output_mode="files_with_matches")
Grep(pattern="Peak\s+Read\s+TPS:\s*3,?000", path="ARCHITECTURE.md", output_mode="files_with_matches")
Grep(pattern="Average\s+Processing\s+TPS:\s*450", path="ARCHITECTURE.md", output_mode="files_with_matches")
Grep(pattern="Peak\s+Processing\s+TPS:\s*1,?000", path="ARCHITECTURE.md", output_mode="files_with_matches")
Grep(pattern="Average\s+Write\s+TPS:\s*300", path="ARCHITECTURE.md", output_mode="files_with_matches")
Grep(pattern="Peak\s+Write\s+TPS:\s*800", path="ARCHITECTURE.md", output_mode="files_with_matches")
Grep(pattern="99\.99%", path="ARCHITECTURE.md", output_mode="files_with_matches")
Grep(pattern="p95.*100ms", path="ARCHITECTURE.md", output_mode="files_with_matches")
Grep(pattern="p99.*200ms", path="ARCHITECTURE.md", output_mode="files_with_matches")
Grep(pattern="10,?000.*concurrent", path="ARCHITECTURE.md", output_mode="files_with_matches")
Note: Use -n flag with grep bash command if you need line numbers, or use Grep tool with output_mode="content".
Step 3: Load Context for Each Match
For each grep result, read ±5 lines for context to determine if it's a duplicate or coincidental match:
Read(file_path="ARCHITECTURE.md", offset=782, limit=10)
Step 4: Classify Findings
Categorize each finding into one of four categories:
- ✓ Exact Match: Same value, same metric concept, already consistent with Executive Summary
- ⚠️ Mismatch: Same metric concept but different value (ACTION REQUIRED - user must decide)
- ℹ️ Derived Value: Related but transformed metric (e.g., 450 TPS = 1,620,000 jobs/hour via 450 × 3600)
- ? Ambiguous: Number matches but context is unclear (flag for manual review)
Classification Logic:
- Check if line is in Section 1 (skip, that's the source of truth)
- Read context (±5 lines) to understand what the metric represents
- Compare metric concept (is this the same "Job Creation Capacity" or different metric?)
- Determine relationship (exact duplicate, derived value, or unrelated)
Step 5: Generate Consistency Report
Present findings in structured, user-friendly format:
═══════════════════════════════════════════════════════════
METRIC CONSISTENCY AUDIT REPORT
═══════════════════════════════════════════════════════════
Source of Truth: Section 1 (Executive Summary) Lines 31-38
Total Metrics Audited: 10
═══════════════════════════════════════════════════════════
## ✓ Exact Matches (Consistent)
| Metric | Exec Value | Location | Context | Status |
|--------|-----------|----------|---------|--------|
| Job Latency (p95) | < 100ms | Line 787 | Section 6: Data Flow Performance | ✓ Match |
| Job Latency (p99) | < 200ms | Line 787 | Section 6: Data Flow Performance | ✓ Match |
| Job Latency (p95) | < 100ms | Line 1345 | Section 10: Performance Table | ✓ Match |
| Job Latency (p99) | < 200ms | Line 1345 | Section 10: Performance Table | ✓ Match |
## ⚠️ Mismatches Found (ACTION REQUIRED)
| Metric | Exec Value | Location | Current Value | Difference |
|--------|-----------|----------|---------------|------------|
| Peak Job Creation | 1,000 TPS | Line 1367 | 500 TPS | -500 TPS |
## ℹ️ Derived Values (Informational)
| Metric | Exec Value | Location | Derived Value | Relationship |
|--------|-----------|----------|---------------|--------------|
| Job Creation | 450 TPS | Line 32 | 1,620,000 jobs/hour | 450 × 3600 |
═══════════════════════════════════════════════════════════
SUMMARY: ✓ 4 Matches | ⚠️ 1 Mismatch | ℹ️ 1 Derived
═══════════════════════════════════════════════════════════
Step 6: Await User Decision
If mismatches found, present options to user:
I found 1 metric mismatch. What would you like to do?
1. [Review Details] - Show detailed context for the mismatch
2. [Update Exec Summary] - Update Section 1 to match line 1367 (500 TPS)
3. [Update Document] - Update line 1367 to match Exec Summary (1,000 TPS)
4. [Preview Changes] - Show exactly what will change before applying
5. [Manual Review] - I'll review and decide later
6. [Ignore] - Keep as-is (intentional difference)
Step 7: Apply Approved Changes
If user approves updates:
- Show preview of all changes (exact before/after for each location)
- Confirm user approval
- Use Edit tool to update each location sequentially
- Update Document Index if line numbers shift significantly (>10 lines)
- Report completion with summary of all changes made
Common Metric Locations
Known Duplicate Locations (for typical architecture documents):
| Metric | Executive Summary | Common Duplicate Locations |
|---|
| Job Creation Capacity (450 TPS) | Line ~32 | Section 10 Throughput Table (~line 1367) |
| Job Execution Capacity (500 TPS) | Line ~33 | Section 10 Throughput Table (~line 1368), Section 6 Data Flow (~line 787) |
| Peak Capacity (1,000/2,000 TPS) | Line ~34 | Section 10 Throughput Table (~lines 1367-1368) |
| Initial Load (150/350 TPS) | Line ~35 | Section 10 Capacity Planning (~lines 1378-1379) |
| System Availability (99.99%) | Line ~36 | Section 2 Use Case metrics (~line 115), Section 7 Integration SLA Table (~lines 829-832) |
| Latency Targets (p95/p99) | Line ~37 | Section 6 Data Flow Performance (~line 787), Section 10 Performance Table (~line 1345) |
| Concurrent Jobs (10,000+) | Line ~38 | Less commonly duplicated (usually only in Exec Summary) |
Note: Line numbers are approximate and vary by document. Use grep to find exact locations.
Metric Update Best Practices
DO:
- ✅ Always scan full document after Exec Summary metric changes
- ✅ Present findings before making any changes (review-only first)
- ✅ Explain context for each mismatch (which section, what table/paragraph)
- ✅ Offer batch update option for multiple occurrences of same metric
- ✅ Show preview with exact before/after text for transparency
- ✅ Update Document Index if edits shift section boundaries
DON'T:
- ❌ Auto-update without user approval (always review-only first)
- ❌ Change metrics in unrelated sections without confirming intent
- ❌ Ignore ambiguous matches (always flag for review)
- ❌ Forget to check derived values (e.g., jobs/hour conversions from TPS)
- ❌ Skip context loading (always read ±5 lines to understand match)
Error Handling & Edge Cases
1. Multiple Conflicting Values
Scenario: Same metric has different values in multiple sections (not just Exec Summary vs. one location)
Example:
- Exec Summary (Line 32): 450 TPS
- Section 6 (Line 787): 500 TPS
- Section 10 (Line 1367): 400 TPS
Handling:
⚠️ CONFLICT DETECTED: Job Execution Capacity has 3 different values
| Location | Value | Context |
|----------|-------|---------|
| Line 32 (Exec Summary) | 450 TPS | Design Capacity |
| Line 787 (Section 6) | 500 TPS | Data Flow Performance |
| Line 1367 (Section 10) | 400 TPS | Throughput Table |
Which value is correct?
1. Use Exec Summary (450 TPS) as source of truth
2. Use most common value (if clear majority)
3. Manual review - I need to investigate further
Please clarify which value should be used across all locations.
2. Derived Value Calculation Errors
Scenario: Derived value doesn't match expected conversion
Example:
- Exec Summary: 450 TPS
- Expected derived: 1,620,000 jobs/hour (450 × 3600)
- Found in doc: 1,650,000 jobs/hour
Handling:
ℹ️ Derived Value Mismatch Detected:
Metric: Job Creation Capacity
Base Value: 450 TPS (Line 32)
Expected Derived: 1,620,000 jobs/hour (450 × 3600)
Actual Found: 1,650,000 jobs/hour (Line 32)
Difference: +30,000 jobs/hour
Possible causes:
- Rounding or overhead factor applied
- Different calculation method
- Stale value from previous metric update
Would you like to:
1. Update to calculated value (1,620,000)
2. Keep current value (1,650,000) - might be intentional overhead
3. Investigate further
3. Ambiguous Metric Context
Scenario: Number matches but unclear if it's the same metric
Example:
- Exec Summary: Peak Capacity 1,000 TPS
- Found at line 1367: "System limit 1,000 TPS (theoretical max)"
- Found at line 1372: "Target throughput 1,000 TPS (steady state)"
- Found at line 1389: "1000 TPS limit"
Handling:
? AMBIGUOUS MATCH: Value "1,000 TPS" found in multiple contexts
Exec Summary Definition (Line 34):
"Peak Capacity: 1,000 TPS job creation, 2,000 TPS job execution (system limits)"
Found Matches:
1. Line 1367: "System limit 1,000 TPS"
Context: Throughput table - appears to be same metric ✓
2. Line 1372: "1000 TPS (theoretical max)"
Context: Throughput calculation - likely same metric ✓
3. Line 1389: "1000 TPS limit"
Context: Capacity planning - likely same metric ✓
All 3 appear to reference Peak Capacity. Treat as exact matches? [Yes/No/Review Each]
4. No Matches Found
Scenario: Metric exists in Exec Summary but never referenced elsewhere
Example:
- Exec Summary: "Concurrent Jobs: Support for 10,000+ concurrent scheduled jobs"
- Grep search: No matches found in rest of document
Handling:
ℹ️ INFORMATIONAL: Metric appears only in Executive Summary
Metric: Concurrent Jobs (10,000+)
Location: Line 38 (Section 1)
Document Coverage: Not referenced in other sections
This is not necessarily an error - some high-level metrics may only appear in Exec Summary.
Recommendation:
- If this metric is important to architecture, consider adding to Section 10 (Scalability & Performance)
- If it's a summary-only metric, no action needed
Would you like to:
1. Add this metric to Section 10
2. Keep as-is (Exec Summary only)
3. Ignore this finding
5. Too Many Grep Results
Scenario: Common number matches hundreds of unrelated contexts
Example: Searching for "100" also matches "100 pods", "section 100", "version 1.00"
Handling:
Example: Complete Metric Update Workflow
Scenario: User updates Job Execution Capacity from 500 TPS to 700 TPS
Step-by-Step Execution:
-
User Action:
User: "Update the job execution capacity to 700 TPS in the Executive Summary"
-
Claude Applies Edit:
[Uses Edit tool to change line 33: "500 TPS" → "700 TPS"]
✓ Updated line 33: Design Capacity - Job Execution: 700 TPS
Now checking for metric consistency across the document...
-
Automatic Audit Triggered:
[Metric audit automatically triggered because Section 1 Key Metrics was edited]
Scanning document for references to old value (500 TPS)...
[Runs: Grep(pattern="500\s*TPS", path="ARCHITECTURE.md")]
[Found at: Line 787, Line 1368]
-
Load Context for Each Match:
[Reads context around each match]
Read(file_path="ARCHITECTURE.md", offset=782, limit=10) # Lines 782-792 for Line 787
Read(file_path="ARCHITECTURE.md", offset=1363, limit=10) # Lines 1363-1373 for Line 1368
-
Present Findings:
═══════════════════════════════════════════════════════════
METRIC CONSISTENCY AUDIT REPORT
═══════════════════════════════════════════════════════════
Triggered by: Executive Summary edit (Line 33)
Metric Changed: Job Execution Capacity (500 TPS → 700 TPS)
═══════════════════════════════════════════════════════════
## ⚠️ Outdated References Found
| Location | Section | Current Value | Should Be | Context |
|----------|---------|---------------|-----------|---------|
| Line 787 | Section 6: Data Flow Patterns | 500 TPS capacity | 700 TPS | "Performance: p50 = 40ms, p95 = 100ms, p99 = 200ms \| 500 TPS capacity" |
| Line 1368 | Section 10: Scalability & Performance | 500 | 700 | Throughput table: "Job Execution (TPS) \| 500 \| 1000 \| 2000" |
═══════════════════════════════════════════════════════════
SUMMARY: Found 2 locations with outdated metric value
═══════════════════════════════════════════════════════════
Would you like me to update both locations to 700 TPS?
Options:
1. [Yes - Update All] - Apply changes to both locations
2. [Preview Changes] - Show me exactly what will change
3. [Manual Selection] - Let me choose individually
4. [No Thanks] - I'll handle this manually
-
User Requests Preview:
User: "Preview changes first"
-
Show Preview:
Here's a preview of the changes I'll make:
════════════════════════════════════════════════════════════
CHANGE 1 of 2: Line 787 (Section 6: Data Flow Patterns)
════════════════════════════════════════════════════════════
Current:
**Performance**: p50 = 40ms, p95 = 100ms, p99 = 200ms | 500 TPS capacity
Will become:
**Performance**: p50 = 40ms, p95 = 100ms, p99 = 200ms | 700 TPS capacity
════════════════════════════════════════════════════════════
CHANGE 2 of 2: Line 1368 (Section 10: Throughput Table)
════════════════════════════════════════════════════════════
Current:
| Job Execution (TPS) | 500 | 1000 | 2000 | Downstream domain services |
Will become:
| Job Execution (TPS) | 700 | 1000 | 2000 | Downstream domain services |
════════════════════════════════════════════════════════════
Proceed with both changes? [Yes/No/Choose Individually]
Design Drivers Impact Metrics Calculation
PURPOSE: Automatically calculate and maintain Design Drivers impact metrics (Value Delivery, Scale, Impacts) based on data from existing architecture sections. Design Drivers provide a quantifiable assessment of the architecture's business value, customer reach, and implementation complexity.
When to Trigger Design Drivers Calculation
Automatic Prompt:
- ✅ User requests "architecture review" or "audit" (prompt to calculate)
- ✅ User explicitly asks to "calculate design drivers" or "update design drivers"
- ✅ After significant architecture changes during review process
Manual Trigger:
- User explicitly requests: "Calculate design drivers", "Update Section 2.2.1", "Assess design impact"
- During quarterly documentation review or architecture validation
- When preparing architecture presentations or business justifications
Do NOT Trigger:
- ❌ Minor edits unrelated to architecture (typos, formatting, dates)
- ❌ Changes to sections not used in design drivers calculation (Sections 3, 4, 9, 11, 12)
- ❌ User explicitly declines when prompted during review
Design Drivers Framework
The Design Drivers subsection (Section 2.2.1) measures three impact dimensions:
1. Value Delivery
Definition: Effectiveness of change in customer experience
Threshold: >50% = High Impact, ≤50% = Low Impact
Data Source: Section 1 Executive Summary - Business Value bullets
Extraction Pattern: (\d{1,3})%\s*(reduction|improvement|increase|efficiency|optimization|cost\s*savings?|faster|time\s*savings?)
Calculation Logic:
- Read Section 1 Executive Summary (lines 25-55)
- Find all percentage metrics in Business Value subsection
- Extract maximum percentage value
- If ANY metric > 50% → HIGH Impact
- If ALL metrics ≤ 50% → LOW Impact
- Generate justification citing specific percentage and line number
Example:
- Input: "70% cost reduction" (Section 1, line 52)
- Output: HIGH Impact - "System delivers 70% cost reduction (Section 1, line 52)"
2. Scale
Definition: Estimated number of customers/transactions impacted
Threshold: >100K = High Impact, ≤100K = Low Impact
Data Source: Section 2.3 Use Cases - Success Metrics
Extraction Pattern: (\d{1,3}(?:,\d{3})*)\+?\s*(?:per\s*day|daily|customers?|users?|transactions?|reminders?|payments?|jobs?)
Calculation Logic:
- Read Section 2.3 Use Cases (approximate lines 100-165)
- Find all volume metrics in Success Metrics subsections
- Extract maximum customer/transaction count
- If MAX count > 100,000 → HIGH Impact
- If MAX count ≤ 100,000 → LOW Impact
- Generate justification citing specific volume and line number
Example:
- Input: "500,000+ reminders per day" (Section 2.3, line 141)
- Output: HIGH Impact - "System impacts 500,000 customers/day (Section 2.3, line 141)"
3. Impacts
Definition: Implementation complexity (configuration, development, deployment)
Threshold: >5 impacts = High Impact, ≤5 impacts = Low Impact
Data Sources: Section 5 Component Architecture + Section 8 Technology Stack
Extraction Method: Count subsection headers + table rows
Calculation Logic:
- Read Section 5 Component Details (approximate lines 456-675)
- Count component subsection headers matching pattern:
^###\s+\d+\.\d+
- Read Section 8 Technology Stack (approximate lines 912-998)
- Count technology table rows (excluding headers and separators)
- Total = component_count + technology_count
- If total > 5 → HIGH Impact
- If total ≤ 5 → LOW Impact
- Generate justification with breakdown
Example:
- Input: 5 components in Section 5, 3 technologies in Section 8
- Output: HIGH Impact - "System requires 8 components/technologies (Section 5: 5, Section 8: 3)"
6-Phase Calculation Workflow
Phase 1: Detection & User Prompt
Trigger Detection:
When user request contains keywords:
- "architecture review", "audit", "assess architecture"
- "calculate design drivers", "update design drivers"
- "design impact", "impact metrics"
User Prompt:
═══════════════════════════════════════════════════════════
Would you like me to calculate Design Drivers impact metrics?
═══════════════════════════════════════════════════════════
Design Drivers provide quantifiable assessment across 3 dimensions:
• Value Delivery: Customer experience effectiveness (from Section 1)
• Scale: Customer/transaction volume impacted (from Section 2.3)
• Impacts: Implementation complexity (from Sections 5 & 8)
This will analyze existing architecture data and update Section 2.2.1.
[Calculate Now] [Skip] [Learn More]
If user selects "Learn More", explain:
Design Drivers help you:
✓ Quantify business value of architecture decisions
✓ Justify complexity based on scale and impact
✓ Communicate architecture priorities to stakeholders
✓ Validate alignment between architecture and business goals
The calculation is automatic - metrics are extracted from:
• Section 1: Business value percentages
• Section 2.3: Customer/transaction volumes
• Section 5: Component count
• Section 8: Technology count
Results are presented for your review before updating the document.
Phase 2: Context-Efficient Data Loading
Sequential Loading Strategy (minimize context usage):
Read(file_path="ARCHITECTURE.md", offset=1, limit=50)
Read(file_path="ARCHITECTURE.md", offset=<section1_start-5>, limit=<section1_length+10>)
Read(file_path="ARCHITECTURE.md", offset=<section2.3_start-5>, limit=<section2.3_length+10>)
Read(file_path="ARCHITECTURE.md", offset=<section5_start-5>, limit=<section5_length+10>)
Read(file_path="ARCHITECTURE.md", offset=<section8_start-5>, limit=<section8_length+10>)
Context Buffer Guidelines:
- Add ±5-10 lines buffer to each section for context preservation
- Load sections sequentially (one at a time), not simultaneously
- Extract metrics immediately after loading each section
- Clear temporary data before loading next section
Phase 3: Metric Extraction & Calculation
Algorithm 1: Value Delivery Extraction
def extract_value_delivery(section1_text, section1_start_line):
business_value_match = re.search(r'\*\*Business Value:\*\*(.+?)(?=\n\n|\n\*\*|$)', section1_text, re.DOTALL)
if not business_value_match:
return {
'impact': 'LOW',
'justification': 'No quantifiable business value metrics found in Section 1',
'percentage': None,
'line': None
}
business_value_section = business_value_match.group(1)
percentage_pattern = r'(\d{1,3})%\s*(reduction|improvement|increase|efficiency|optimization|cost\s*savings?|faster|time\s*savings?)'
matches = re.finditer(percentage_pattern, business_value_section, re.IGNORECASE)
percentages = []
for match in matches:
percentage = int(match.group(1))
context = match.group(2)
line_offset = section1_text[:match.start()].count('\n')
line_number = section1_start_line + line_offset
percentages.append({
'value': percentage,
'context': context,
'line': line_number
})
if not percentages:
return {
'impact': 'LOW',
: ,
: ,
:
}
max_metric = (percentages, key= x: x[])
impact = max_metric[] >
{
: impact,
: ,
: max_metric[],
: max_metric[]
}
Algorithm 2: Scale Extraction
def extract_scale(section2_3_text, section2_3_start_line):
volume_pattern = r'(\d{1,3}(?:,\d{3})*)\+?\s*(?:per\s*day|daily|customers?|users?|transactions?|reminders?|payments?|jobs?)'
matches = re.finditer(volume_pattern, section2_3_text, re.IGNORECASE)
volumes = []
for match in matches:
volume_str = match.group(1).replace(',', '')
volume = int(volume_str)
context = match.group(0)
line_offset = section2_3_text[:match.start()].count('\n')
line_number = section2_3_start_line + line_offset
volumes.append({
'value': volume,
'context': context,
'line': line_number
})
if not volumes:
return {
'impact': 'LOW',
'justification': 'No volume metrics found in Use Cases success metrics',
'volume': None,
'line': None
}
max_volume = max(volumes, key=lambda x: x['value'])
impact = 'HIGH' if max_volume[] >
volume_formatted =
{
: impact,
: ,
: max_volume[],
: max_volume[]
}
Algorithm 3: Impacts Calculation
def calculate_impacts(section5_text, section8_text):
component_pattern = r'^###\s+\d+\.\d+\s+.+$'
component_matches = re.findall(component_pattern, section5_text, re.MULTILINE)
component_count = len(component_matches)
tech_table_pattern = r'^\|[^|]+\|[^|]+\|.+\|$'
separator_pattern = r'^\|\s*-+\s*\|'
tech_rows = []
for line in section8_text.split('\n'):
if re.match(tech_table_pattern, line) and not re.match(separator_pattern, line):
tech_rows.append(line)
technology_count = max(0, len(tech_rows) - 5)
total_impacts = component_count + technology_count
impact = 'HIGH' if total_impacts > 5 else 'LOW'
return {
'impact': impact,
'justification': f"System requires {total_impacts} components/technologies (Section 5: {component_count}, Section 8: )",
: component_count,
: technology_count,
: total_impacts
}
Phase 4: Generate Calculation Report & User Review
Report Format:
═══════════════════════════════════════════════════════════
DESIGN DRIVERS IMPACT METRICS CALCULATION
═══════════════════════════════════════════════════════════
Calculation Date: YYYY-MM-DD
Data Sources: Sections 1, 2.3, 5, 8
═══════════════════════════════════════════════════════════
## Value Delivery: [HIGH / LOW]
**Threshold**: >50% = High Impact
**Assessment**: [Percentage]% [context] exceeds threshold
**Justification**: System delivers [X]% [context] (Section 1, line [N])
**Source Data**: [Extracted percentage metric from Business Value]
## Scale: [HIGH / LOW]
**Threshold**: >100K = High Impact
**Assessment**: [Volume] [unit] exceeds threshold
**Justification**: System impacts [X] customers/day (Section 2.3, line [N])
**Source Data**: [Extracted volume metric from Success Metrics]
## Impacts: [HIGH / LOW]
**Threshold**: >5 = High Impact
**Assessment**: [Total] components/technologies exceeds threshold
**Justification**: System requires [Total] components/technologies (Section 5: [C], Section 8: [T])
**Breakdown**:
- Components (Section 5): [Component count]
- Technologies (Section 8): [Technology count]
═══════════════════════════════════════════════════════════
SUMMARY: [3/3 HIGH | 2/3 HIGH | 1/3 HIGH | 0/3 HIGH]
═══════════════════════════════════════════════════════════
Next Steps:
1. [Update Section 2.2.1] - Apply these metrics to Design Drivers subsection
2. [Preview Changes] - See exact updates before applying
3. [Manual Override] - Adjust values or classifications manually
4. [Export Report] - Save this report for documentation
5. [Skip Update] - Review only, don't modify ARCHITECTURE.md
Please select an option:
Interactive Review Options:
- Update Section 2.2.1: Proceed with applying metrics to Design Drivers subsection
- Preview Changes: Show exact before/after of Section 2.2.1
- Manual Override: User can adjust thresholds, classifications, or justifications
- Export Report: Save calculation report to separate file
- Skip Update: Review-only mode, don't modify document
Phase 5: Apply Changes to ARCHITECTURE.md
Insertion Logic:
-
Check if Section 2.2.1 exists:
Grep(pattern="### Design Drivers", path="ARCHITECTURE.md")
Grep(pattern="### 2\.2\.1", path="ARCHITECTURE.md")
-
If Section 2.2.1 DOES NOT exist (first-time insertion):
- Find end of Section 2.2 (Solution Overview)
- Insert new Design Drivers subsection after Section 2.2
- Update section numbering if needed (2.3 Use Cases remains 2.3)
- Update Document Index (Section 2 line range expands)
-
If Section 2.2.1 DOES exist (update existing):
- Read Section 2.2.1 content
- Update only the impact assessments and justifications
- Preserve structure and formatting
- Update "Last Calculated" date
- Update "Calculation Method" to "Automatic"
Section 2.2.1 Template (for insertion):
### 2.2.1 Design Drivers
This architecture is driven by the following key factors:
#### Value Delivery
**Description**: Effectiveness of change in customer experience
- **Threshold**: >50% = High Impact, ≤50% = Low Impact
- **Current Assessment**: [HIGH / LOW] Impact
- **Justification**: [Extracted justification with line reference]
#### Scale
**Description**: Estimated number of customers impacted
- **Threshold**: >100K = High, ≤100K = Low
- **Current Assessment**: [HIGH / LOW] Impact
- **Justification**: [Extracted justification with line reference]
#### Impacts
**Description**: Implementation complexity across configuration, development, and applications
- **Threshold**: >5 = High, ≤5 = Low
- **Current Assessment**: [HIGH / LOW] Impact
- **Justification**: [Extracted justification with component/technology counts]
**Last Calculated**: [YYYY-MM-DD]
**Calculation Method**: Automatic
Update Workflow:
Read(file_path="ARCHITECTURE.md", offset=82, limit=20)
Edit(file_path="ARCHITECTURE.md",
old_string="[End of Section 2.2 content]\n\n### 2.3 Primary Use Cases",
new_string="[End of Section 2.2 content]\n\n### 2.2.1 Design Drivers\n\n[Full template with calculated values]\n\n### 2.3 Primary Use Cases")
Edit(file_path="ARCHITECTURE.md",
old_string="**Current Assessment**: [old value]\n- **Justification**: [old justification]",
new_string="**Current Assessment**: [new value]\n- **Justification**: [new justification]")
Edit(file_path="ARCHITECTURE.md",
old_string="**Last Calculated**: YYYY-MM-DD",
new_string="**Last Calculated**: 2025-01-26")
grep -n "^## [0-9]" ARCHITECTURE.md
Phase 6: Completion Report & Verification
Completion Report Format:
═══════════════════════════════════════════════════════════
DESIGN DRIVERS UPDATE COMPLETE
═══════════════════════════════════════════════════════════
✓ Section 2.2.1 Design Drivers updated
✓ All three metrics calculated and applied
✓ Document Index updated (Section 2: Lines X-Y)
✓ Last Calculated: 2025-01-26
Summary of Metrics:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Value Delivery: HIGH (70% cost reduction)
Scale: HIGH (500,000 customers/day)
Impacts: HIGH (8 components/technologies)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Design Impact: 3/3 HIGH
Data Sources:
• Section 1 (Executive Summary): Business value metrics
• Section 2.3 (Use Cases): Success metrics and volumes
• Section 5 (Components): Component architecture details
• Section 8 (Technology Stack): Technology inventory
Next Steps:
• Review Section 2.2.1 for accuracy
• Use these metrics in architecture presentations
• Recalculate after significant architecture changes
• Include in quarterly architecture reviews
═══════════════════════════════════════════════════════════
Verification Steps:
- Read Section 2.2.1 to confirm updates applied correctly
- Verify Document Index reflects new line ranges
- Check "Last Calculated" date is current
- Confirm all three metrics (Value Delivery, Scale, Impacts) are present
- Validate justifications include source line numbers
Edge Cases & Error Handling
Edge Case 1: Missing Source Data
Scenario: No percentage metrics found in Section 1 Business Value
Handling:
⚠️ MISSING DATA: Value Delivery
No percentage-based metrics found in Section 1 Business Value.
Recommendations:
1. Add quantifiable business value metrics to Section 1
2. Provide manual override for Value Delivery assessment
3. Default to LOW impact with note: "No quantifiable metrics found"
Would you like to:
[Add Metrics to Section 1] [Manual Override] [Default to LOW]
Default Behavior:
- Value Delivery: LOW Impact with justification "No quantifiable business value metrics found in Section 1"
- Scale: LOW Impact with justification "No volume metrics found in Use Cases"
- Impacts: Calculate based on available data (Section 5 or 8, whichever exists)
Edge Case 2: Threshold Edge Cases (Exactly 50%, 100K, or 5)
Scenario: Metric value exactly equals threshold
Handling:
ℹ️ THRESHOLD EDGE CASE: Scale
Volume metric: Exactly 100,000 customers/day (Section 2.3, line 141)
Threshold rule: >100K = HIGH (not ≥)
Assessment: LOW Impact (100K is NOT > 100K)
Note: Consider if this is close enough to merit HIGH classification
Would you like to:
[Use LOW (strict threshold)] [Override to HIGH] [Review Context]
Default Rule:
- Thresholds use strict > operator (not ≥)
- 50% exactly → LOW
- 100,000 exactly → LOW
- 5 exactly → LOW
- Flag these cases for user review with note in justification
Edge Case 3: Conflicting Metrics (Multiple Percentages)
Scenario: Multiple different percentage metrics in Business Value
Example:
- 70% cost reduction
- 45% time savings
- 60% efficiency improvement
Handling:
ℹ️ MULTIPLE METRICS: Value Delivery
Found 3 percentage metrics in Business Value:
• 70% cost reduction (Line 52)
• 45% time savings (Line 53)
• 60% efficiency improvement (Line 54)
Using maximum value approach:
Selected: 70% cost reduction → HIGH Impact
Alternative: Could use average (58.3%) → still HIGH
Alternative: Could list all metrics in justification
Proceed with maximum value (70%)? [Yes] [Use Average] [Custom]
Default Behavior: Use maximum percentage value
Edge Case 4: Non-Standard Document Structure
Scenario: Document Index missing or section numbers non-standard
Handling:
-
Fallback Detection: Use grep to find sections by header text
grep -n "^## .*Executive Summary" ARCHITECTURE.md
grep -n "^### .*Primary Use Cases" ARCHITECTURE.md
grep -n "^## .*Component" ARCHITECTURE.md
grep -n "^## .*Technology Stack" ARCHITECTURE.md
-
Prompt User:
⚠️ NON-STANDARD STRUCTURE
Document Index not found or sections not in expected locations.
Would you like me to:
1. Search for sections by header text (slower but works)
2. Update document to standard structure first
3. Manually specify section line ranges
Recommended: Option 2 (standardize structure)
-
Graceful Degradation: Calculate what's possible, note what's missing
