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