architecture-docs

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:

1. Confirm: "I'll help you generate an architecture presentation Markdown file for Claude PowerPoint."
2. Jump directly to Workflow 8, Step 1 (Stakeholder Type Selection)
3. 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:

1. Confirm: "I'll help you generate architecture diagrams."
2. Jump directly to Workflow 9, Step 1 (Diagram Type Selection)
3. 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:

1. Acknowledge the skill invocation
2. Ask which workflow they want to use
3. 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

1. 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

2. 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)

3. 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

4. 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:

1. Find the Index: Read lines 1-50 to locate the Document Index
2. Identify Target Section: Check the index for exact line ranges
3. Load with Context Buffer: Read target section ± 10-20 lines for context preservation
4. 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:

1. Use grep -n "^## [0-9]" ARCHITECTURE.md to find actual section line numbers
2. Update the Document Index with current line ranges
3. Update "Index Last Updated" date
4. 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

1. Microservices Architecture (Recommended) - Cloud-native distributed systems with independent services
2. 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. 3-Tier Architecture - Classic web application pattern (Presentation → Application/Business Logic → Data)
4. N-Layer Architecture - Customizable patterns (DDD, Clean Architecture, Hexagonal)
5. 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:

1. Read the appropriate Section 4 template file
2. Read the appropriate Section 5 template file (if exists)
3. Extract template content (excluding metadata comments)
4. 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:

<!-- ARCHITECTURE_TYPE: META -->

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):

• Show ADR information:

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)

# Read Document Index to find Section 12 line range
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:

# Find Section 12 header line number
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:

# Using Read tool with line range from Step 6.2
Read(file_path="ARCHITECTURE.md", offset=1750, limit=50)

Parse ADR table rows:

# Extract ADR table rows using grep
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-:

1. Extract ADR number: 001, 002, etc. (from [ADR-001])
2. Extract file path from link: adr/ADR-001.md (from (adr/ADR-001.md))
3. Extract slug (if present): `` (empty) or database (from ADR-002-database.md)
4. Extract title: Column 2 (e.g., [Title] or Database Choice)
5. Extract status: Column 3 (e.g., Accepted, Proposed)
6. Extract date: Column 4 (e.g., YYYY-MM-DD or 2024-01-20)
7. 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:

