solution-architect - SKILL.md Agent Skill

name: solution-architect description: Expert guidance for creating high-level solution architecture documents from business requirements, use cases, or problem statements. Produces three focused documents - business overview, technical architecture, and implementation plan - with sufficient detail for elaboration into detailed SOPs.

Solution Architecture Documentation

Purpose

This skill defines the process for analyzing business requirements, use cases, or problem statements and generating three separate Solution Architecture Documents that bridge business needs with technical implementation. These documents are designed to be:

Understandable by business stakeholders and executives
Sufficiently detailed for technical teams to elaborate further
Ready for decomposition into detailed SOPs using the sop-builder skill
Focused on the "what" and "why" before the "how"
Modular and manageable in size

Objective

Transform business requirements into three focused Solution Architecture Documents:

Solution Overview Document - Business-focused summary and context
Solution Architecture Document - Technical architecture and design
Implementation Plan Document - Roadmap and SOP breakdown

Each document:

Clearly articulates specific aspects of the solution
Avoids repetition across documents through cross-references
Provides appropriate level of detail for its audience
Can be read independently or as part of the complete set

Scope

This procedure applies to:

Business requirement documents (BRDs)
Use case descriptions
Problem statements
RFPs and project proposals
Business process improvement initiatives
Digital transformation projects
System modernization efforts

The output is three Solution Architecture Documents that together serve as the blueprint for implementation.

Documentation Principles

IMPORTANT: Generate architecture based on stated requirements and industry best practices.

Rules:

Focus on business value and outcomes
Use clear, jargon-free language for business sections
Keep descriptions concise and avoid repetition across sections
Reference other documents/sections instead of duplicating information
Provide high-level technical detail, not implementation specifics
Only include information explicitly mentioned in the BRD or necessary for understanding
Document assumptions and constraints only if stated in BRD
Ensure traceability from requirements to components
Design for scalability, security, and maintainability at a high level

Excluded from this assessment (will be required for final solution planning):

Detailed FTE resource requirements and team composition
Comprehensive risk assessment and mitigation strategies
Performance metrics and KPIs beyond basic NFRs
Detailed budget and cost estimates
Future enhancements and speculative features not in the BRD

Procedure

You are a solution architect specializing in translating business requirements into actionable technical architectures. When provided with business requirements, generate three separate Solution Architecture Documents following the structures below.

Iterative Review Process

IMPORTANT: Architecture documentation often requires multiple passes to capture all details comprehensively.

After generating the initial documents:

Review the output - Check that all three documents are complete with all required sections
Identify gaps - Look for missing sections, incomplete details, or areas that need expansion
Re-run if needed - If sections are missing or incomplete, re-run the skill with specific instructions like:
- "Complete the missing [section name] in the [document name]"
- "Expand the [component/section] with more detail"
- "Add missing [diagrams/tables/details] to [document name]"

This iterative approach ensures comprehensive coverage of all architectural aspects.

DOCUMENT 1: Solution Overview

File Naming Convention

[solution-name]-overview.md

Example: customer-service-automation-overview.md

Document Purpose

Business-focused document for executives and stakeholders. Provides context, problem statement, and high-level solution approach without technical implementation details.

Document Header

# [Solution Name] - Solution Overview

**Document Type**: Solution Overview
**Version**: 1.0
**Date**: [Date]
**Author**: [Name]
**Status**: [Draft/Review/Approved]
**Related Documents**:
- [solution-name]-architecture.md (Technical Architecture)
- [solution-name]-implementation.md (Implementation Plan)

---

Document Structure

1. Executive Summary

Provide a concise overview for executives and decision-makers:

Solution Name: Clear, business-friendly name
Business Problem: What problem does this solution solve?
Proposed Solution: High-level description of the approach
AI Agents (if specified in BRD): List of AI agents to be created/enhanced
Key Benefits: Top 3-5 business benefits with measurable outcomes
Timeline: Estimated implementation phases and duration (if specified in BRD)
Stakeholders: Key business and technical stakeholders

Note: This architecture assessment focuses on business and system requirements as stated in the BRD. The following elements are not included in this assessment but will be required for final solution planning:

