gh-dotclaude-marketplace-plugins-adaptive-learning/commands/learn_architecture.md

model, allowed-tools, argument-hint, description

model	allowed-tools	argument-hint	description
claude-opus-4-1	Task, Read, Write, Bash(*), Glob, Grep	<system> [--learning-objective=<goal>] [--complexity-progression=<approach>] [--pathway=<exploration-style>]	Scaffolded system architecture exploration with progressive complexity building

Architectural Learning System

Guide systematic architecture understanding through progressive complexity building, pattern recognition development, and hands-on exploration with adaptive scaffolding. Transform complex system architecture into accessible learning journeys that build deep understanding through guided discovery and practical investigation.

Learning Objective Framework

Comprehension Level (Understanding existing architecture)

[Extended thinking: Focus on understanding decisions already made, components already in place, and relationships already established in existing systems.]

Learning Goals:

• Component Understanding: Identify and understand individual system components and their responsibilities
• Relationship Mapping: Understand how components interact and depend on each other
• Decision Rationale: Comprehend why specific architectural choices were made
• Pattern Recognition: Identify common architectural patterns and their applications
• Trade-off Awareness: Understand benefits and costs of current architectural decisions

Exploration Methods:

• System documentation analysis with guided comprehension
• Component deep-dive investigation with scaffolded complexity
• Data flow tracing with step-by-step pathway exploration
• Interface examination with interaction pattern analysis
• Historical evolution study with decision context understanding

Analysis Level (Evaluating architectural trade-offs)

[Extended thinking: Develop critical evaluation skills for assessing architectural decisions, comparing alternatives, and understanding implications.]

Learning Goals:

• Trade-off Evaluation: Analyze benefits and costs of architectural decisions
• Alternative Assessment: Compare different approaches and understand their implications
• Quality Attribute Analysis: Evaluate architecture against performance, security, maintainability criteria
• Scalability Assessment: Understand how architecture handles growth and change
• Risk Identification: Recognize potential architectural vulnerabilities and limitations

Exploration Methods:

• Comparative analysis with multiple system examination
• What-if scenario exploration with alternative consideration
• Quality attribute testing with measurement and evaluation
• Bottleneck identification with performance analysis
• Failure mode analysis with resilience assessment

Synthesis Level (Designing new architectural solutions)

[Extended thinking: Develop creative capability for designing new architectural solutions that address specific requirements and constraints.]

Learning Goals:

• Requirements Translation: Convert functional requirements into architectural decisions
• Pattern Application: Apply architectural patterns appropriately to solve design problems
• Component Design: Create well-designed components with clear responsibilities
• Integration Strategy: Design effective component interaction and data flow
• Evolution Planning: Design architectures that can adapt and evolve over time

Exploration Methods:

• Design exercise completion with guided creativity
• Pattern application practice with scaffolded implementation
• Requirements analysis with architectural translation
• Prototype development with iterative refinement
• Peer review participation with collaborative learning

Evaluation Level (Assessing and comparing architectural alternatives)

[Extended thinking: Develop sophisticated judgment for evaluating architectural alternatives and making informed decisions about system design.]

Learning Goals:

• Multi-Criteria Assessment: Evaluate architectures against multiple quality attributes
• Context Sensitivity: Understand how context affects architectural appropriateness
• Future Readiness: Assess architecture's ability to handle future requirements
• Decision Justification: Articulate reasoning for architectural choices
• Optimization Identification: Recognize opportunities for architectural improvement

Exploration Methods:

• Architecture review facilitation with evaluation criteria application
• Decision framework development with structured analysis
• Future scenario planning with adaptability assessment
• Optimization identification with improvement planning
• Cross-system comparison with pattern extraction

Complexity Progression Framework

Component Level (Individual service/module understanding)

[Extended thinking: Start with single components to build foundational understanding before tackling system-wide complexity.]

Progression Strategy:

1. Single Component Deep Dive: Understand one component's responsibilities, interfaces, and implementation
2. Interface Analysis: Examine how component exposes functionality and manages dependencies
3. Internal Structure: Explore component's internal organization and design patterns
4. Quality Attributes: Assess component's performance, security, and maintainability characteristics
5. Evolution Patterns: Understand how component has changed over time and why

Scaffolding Approach:

• Start with simplest, most isolated components
• Use visual diagrams to represent component structure
• Provide concrete examples of component behavior
• Connect component design to familiar concepts
• Gradually introduce technical vocabulary and concepts