# Example structure (pseudocode)
adrs = [
    {
        "number": "001",
        "slug": "",  # Empty means generate from title
        "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:

# Extract directory path from ARCHITECTURE.md location
# If ARCHITECTURE.md is in current directory, use "."
# Otherwise, extract directory from file path
ARCH_DIR="."

Define ADR directory path:

ADR_DIR="${ARCH_DIR}/adr"
# Results in: "./adr" relative to ARCHITECTURE.md

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

# Determine slug (pseudocode)
if adr["slug"] == "":
    # Generate slug from title using Step 6.6b rules
    slug = generate_slug(adr["title"])
else:
    # Use slug from file path in table
    slug = adr["slug"]

# Construct file path
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:

1. Convert title to lowercase
2. Replace spaces with hyphens
3. Remove special characters: :?/*<>|" (keep alphanumeric and hyphens)
4. Remove consecutive hyphens (replace -- with -)
5. Trim leading/trailing hyphens
6. Limit to 50 characters
7. If title is [Title] or placeholder, use slug untitled

Examples:

• Technology Stack Selection → technology-stack-selection
• REST vs. gRPC: Which API? → rest-vs-grpc-which-api
• PostgreSQL Database Choice → postgresql-database-choice
• [Title] → untitled

Step 6.6c: Check for Existing File

# Check if file already exists
if [ -f "adr/ADR-${number}-*.md" ]; then
    # File exists - trigger conflict handling
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

# Copy template (pseudocode)
adr_content = template_content

# Replace placeholders
adr_content = adr_content.replace("ADR-XXX", f"ADR-{adr['number']}")
adr_content = adr_content.replace("[Short Decision Title]", adr["title"])

# Replace status line (keep full line format from template)
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)

# Replace date
if adr["date"] == "YYYY-MM-DD" or adr["date"] == "[Date]":
    # Use current date
    current_date = datetime.now().strftime("%Y-%m-%d")
    adr_content = adr_content.replace("**Date**: YYYY-MM-DD", f"**Date**: {current_date}")
else:
    # Use date from table
    adr_content = adr_content.replace("**Date**: YYYY-MM-DD", f"**Date**: {adr['date']}")

# Replace authors (default to Architecture Team)
adr_content = adr_content.replace("**Authors**: [Author names or team name]", "**Authors**: Architecture Team")

# Replace related ADRs (empty by default)
adr_content = adr_content.replace("**Related**: [Links to related ADRs, e.g., ADR-001, ADR-005]", "**Related**: []")

Special handling for placeholder titles:

# If title is placeholder, add TODO note
if adr["title"] in ["[Title]", "[title]", "Title"]:
    # Add note about placeholder
    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"
    # Insert after first header (after "# ADR-XXX: [Title]" line)
    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 the file using Write tool
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:

# Check for BIAN indicators (check FIRST - most specific)
grep -E "(Layer 2: BIAN Business Scenarios|Layer 4: BIAN Service Domains)" ARCHITECTURE.md

# Check for META indicators
grep -E "(Layer 1: Channels|Layer 5: Domain|Layer 6: Core)" ARCHITECTURE.md

# Check for 3-Tier indicators
grep -E "(Tier 1: Presentation|Tier 3: Data)" ARCHITECTURE.md

# Check for Microservices indicators
grep -E "(API Gateway|Service Mesh|Microservices Catalog)" ARCHITECTURE.md

# Check for N-Layer indicators
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:

1. Detect current type using detection methods above

2. 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)
   

3. 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

4. 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:

1. Detects new ARCHITECTURE.md creation
2. Presents architecture type options (1-4)
3. User selects "3" (Microservices)
4. Loads templates/SECTION_4_MICROSERVICES.md and templates/SECTION_5_MICROSERVICES.md
5. 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 -->
6. 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:

1. Detect: Run grep -n "^## [0-9]" ARCHITECTURE.md to find section boundaries
2. Calculate: Parse output to determine line ranges (Section_Start to Next_Section_Start - 1)
3. Update: Edit Document Index (typically lines 5-21) with new ranges
4. Timestamp: Update "Index Last Updated" to current date
5. Report: Inform user which sections changed

Example:

# After adding content to Section 8, it grew from 906-980 to 912-996
grep -n "^## [0-9]" ARCHITECTURE.md
# Parse: Section 8 now at line 912, Section 9 at 998
# Calculate: Section 8 = 912-997, Section 9 = 998-1243
# Update index and report to user

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):

# For each metric in registry, search with appropriate pattern (new standardized TPS format)
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:

# If match found at line 787
Read(file_path="ARCHITECTURE.md", offset=782, limit=10)
# Reads lines 782-792 for context

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:

1. Check if line is in Section 1 (skip, that's the source of truth)
2. Read context (±5 lines) to understand what the metric represents
3. Compare metric concept (is this the same "Job Creation Capacity" or different metric?)
4. 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:

1. Show preview of all changes (exact before/after for each location)
2. Confirm user approval
3. Use Edit tool to update each location sequentially
4. Update Document Index if line numbers shift significantly (>10 lines)
5. 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:

• Use context-aware grep patterns to reduce false positives:

  • Bad: grep -n "100" ARCHITECTURE.md (too broad)
  • Good: grep -n "p95.*100ms" ARCHITECTURE.md (context-aware)
  • Better: grep -n "p95\s*<\s*100ms" ARCHITECTURE.md (exact pattern)

• If still >20 matches after context-aware patterns:

  1. Load only first 10 matches
  2. Present summary: "Found 47 matches for '100' - showing first 10 most relevant"
  3. Ask user if they want to see all or refine search pattern

Example: Complete Metric Update Workflow

Scenario: User updates Job Execution Capacity from 500 TPS to 700 TPS

Step-by-Step Execution:

1. User Action:

   User: "Update the job execution capacity to 700 TPS in the Executive Summary"
   

2. 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...
   

3. 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]
   

4. 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
   

5. 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
   

6. User Requests Preview:

   User: "Preview changes first"
   

7. 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:

1. Read Section 1 Executive Summary (lines 25-55)
2. Find all percentage metrics in Business Value subsection
3. Extract maximum percentage value
4. If ANY metric > 50% → HIGH Impact
5. If ALL metrics ≤ 50% → LOW Impact
6. 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:

1. Read Section 2.3 Use Cases (approximate lines 100-165)
2. Find all volume metrics in Success Metrics subsections
3. Extract maximum customer/transaction count
4. If MAX count > 100,000 → HIGH Impact
5. If MAX count ≤ 100,000 → LOW Impact
6. 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:

1. Read Section 5 Component Details (approximate lines 456-675)
2. Count component subsection headers matching pattern: ^###\s+\d+\.\d+
3. Read Section 8 Technology Stack (approximate lines 912-998)
4. Count technology table rows (excluding headers and separators)
5. Total = component_count + technology_count
6. If total > 5 → HIGH Impact
7. If total ≤ 5 → LOW Impact
8. 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):

# Load only required sections, NOT full document
# Total: ~400-500 lines vs 2000+ full document (75% reduction)

# Step 1: Load Document Index
Read(file_path="ARCHITECTURE.md", offset=1, limit=50)
# Parse index to get exact line ranges for Sections 1, 2, 5, 8

# Step 2: Load Section 1 Executive Summary
Read(file_path="ARCHITECTURE.md", offset=<section1_start-5>, limit=<section1_length+10>)
# Extract Business Value bullets, look for percentage metrics

# Step 3: Load Section 2.3 Use Cases
Read(file_path="ARCHITECTURE.md", offset=<section2.3_start-5>, limit=<section2.3_length+10>)
# Extract Success Metrics from all use cases, look for volume counts

# Step 4: Load Section 5 Component Details
Read(file_path="ARCHITECTURE.md", offset=<section5_start-5>, limit=<section5_length+10>)
# Count subsection headers (### X.X Component Name)

# Step 5: Load Section 8 Technology Stack
Read(file_path="ARCHITECTURE.md", offset=<section8_start-5>, limit=<section8_length+10>)
# Count technology table rows

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

# Pseudo-code for Value Delivery calculation
def extract_value_delivery(section1_text, section1_start_line):
    # Find Business Value subsection
    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)

    # Extract all percentage metrics
    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)
        # Calculate approximate line number within section
        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

# Pseudo-code for Scale calculation
def extract_scale(section2_3_text, section2_3_start_line):
    # Extract all volume metrics from Success Metrics subsections
    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:
        # Parse number (remove commas)
        volume_str = match.group(1).replace(',', '')
        volume = int(volume_str)
        context = match.group(0)
        # Calculate line number
        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
        }

    # Find maximum volume
    max_volume = max(volumes, key=lambda x: x['value'])

    # Apply threshold
    impact = 'HIGH' if max_volume[] >   

    
    volume_formatted = 

     {
        : impact,
        : ,
        : max_volume[],
        : max_volume[]
    }

Algorithm 3: Impacts Calculation

# Pseudo-code for Impacts calculation
def calculate_impacts(section5_text, section8_text):
    # Count component subsection headers in Section 5
    component_pattern = r'^###\s+\d+\.\d+\s+.+$'
    component_matches = re.findall(component_pattern, section5_text, re.MULTILINE)
    component_count = len(component_matches)

    # Count technology table rows in Section 8
    # Exclude header rows (contains | --- |) and empty rows
    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)

    # First row is typically header, so subtract 1
    # Count unique tables (Languages, Frameworks, Databases, etc.)
    # Approximate: count all rows and subtract ~4-6 header rows
    technology_count = max(0, len(tech_rows) - 5)  # Conservative estimate

    # Total impacts
    total_impacts = component_count + technology_count

    # Apply threshold
    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:

1. Update Section 2.2.1: Proceed with applying metrics to Design Drivers subsection
2. Preview Changes: Show exact before/after of Section 2.2.1
3. Manual Override: User can adjust thresholds, classifications, or justifications
4. Export Report: Save calculation report to separate file
5. Skip Update: Review-only mode, don't modify document

Phase 5: Apply Changes to ARCHITECTURE.md

Insertion Logic:

1. Check if Section 2.2.1 exists:

   Grep(pattern="### Design Drivers", path="ARCHITECTURE.md")
   # or
   Grep(pattern="### 2\.2\.1", path="ARCHITECTURE.md")
   

2. 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)

3. 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:

# Step 1: Find insertion point
Read(file_path="ARCHITECTURE.md", offset=82, limit=20)  # Section 2.2 Solution Overview
# Identify line number where Section 2.2 ends (before 2.3 Use Cases)

# Step 2: Insert or Update Section 2.2.1
# If new insertion:
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")

# If updating existing:
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]")

# Step 3: Update "Last Calculated" date
Edit(file_path="ARCHITECTURE.md",
     old_string="**Last Calculated**: YYYY-MM-DD",
     new_string="**Last Calculated**: 2025-01-26")  # Use current date

# Step 4: Update Document Index (if significant line shift)
# Run grep to detect new section positions
grep -n "^## [0-9]" ARCHITECTURE.md
# Update index line ranges if Section 2 grew by >10 lines

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:

1. Read Section 2.2.1 to confirm updates applied correctly
2. Verify Document Index reflects new line ranges
3. Check "Last Calculated" date is current
4. Confirm all three metrics (Value Delivery, Scale, Impacts) are present
5. 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:

1. 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
   

2. 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)
   

3. Graceful Degradation: Calculate what's possible, note what's missing