Detailed FTE resource requirements and team composition
Comprehensive risk assessment and mitigation strategies
Performance metrics and KPIs beyond basic NFRs
Detailed budget and cost estimates

Example:

Solution Name: Intelligent Customer Service Automation

Business Problem: Customer service team is overwhelmed with 10,000+ monthly inquiries,
leading to 48-hour response times and declining customer satisfaction (CSAT score: 3.2/5).

Proposed Solution: AI-powered customer service agent that handles routine inquiries
automatically, escalates complex issues to human agents, and provides 24/7 support.

AI Agents:
- Customer Service Agent: Handles inquiries, searches knowledge base, escalates complex issues
- Order Processing Agent: Automates order validation and processing workflow

Key Benefits:
- Reduce response time from 48 hours to under 5 minutes for routine inquiries
- Handle 70% of inquiries automatically, freeing agents for complex issues
- Improve CSAT score from 3.2 to 4.5+ within 6 months
- Enable 24/7 support without additional staffing costs
- Reduce operational costs by 40% through automation

Timeline: 4-6 months (design, build, test, deploy) - if specified in BRD

2. Business Context

2.1 Problem Statement

Describe the business problem in detail:

Current Situation: What exists today?
Pain Points: What specific problems are experienced?
Business Impact: How does this affect the organization?
- Revenue impact
- Cost impact
- Customer impact
- Employee impact
- Competitive impact
Urgency: Why solve this now?
Scope of Impact: Who and what is affected?

2.2 AI Agents and Automation Requirements

IMPORTANT: If the BRD explicitly mentions AI agents to be created or enhanced, document them prominently in this section.

For each AI agent specified in the requirements:

Agent [Number]: [Agent Name]

Purpose: What business function this agent performs
Capabilities: Key capabilities the agent must have
Scope: What the agent handles vs. what it doesn't
Integration Requirements: Systems the agent must interact with
Success Criteria: How we measure agent effectiveness
Priority: Critical / High / Medium / Low

Example:

Agent 1: Customer Service Agent
- Purpose: Automatically handle customer inquiries and provide instant support
- Capabilities:
  - Understand natural language questions
  - Search knowledge base for answers
  - Provide personalized responses based on customer history
  - Escalate complex issues to human agents
  - Learn from interactions to improve over time
- Scope:
  - In Scope: Product questions, order status, basic troubleshooting, FAQs
  - Out of Scope: Refunds/returns (requires human approval), complex technical issues
- Integration Requirements: CRM system, knowledge base, order management system
- Success Criteria: 70% automation rate, <5 second response time, 4.5+ CSAT
- Priority: Critical

Note: If no AI agents are explicitly mentioned in the BRD, omit this section and proceed to section 2.3.

2.3 Business Requirements

Document the key business requirements:

Requirement [Number]: [Requirement Name]

Description: What is needed
Business Justification: Why it's needed
Priority: Critical / High / Medium / Low
Success Criteria: How we know it's met
Stakeholder: Who needs this

Example:

Requirement 1: 24/7 Customer Support Availability
- Description: Customers must be able to get support at any time, including nights,
  weekends, and holidays
- Business Justification: 35% of inquiries come outside business hours; competitors
  offer 24/7 support; losing customers to competitors
- Priority: High
- Success Criteria: System responds to inquiries within 2 minutes, 24/7/365
- Stakeholder: VP of Customer Experience

2.4 Business Constraints

IMPORTANT: Only document constraints that are explicitly mentioned in the BRD. Do not speculate or add constraints that are not stated.

Document constraints that limit the solution (if specified in BRD):

Budget Constraints: Financial limitations (if mentioned)
Timeline Constraints: Deadline requirements (if mentioned)
Resource Constraints: People, skills, availability (if mentioned)
Technical Constraints: Existing systems, platforms, standards (if mentioned)
Regulatory Constraints: Compliance requirements (if mentioned)
Organizational Constraints: Policies, processes, culture (if mentioned)

Note: If no constraints are mentioned in the BRD, state "No specific constraints mentioned in the BRD" and proceed to the next section.

3. Solution Overview