Interaction Level (Service communication and data flow)

[Extended thinking: Build understanding of how components work together, focusing on interfaces, protocols, and data exchange patterns.]

Progression Strategy:

1. Two-Component Interaction: Understand communication between two related components
2. Protocol Analysis: Examine communication methods and data formats
3. Data Flow Tracing: Follow information as it moves through component interactions
4. Error Handling: Understand how components handle interaction failures
5. Multi-Component Coordination: Explore how multiple components coordinate for complex operations

Scaffolding Approach:

• Use sequence diagrams to visualize interactions
• Trace specific user scenarios through component communications
• Provide hands-on exploration of API calls and data formats
• Build understanding of synchronous vs. asynchronous patterns
• Connect interaction patterns to familiar communication analogies

System Level (End-to-end architecture comprehension)

[Extended thinking: Develop holistic understanding of complete system architecture including all components, interactions, and emergent properties.]

Progression Strategy:

1. System Boundary Definition: Understand what's inside vs. outside the system
2. Subsystem Organization: Recognize how system is organized into logical groupings
3. Cross-System Data Flows: Trace information as it flows through entire system
4. Quality Attribute Emergence: Understand how system-level properties emerge from component interactions
5. Evolution and Growth: Comprehend how system architecture supports change and scaling

Scaffolding Approach:

• Build system understanding through layered architectural views
• Use real user scenarios to demonstrate end-to-end system behavior
• Provide multiple perspectives (logical, physical, deployment) on same system
• Connect system design to business capabilities and user value
• Guide recognition of architectural patterns at system level

Ecosystem Level (Multi-system integration understanding)

[Extended thinking: Develop understanding of how systems integrate with other systems, platforms, and external services in broader technological ecosystems.]

Progression Strategy:

1. External Dependencies: Identify and understand systems that this system depends on
2. Integration Patterns: Recognize common patterns for system-to-system communication
3. Data Consistency: Understand how data consistency is maintained across system boundaries
4. Service Boundaries: Comprehend how responsibilities are divided between different systems
5. Ecosystem Evolution: Understand how multi-system architectures evolve and adapt over time

Scaffolding Approach:

• Map ecosystem relationships with visual system context diagrams
• Explore integration challenges through concrete failure scenarios
• Build understanding of distributed system patterns and trade-offs
• Connect ecosystem design to organizational and business considerations
• Guide recognition of industry-standard integration approaches

Exploration Methodology

Hands-On Investigation Protocol

[Extended thinking: Balance theoretical understanding with practical exploration through direct system interaction and experimentation.]

Investigation Techniques:

• Code Archaeology: Systematic exploration of system codebase with guided discovery
• Runtime Exploration: Live system investigation with monitoring and observability tools
• Configuration Analysis: Understanding system behavior through configuration examination
• Interface Testing: Hands-on exploration of system APIs and interfaces
• Performance Profiling: Empirical investigation of system performance characteristics

Guided Discovery Process:

1. Hypothesis Formation: Develop predictions about system behavior
2. Investigation Design: Plan systematic exploration to test hypotheses
3. Evidence Collection: Gather data through direct system interaction
4. Pattern Recognition: Identify recurring themes and architectural patterns
5. Understanding Synthesis: Integrate discoveries into coherent architectural comprehension

Pattern Building Framework

[Extended thinking: Help learners recognize and understand common architectural patterns through systematic pattern exploration and application.]

Pattern Learning Progression:

1. Pattern Recognition: Identify pattern instances in familiar systems
2. Pattern Abstraction: Understand pattern's essential characteristics and motivations
3. Pattern Variations: Explore different implementations and adaptations of patterns
4. Pattern Application: Apply patterns to new contexts and problems
5. Pattern Composition: Understand how patterns combine in complex architectures

Scaffolding Strategies:

• Start with patterns visible in everyday technology experiences
• Use concrete examples before introducing abstract pattern definitions
• Provide pattern templates and checklists for recognition
• Encourage pattern spotting in multiple different systems
• Build personal pattern library with documented examples

Execution Examples

Example 1: Microservices Architecture Learning

learn_architecture "e-commerce platform microservices" --learning-objective=comprehension --complexity-progression=component --pathway=hands-on

Learning Flow:

1. Component Focus: Start with single service (e.g., Product Catalog Service)

   • Understand service responsibilities and boundaries
   • Explore service API and data models
   • Investigate internal service structure
   • Trace service's role in user scenarios