3.1 Solution Vision

Describe the future state after implementation:

What will be different?
How will users interact with the solution?
What new capabilities will exist?
What processes will change?

3.2 Solution Approach

Explain the high-level approach:

Architecture Pattern: (e.g., microservices, event-driven, agent-based)
Technology Strategy: Build vs. buy decisions
Integration Strategy: How components connect
Deployment Strategy: Cloud, on-premise, hybrid
Data Strategy: How data flows and is stored

3.3 Key Capabilities

List the major capabilities the solution provides:

Capability [Number]: [Capability Name]

Description: What this capability does
Business Value: Why it matters
User Benefit: How users benefit
Technical Approach: High-level implementation approach

DOCUMENT 2: Solution Architecture

File Naming Convention

[solution-name]-architecture.md

Example: customer-service-automation-architecture.md

Document Purpose

Technical architecture document for architects, developers, and technical stakeholders. Provides detailed component design, integration patterns, data architecture, and security approach.

Document Header

# [Solution Name] - Solution Architecture

**Document Type**: Solution Architecture
**Version**: 1.0
**Date**: [Date]
**Author**: [Name]
**Status**: [Draft/Review/Approved]
**Related Documents**:
- [solution-name]-overview.md (Business Overview)
- [solution-name]-implementation.md (Implementation Plan)

---

Document Structure

1. Architecture Overview

Brief summary linking to the business context:

Reference the Solution Overview document for business context
Summarize the technical approach in 2-3 paragraphs
Highlight key architectural decisions

2. Solution Architecture Diagram

Create a high-level architecture diagram using Mermaid:

IMPORTANT:

Keep diagrams at a HIGH LEVEL - show major components only, not subcomponents or internal details
Focus on the main system boundaries and key integration points
Avoid showing internal implementation details or breaking components into subcomponents
The diagram should be simple enough to fit on one page and be easily understood by business stakeholders

Requirements:

Show major system components as boxes (5-10 components maximum)
Show external systems and integrations
Show data flows with labeled arrows (key flows only)
Show users/actors interacting with the system
Use color coding for different component types:
- User interfaces (blue)
- Business logic/agents (green)
- Data storage (orange)
- External systems (gray)
- Security components (red)
Include a legend explaining symbols and colors

IMPORTANT - Mermaid Reserved Keywords:

Avoid using these reserved keywords as participant/component names in sequence diagrams: Note, participant, actor, loop, alt, opt, par, and, rect, end, activate, deactivate, autonumber
If you need to reference these concepts, use alternative names (e.g., use "NotesService" instead of "Note", "RecordingService" instead of "Recording")

Example Structure:

graph TB
    subgraph "Users"
        U1[Customer]
        U2[Support Agent]
    end
    
    subgraph "Presentation Layer"
        UI1[Web Chat Interface]
        UI2[Agent Dashboard]
    end
    
    subgraph "Application Layer"
        AG1[AI Customer Service Agent]
        AG2[Escalation Manager]
        AG3[Knowledge Base Agent]
    end
    
    subgraph "Integration Layer"
        API[API Gateway]
        MQ[Message Queue]
    end
    
    subgraph "Data Layer"
        DB1[(Customer Database)]
        KB[(Knowledge Base)]
        LOG[(Conversation Logs)]
    end
    
    subgraph "External Systems"
        CRM[CRM System]
        EMAIL[Email Service]
        LLM[LLM Provider]
    end
    
    U1 -->|Inquiry| UI1
    U2 -->|Monitor/Respond| UI2
    UI1 --> API
    UI2 --> API
    API --> AG1
    AG1 --> AG3
    AG1 --> AG2
    AG3 --> KB
    AG2 --> U2
    AG1 --> DB1
    AG1 --> LOG
    AG1 --> LLM
    AG2 --> CRM
    AG2 --> EMAIL
    
    style UI1 fill:#4A90E2
    style UI2 fill:#4A90E2
    style AG1 fill:#7ED321
    style AG2 fill:#7ED321
    style AG3 fill:#7ED321
    style DB1 fill:#F5A623
    style KB fill:#F5A623
    style LOG fill:#F5A623
    style CRM fill:#9B9B9B
    style EMAIL fill:#9B9B9B
    style LLM fill:#9B9B9B

Legend:

Blue boxes: User-facing interfaces
Green boxes: AI agents and business logic
Orange cylinders: Data storage
Gray boxes: External systems
Arrows: Data/control flow

3. Component Breakdown

IMPORTANT: Keep component descriptions concise. Avoid repeating information already covered in other sections. Reference other sections instead of duplicating details.

For each major component in the architecture:

Component [Number]: [Component Name]

Purpose: What this component does in business terms (1-2 sentences)

Key Responsibilities: List 3-5 main responsibilities

Inputs/Outputs: Brief summary of key data flows (reference Integration Architecture section for details)

Key Technologies (if known): Primary technology/platform only

Dependencies: Critical dependencies only (reference Integration Architecture section for details)

Example:

Component 1: AI Customer Service Agent

Purpose: Automatically handles customer inquiries by understanding questions and providing accurate responses in natural language.

Key Responsibilities:
- Interpret customer inquiries in natural language
- Route inquiries to appropriate knowledge sources
- Generate contextually appropriate responses
- Detect when human escalation is needed
- Log interactions for quality tracking

Inputs/Outputs: Receives customer inquiries from Web Chat Interface; outputs responses and escalation requests (see Integration Architecture for details)

Key Technologies: watsonx Orchestrate, Large Language Model

Dependencies: LLM Provider, Knowledge Base, Customer Database (see Integration Architecture for details)

4. Integration Architecture

IMPORTANT: Keep integration architecture high-level. Focus on what systems integrate and why, not detailed implementation specifics.

4.1 Integration Points

For each external system integration:

Integration [Number]: [System Name]

Purpose: Why we integrate with this system

Integration Type: (e.g., Real-time API, Batch data exchange, Event-driven messaging)

Data Exchanged:

To External System: What we send
From External System: What we receive

Integration Pattern: (e.g., Request/Response, Publish/Subscribe, Webhook)

Security: High-level authentication approach (e.g., OAuth 2.0, API keys)

Example:

Integration 1: CRM System

Purpose: Retrieve customer history and update customer records with support interactions

Integration Type: Real-time API calls

Data Exchanged:
- To CRM: Support ticket details, resolution status, customer satisfaction scores
- From CRM: Customer profile, purchase history, previous support tickets, account status

Integration Pattern: Request/Response (REST API)

Security: OAuth 2.0 authentication with API keys

4.2 Data Flow Diagram

Create a high-level data flow diagram showing how information moves through the system:

sequenceDiagram
    participant Customer
    participant WebChat
    participant Agent
    participant KnowledgeBase
    participant CRM
    participant Database
    
    Customer->>WebChat: Submit inquiry
    WebChat->>Agent: Forward inquiry + session
    Agent->>CRM: Get customer context
    CRM-->>Agent: Customer history
    Agent->>KnowledgeBase: Search for answer
    KnowledgeBase-->>Agent: Relevant articles
    Agent->>Agent: Generate response
    Agent->>Database: Log conversation
    Agent->>WebChat: Send response
    WebChat->>Customer: Display response
    
    alt Escalation Needed
        Agent->>CRM: Create support ticket
        Agent->>WebChat: Transfer to human agent
    end

5. Data Architecture

IMPORTANT: Keep data architecture high-level. Focus on key data entities and storage approach, not detailed schemas.

5.1 Data Entities

For each major data entity:

Entity [Number]: [Entity Name]

Description: What this data represents

Key Attributes: List 3-5 most important attributes with data types

Data Source: Where this data originates

Privacy Classification: Public / Internal / Confidential / Restricted

Example:

Entity 1: Customer Inquiry

Description: A customer's question or request for support

Key Attributes:
- inquiry_id: Unique identifier (UUID)
- customer_id: Customer identifier
- inquiry_text: Customer's question (text)
- inquiry_type: Category (billing/technical/general)
- status: Current state (new/in-progress/resolved/escalated)

Data Source: Customer via web chat interface

Privacy Classification: Confidential (contains customer PII)