2. Scaffolded Exploration:

   • "Let's start with something familiar - think of an online store you use..."
   • "The Product Catalog Service is like the store's inventory system..."
   • "What information would you need to display a product page?"
   • "How might this service connect to other parts of the system?"

3. Hands-On Investigation:

   • Examine actual API endpoints with curl or Postman
   • Review service code structure and organization
   • Explore service configuration and deployment
   • Monitor service behavior with observability tools

Example 2: Distributed System Trade-offs Analysis

learn_architecture "payment processing system" --learning-objective=analysis --complexity-progression=system --pathway=comparative

Learning Flow:

1. System-Level Analysis: Examine complete payment processing architecture

   • Map all components involved in payment processing
   • Understand different payment methods and their architectural implications
   • Analyze consistency, availability, and partition tolerance trade-offs
   • Evaluate security and compliance considerations

2. Comparative Exploration:

   • "How does this architecture compare to simpler, monolithic payment processing?"
   • "What trade-offs were made to achieve high availability?"
   • "How would you evaluate the security vs. performance balance?"
   • "What alternative approaches might address the same requirements?"

3. Trade-off Assessment:

   • Performance analysis with load testing and measurement
   • Failure scenario exploration with chaos engineering
   • Cost analysis with infrastructure and operational considerations
   • Scalability assessment with growth projection modeling

Example 3: Architecture Design Practice

learn_architecture "social media platform design" --learning-objective=synthesis --complexity-progression=ecosystem --pathway=creative

Learning Flow:

1. Ecosystem-Level Design: Create architecture for large-scale social platform

   • Identify all major functional areas and their relationships
   • Design service boundaries and integration patterns
   • Plan for global scale and diverse user requirements
   • Consider ecosystem integration with external platforms

2. Creative Design Process:

   • "If you were building the next social platform, what would be your core architectural principles?"
   • "How would you handle the feed generation challenge at global scale?"
   • "What patterns would you use for user-generated content and moderation?"
   • "How would your architecture evolve as the platform grows?"

3. Synthesis Practice:

   • Requirements analysis with stakeholder perspective consideration
   • Architecture sketch development with iterative refinement
   • Pattern application with creative adaptation to specific requirements
   • Peer review and feedback integration with collaborative improvement

Advanced Learning Features

Adaptive Scaffolding System

[Extended thinking: Dynamically adjust learning support based on learner progress and comprehension signals.]

Scaffolding Calibration:

• Novice Support: Heavy visual aids, concrete examples, step-by-step guidance
• Intermediate Adaptation: Moderate scaffolding with guided discovery emphasis
• Advanced Challenge: Light guidance with peer-level collaboration
• Expert Partnership: Co-exploration with knowledge co-construction

Dynamic Adjustment:

• Monitor comprehension through question quality and insight depth
• Adjust complexity based on learner confidence and curiosity signals
• Modify exploration style based on learning preference indicators
• Provide additional support when confusion or frustration detected

Metacognitive Development

[Extended thinking: Help learners understand their own learning process and develop self-directed architecture learning capabilities.]

Self-Awareness Building:

• "What aspects of architecture are most challenging for you?"
• "How do you approach understanding complex systems?"
• "What patterns help you organize architectural information?"
• "When do you feel most confident in your architectural understanding?"

Learning Strategy Development:

• Help learners identify effective personal learning approaches
• Build toolkit of investigation and analysis methods
• Develop pattern recognition and abstraction skills
• Foster curiosity and systematic exploration habits

Success Indicators

Understanding Quality Measures

• Conceptual Clarity: Clear comprehension of architectural concepts and relationships
• Pattern Recognition: Ability to identify and apply architectural patterns appropriately
• Trade-off Awareness: Understanding of architectural decision implications and alternatives
• Transfer Capability: Application of architectural understanding to new contexts
• Critical Thinking: Evaluation and critique of architectural approaches

Learning Engagement

• Curiosity Activation: Questions and exploration drive beyond assigned investigation
• Hands-on Participation: Active engagement with systems and tools
• Pattern Seeking: Natural tendency to look for architectural patterns and connections
• Creative Application: Innovation in applying architectural understanding to new problems

The learn_architecture command transforms complex system architecture into accessible learning experiences, building deep understanding through progressive complexity, hands-on exploration, and pattern recognition development.