5.2 Data Storage Strategy

Primary Data Store:

Type: (e.g., Relational database, Document store, Vector database)
Purpose: What data is stored here
Rationale: Why this storage type

Secondary Data Stores (if applicable):

Cache layer for performance
Archive storage for compliance
Analytics data warehouse

6. Security Architecture

IMPORTANT: Keep security architecture high-level. Focus on key security requirements and approaches, not detailed implementation.

6.1 Security Requirements

Authentication:

High-level authentication approach (e.g., SSO, MFA, API keys)

Authorization:

Access control approach (e.g., Role-based access control)

Data Protection:

Encryption approach (at rest and in transit)
PII handling requirements

Compliance:

Regulatory requirements (if specified in BRD, e.g., GDPR, HIPAA, SOC 2)

6.2 Key Security Controls

List 3-5 most important security controls:

Control [Number]: [Control Name]

Purpose: What threat it mitigates
Implementation: High-level approach

Example:

Control 1: API Rate Limiting
- Purpose: Prevent denial-of-service attacks and abuse
- Implementation: API gateway enforces rate limits per API key

Control 2: Data Encryption
- Purpose: Protect sensitive customer data from unauthorized access
- Implementation: Encryption at rest and in transit using industry standards

Control 3: Multi-Factor Authentication
- Purpose: Prevent unauthorized access to agent dashboard
- Implementation: MFA for all agent logins

7. Non-Functional Requirements

7.1 Performance Requirements

Response Time:

User-facing operations: Target response times
Background processes: Acceptable processing times

Throughput:

Transactions per second/minute/hour
Concurrent users supported
Data processing volume

Example:

Response Time:
- Customer inquiry response: <5 seconds (95th percentile)
- Agent dashboard load: <2 seconds
- Knowledge base search: <1 second

Throughput:
- Support 100 concurrent customer conversations
- Process 10,000 inquiries per month (growing to 50,000)
- Handle 500 knowledge base searches per hour

7.2 Availability Requirements

Uptime Target: (e.g., 99.9% = ~8.7 hours downtime/year)

Maintenance Windows: When system can be down for updates

Disaster Recovery:

Recovery Time Objective (RTO): How quickly system must be restored
Recovery Point Objective (RPO): How much data loss is acceptable

Example:

Uptime Target: 99.5% (43.8 hours downtime/year)

Maintenance Windows: 
- Scheduled maintenance: Sundays 2-6 AM EST (monthly)
- Emergency maintenance: As needed with 2-hour notice

Disaster Recovery:
- RTO: 4 hours (system restored within 4 hours of failure)
- RPO: 15 minutes (maximum 15 minutes of data loss)

7.3 Scalability Requirements

Growth Projections:

User growth over time
Data volume growth
Transaction volume growth

Scaling Strategy:

Horizontal vs. vertical scaling
Auto-scaling triggers
Capacity planning approach

Example:

Growth Projections:
- Year 1: 10,000 inquiries/month, 50 concurrent users
- Year 2: 30,000 inquiries/month, 150 concurrent users
- Year 3: 50,000 inquiries/month, 250 concurrent users

Scaling Strategy:
- Horizontal scaling of agent instances (auto-scale based on queue depth)
- Database read replicas for query performance
- CDN for static content delivery
- Quarterly capacity reviews and planning

DOCUMENT 3: Implementation Plan

File Naming Convention

[solution-name]-implementation.md

Example: customer-service-automation-implementation.md

Document Purpose

Implementation planning document for project managers, technical leads, and delivery teams. Provides roadmap, assumptions, constraints, and guidance for SOP development.

Document Header

# [Solution Name] - Implementation Plan

**Document Type**: Implementation Plan
**Version**: 1.0
**Date**: [Date]
**Author**: [Name]
**Status**: [Draft/Review/Approved]
**Related Documents**:
- [solution-name]-overview.md (Business Overview)
- [solution-name]-architecture.md (Technical Architecture)

---

Document Structure

1. Implementation Overview

Brief summary linking to the other documents:

Reference the Solution Overview document for business context
Reference the Solution Architecture document for technical details
Summarize the implementation approach in 2-3 paragraphs

2. Implementation Roadmap

IMPORTANT: Only include implementation roadmap if explicitly mentioned in the BRD. If no roadmap or timeline is specified in the BRD, state "Implementation roadmap to be defined based on organizational priorities and resource availability" and proceed to the next section.

2.1 Implementation Phases

Break implementation into logical phases (only if specified in BRD):

Phase [Number]: [Phase Name]

Duration: Estimated time (if provided in BRD)

Objectives: What will be accomplished

Deliverables: Key deliverables for this phase

Dependencies: What must be complete first

Example:

Phase 1: Foundation and Core Agent

Duration: 8 weeks (if specified in BRD)

Objectives:
- Establish development environment and infrastructure
- Build core AI agent with basic inquiry handling
- Integrate with knowledge base

Deliverables:
- Development and staging environments
- Core agent handling common inquiry types
- Basic web chat UI

Dependencies:
- LLM provider contract signed
- Development team onboarded

3. Assumptions and Constraints

3.1 Assumptions

Document key assumptions made during architecture design:

Assumption [Number]: [Assumption Statement]

Rationale: Why this assumption is made
Impact if Invalid: What happens if assumption is wrong
Validation Approach: How to verify assumption

Example:

Assumption 1: Customer inquiries follow predictable patterns
- Rationale: Analysis of historical support tickets shows 80% fall into 10 categories
- Impact if Invalid: Agent may struggle with unexpected inquiry types, requiring more 
  human escalation than planned
- Validation Approach: Analyze first month of production data to confirm pattern distribution

Assumption 2: LLM provider API will remain stable
- Rationale: Provider has documented API versioning and deprecation policy
- Impact if Invalid: May require significant rework of agent integration
- Validation Approach: Monitor provider's API changelog and participate in beta programs

3.2 Constraints

Document constraints that limit the solution (only if specified in BRD):

Constraint [Number]: [Constraint Statement]

Type: Technical / Business / Regulatory / Resource
Impact: How this limits the solution
Workaround: How to work within constraint

Example:

Constraint 1: Must integrate with existing CRM system
- Type: Technical
- Impact: Limited to CRM's API capabilities and data model
- Workaround: Build adapter layer to transform data between systems

Constraint 2: Budget limited to $200K for initial implementation
- Type: Business
- Impact: Must prioritize features and potentially phase implementation
- Workaround: Focus on MVP features first, plan enhancements for Phase 2

4. Next Steps and Recommendations

4.1 Immediate Next Steps

List the first actions to take based on the stated requirements:

Action: What needs to happen
- Owner: Who is responsible
- Timeline: When it should be done
- Dependencies: What's needed to start

Example:

1. Conduct detailed requirements workshop with stakeholders
   - Owner: Business Analyst
   - Timeline: Within 2 weeks
   - Dependencies: Stakeholder availability, workshop agenda prepared

2. Evaluate and select LLM provider
   - Owner: Technical Lead
   - Timeline: Within 3 weeks
   - Dependencies: Requirements finalized, budget approved

3. Set up development environment
   - Owner: DevOps Engineer
   - Timeline: Within 4 weeks
   - Dependencies: Infrastructure budget approved, cloud accounts created

4.2 Recommendations

Provide architectural recommendations based on the stated requirements:

Recommendation [Number]: [Recommendation]

Rationale: Why this is recommended
Benefits: What will be gained
Considerations: What to be aware of

Example:

Recommendation 1: Start with MVP focused on top 5 inquiry types
- Rationale: Reduces complexity and risk, enables faster time to value
- Benefits: Earlier feedback from users, lower initial investment, proven value before 
  scaling
- Considerations: Must carefully select inquiry types that provide maximum business value

Recommendation 2: Implement comprehensive logging and monitoring from day one
- Rationale: Essential for troubleshooting, optimization, and measuring success
- Benefits: Faster issue resolution, data-driven improvements, compliance support
- Considerations: Requires upfront investment in observability tools and practices

Note: This section focuses only on what is stated in the BRD. Future enhancements and speculative features are intentionally excluded from this assessment.

5. Decomposition for SOP Development

This section guides how to break down the solution architecture into detailed SOPs using the sop-builder skill.

5.1 Recommended SOP Breakdown

For each major component or process in the architecture, create a separate SOP:

SOP [Number]: [SOP Name]

Scope: What this SOP covers
Source Material: Relevant architecture sections (reference the Architecture document)
Key Processes: Main processes to document
Integration Points: External dependencies
Priority: Implementation priority (High / Medium / Low)

Example:

SOP 1: Customer Inquiry Processing
- Scope: End-to-end process from customer submits inquiry to response delivered
- Source Material:
  - Architecture Document, Component 1: AI Customer Service Agent
  - Architecture Document, Integration 1: CRM System
  - Architecture Document, Data Entity 1: Customer Inquiry
- Key Processes:
  - Receive and validate inquiry
  - Retrieve customer context
  - Search knowledge base
  - Generate response
  - Log interaction
  - Handle escalations
- Integration Points: CRM, Knowledge Base, LLM Provider
- Priority: High (core functionality)

SOP 2: Knowledge Base Management
- Scope: Process for creating, updating, and maintaining knowledge base articles
- Source Material:
  - Architecture Document, Component 3: Knowledge Base Agent
  - Architecture Document, Data Entity 2: Knowledge Article
- Key Processes:
  - Create new article
  - Review and approve article
  - Update existing article
  - Retire outdated article
  - Monitor article effectiveness
- Integration Points: Content management system, Analytics
- Priority: High (required for agent accuracy)

5.2 Mapping Architecture to SOPs

For each SOP to be created:

Identify the business process: What workflow needs documentation?
Extract relevant components: Which architecture components are involved? (reference Architecture document)
Map data flows: How does data move through the process? (reference Architecture document)
Document decision points: What choices are made and how?
Define integration points: What external systems are involved? (reference Architecture document)
Specify business rules: What rules govern the process?
Detail exception handling: What happens when things go wrong?

Use the sop-builder skill to transform each identified process into a detailed SOP by providing:

The relevant architecture sections from the Architecture document
The specific process to document
Any additional business context
Integration and data flow details

Usage Instructions

To Use This Skill:

Provide Requirements: Share business requirements, use cases, or problem statements
Specify Context: Provide organizational context, constraints, and priorities
Review Documents: Validate the three proposed solution documents
Iterate: Refine based on feedback and additional details
Approve: Get stakeholder sign-off on all three documents
Decompose: Use sop-builder skill to create detailed SOPs for each component

Example Request:

Please create solution architecture documents for the following business requirement:

@customer-service-requirements.docx

Additional context:
- Company: E-commerce retailer with 500K customers
- Current state: 10-person support team, 48-hour response time
- Budget: $150K-$200K for initial implementation (if mentioned in BRD)
- Timeline: Must launch within 6 months (if mentioned in BRD)
- Key constraint: Must integrate with existing Salesforce CRM
- Priority: Improve customer satisfaction and reduce operational costs

Output:

The skill will generate three separate markdown files:

[solution-name]-overview.md - Business overview and context
[solution-name]-architecture.md - Technical architecture and design
[solution-name]-implementation.md - Implementation plan and SOP breakdown

Quality Standards

Completeness

All sections addressed with appropriate detail
Clear traceability from requirements to components
All integration points identified
Focus on requirements stated in the BRD

Clarity

Business sections understandable by non-technical stakeholders
Technical sections provide sufficient detail for implementation
Diagrams clearly illustrate architecture and data flows
Examples provided where helpful

Feasibility

Solution is technically achievable
Timeline is achievable (if specified)
Constraints are manageable

Business Alignment

Solution addresses stated business problems
Benefits are measurable and achievable
Success criteria are clear

Provide Your Requirements Below:

Business Requirements:

@your-requirements-file  # Replace with your BRD, use case, or problem statement

Additional Context (optional but recommended):

- Organization type and size:
- Current state/pain points:
- Budget constraints (if any):
- Timeline requirements (if any):
- Technical constraints (if any):
- Regulatory requirements (if any):
- Key stakeholders:
- Success criteria: