# Layer 01 Motiv > Expert knowledge for Motivation Layer modeling in Documentation Robotics Use when this capability is needed. - Skill: `tomevault-io/layer-01-motiv` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/layer-01-motiv` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/layer-01-motiv/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/layer-01-motiv --- # Motivation Layer Skill **Layer Number:** 01 **Specification:** Metadata Model Spec v0.8.3 **Purpose:** Captures stakeholder concerns, goals, requirements, and constraints that drive architectural decisions using ArchiMate motivation elements. --- ## Layer Overview The Motivation Layer is the **highest layer** in the 12-layer architecture and provides governance to all other layers. It describes: - **WHY** - The reasons and drivers behind architectural decisions - **WHO** - Stakeholders with interests in the outcome - **WHAT** - Goals, requirements, principles, and constraints - **VALUE** - The worth and importance of business outcomes This layer uses **ArchiMate 3.2 Motivation Layer** standard without custom extensions. --- ## Entity Types > **CLI Introspection:** Run `dr schema types motivation` for the authoritative, always-current list of node types. > Run `dr schema node ` for full attribute details on any type. | Entity Type | Description | Key Attributes | | --------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | **Stakeholder** | Individual, team, or organization with interest in the outcome | Types: internal, external, customer, partner, regulator | | **Driver** | External or internal condition that motivates an organization | Categories: market, regulatory, technology, competitive, operational, strategic | | **Assessment** | Outcome of analysis of the state of affairs (SWOT) | Types: strength, weakness, opportunity, threat, risk, gap | | **Goal** | High-level statement of intent, direction, or desired end state | Priority: critical, high, medium, low. Can be SMART (measurable, target-date, KPI) | | **Outcome** | End result that has been achieved | Status: planned, in-progress, achieved, not-achieved | | **Principle** | Normative property of all systems in a given context | Categories: business, data, application, technology, security, integration | | **Requirement** | Statement of need that must be realized | Types: functional, non-functional, business, technical, compliance, user | | **Constraint** | Restriction on the way in which a system is realized | Types: budget, time, technology, regulatory, organizational, resource | | **Meaning** | Knowledge or expertise present in a representation | Used to describe semantics and interpretations | | **Value** | Relative worth, utility, or importance of something | Types: financial, customer, operational, strategic, social | --- ## Type Decision Tree Use this decision tree **before assigning a type** to any motivation concept. ``` IS this an individual, team, or organization with an interest in the system or its outcomes? → motivation.stakeholder IS this an external or internal condition (market, regulatory, technology, competitive, operational, strategic) that motivates the organization to change or act? → motivation.driver IS this the result of analyzing the current state — a strength, weakness, opportunity, threat, risk, or gap identified through assessment (e.g., SWOT)? → motivation.assessment IS this a high-level statement of intent, direction, or desired end state the organization wants to achieve? → motivation.goal IS this a specific, verifiable statement of need that must be realized (functional, non-functional, compliance, business, technical, or user need)? → motivation.requirement IS this a normative rule or guideline that all systems in this context must follow (business, data, application, technology, security, integration)? → motivation.principle IS this a hard restriction on HOW the system can be realized — a limit the system cannot exceed (budget, time, technology, regulatory, organizational, resource)? → motivation.constraint IS this an end result that has been or is being achieved — tracked against a goal? → motivation.outcome IS this the relative worth, utility, or importance that the system or feature delivers? → motivation.value IS this a semantic definition, interpretation, or piece of knowledge attached to another element? → motivation.meaning ``` **Key distinctions:** - **Goal vs Requirement**: A Goal is aspirational ("improve performance"); a Requirement is a verifiable must ("API must respond in <200ms") - **Requirement vs Constraint**: A Requirement says WHAT must be done; a Constraint says HOW it is bounded ("must use OAuth 2.0" limits the solution space) - **Driver vs Assessment**: A Driver is an ongoing force motivating action; an Assessment is a point-in-time finding about the current state - **Outcome vs Goal**: A Goal is what you intend to achieve; an Outcome is what has been (or is being) achieved --- ## Intra-Layer Relationships ### Structural Relationships | Source Type | Predicate | Target Type | Example | | ----------- | ----------- | ----------- | ------------------------------------------------------------ | | Goal | aggregates | Goal | Strategic Goal aggregates Operational Goals | | Requirement | aggregates | Requirement | Business Requirement aggregates Functional Requirements | | Principle | aggregates | Principle | Enterprise Principles aggregate Domain Principles | | Constraint | aggregates | Constraint | Budget Constraint aggregates Project Budget Constraints | | Outcome | realizes | Goal | "Launched Mobile App" realizes "Launch Mobile App by Q4" | | Goal | realizes | Value | "Improve Customer Satisfaction" realizes "Customer Value" | | Requirement | realizes | Goal | Functional Requirements realize Business Goals | | Requirement | realizes | Principle | Technical Requirements realize Security Principles | | Constraint | realizes | Principle | Technology Constraints realize Technology Principles | | Goal | specializes | Goal | "Reduce API Latency" specializes "Improve Performance" | | Requirement | specializes | Requirement | "95% Uptime SLA" specializes "High Availability Requirement" | | Principle | specializes | Principle | "Encrypt All PII" specializes "Data Security Principle" | | Value | specializes | Value | "Customer Retention Value" specializes "Customer Value" | ### Behavioral Relationships | Source Type | Predicate | Target Type | Example | | ----------- | --------------- | ----------- | ----------------------------------------------------------------------- | | Driver | influences | Goal | "Digital Transformation" influences "Modernize Architecture" | | Driver | influences | Requirement | "GDPR Compliance" influences "Data Protection Requirements" | | Driver | influences | Principle | "Cloud-First Strategy" influences "Cloud-Native Principles" | | Assessment | influences | Goal | "Legacy System Weakness" influences "Modernization Goal" | | Goal | influences | Requirement | Business Goals influence Functional Requirements | | Principle | influences | Requirement | Security Principles influence Technical Requirements | | Principle | influences | Constraint | "API-First Principle" influences "RESTful API Constraint" | | Constraint | influences | Requirement | Budget Constraints influence Implementation Requirements | | Value | influences | Goal | "Customer Value" influences "Improve UX Goal" | | Stakeholder | influences | Goal | "CEO" influences Strategic Goals | | Stakeholder | influences | Requirement | "End Users" influence Functional Requirements | | Stakeholder | influences | Value | "Shareholders" influence Financial Value | | Stakeholder | associated-with | Driver | "Product Manager" associated with "Market Competition Driver" | | Goal | associated-with | Outcome | "Improve Performance" associated with "Achieved 50ms Latency" | | Requirement | associated-with | Outcome | "High Availability Requirement" associated with "99.99% Uptime Outcome" | | Driver | associated-with | Assessment | "Market Driver" associated with "Competitive Threat Assessment" | | Value | associated-with | Meaning | "Customer Value" associated with "Definition of Customer Success" | --- ## Cross-Layer References **Motivation Layer is the highest layer** - It does **NOT reference any lower layers**. Instead, lower layers reference UP to this layer for governance. ### Incoming References (Lower Layers → Motivation) | Layer | References Motivation For | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | **Layer 2 (Business)** | BusinessService delivers Value, supports Goals, governed by Principles; BusinessActor is Stakeholder; Contract drives Constraints | | **Layer 3 (Security)** | Actor references Stakeholder; ActorObjective references Goal; Threat references Assessment; Countermeasure implements Requirement | | **Layer 4 (Application)** | ApplicationService supports Goals, delivers Value, governed by Principles; ApplicationFunction fulfills Requirements | | **Layer 5 (Technology)** | TechnologyService supports Goals, governed by Principles; Node fulfills Requirements, constrained by Constraints | | **Layer 6 (API)** | Operation supports Goals (x-supports-goals), fulfills Requirements, governed by Principles, constrained by Constraints | | **Layer 7-12** | All layers can reference Principles, Constraints, Requirements, Goals for governance and traceability | **Design Pattern:** Lower layers "look up" to the Motivation layer to justify WHY they exist and WHAT value they deliver. --- ## Codebase Detection Patterns The Motivation Layer is typically **NOT extracted from code** but documented separately. However, certain patterns suggest the need for motivation elements: ### Pattern 1: Requirements Traceability Comments ```python # REQUIREMENT: REQ-001 - User authentication must support OAuth 2.0 # GOAL: Improve security and user experience # PRINCIPLE: Security by design def configure_oauth(provider: str): pass ``` **Maps to:** - Requirement entity (REQ-001) - Goal entity (improve security) - Principle entity (security by design) ### Pattern 2: Non-Functional Requirements in Tests ```python @npm test.mark.performance def test_api_response_time(): """Verify API responds within 200ms (GOAL: sub-second response)""" response_time = measure_api_call() assert response_time < 0.2 # Constraint: < 200ms ``` **Maps to:** - Goal (sub-second response) - Constraint (< 200ms) - Requirement (performance requirement) ### Pattern 3: Configuration Constants ```python # Constraint: Budget limit for cloud spending MAX_MONTHLY_CLOUD_COST = 10000 # USD # Principle: Data residency compliance ALLOWED_REGIONS = ["us-east-1", "us-west-2"] # Constraint: US-only # Goal: 99.99% availability TARGET_UPTIME_SLA = 0.9999 ``` **Maps to:** - Constraint entities (budget, region) - Goal (availability target) - Principle (data residency) ### Pattern 4: README/Documentation Headers ```markdown ## Goals - Achieve 99.9% system availability - Reduce customer onboarding time to < 5 minutes - Support 10,000 concurrent users ## Principles - API-first architecture - Microservices over monoliths - Security by design ## Constraints - Budget: $500K for 2024 - Timeline: Launch by Q3 2024 - Technology: Must run on AWS ``` **Maps to:** Direct creation of Goal, Principle, and Constraint entities --- ## Coverage Completeness Checklist Before declaring motivation layer extraction complete, verify each type was considered: - [ ] **stakeholder** — All individuals, teams, and organizations with interests in the system are documented - [ ] **driver** — External and internal forces motivating architectural decisions are captured - [ ] **assessment** — SWOT-style findings (strengths, weaknesses, opportunities, threats, risks, gaps) are recorded - [ ] **goal** — High-level intentions and desired end states are defined with priority - [ ] **requirement** — Specific needs that must be realized are documented (functional, non-functional, compliance, etc.) - [ ] **principle** — Normative guidelines governing all system implementations are listed - [ ] **constraint** — Hard limits and restrictions on system realization are documented - [ ] **outcome** — Achieved or tracked results linked to goals are recorded - [ ] **value** — The worth and utility delivered by the system or feature is articulated - [ ] **meaning** — Semantic definitions or knowledge interpretations are captured where elements need clarification If any type has ZERO elements, explicitly decide: "This type doesn't apply to this codebase" with reasoning. --- ## Modeling Workflow ### Step 1: Identify Stakeholders Start by documenting **WHO cares** about the system: ```bash # Add key stakeholders dr add motivation stakeholder "End Users" \ --description "Customers using the platform" dr add motivation stakeholder "Product Manager" \ --description "Defines product vision and priorities" dr add motivation stakeholder "Compliance Team" \ --description "Ensures regulatory compliance" ``` ### Step 2: Document Drivers and Assessments Identify **WHAT is pushing** the organization: ```bash # Market driver dr add motivation driver "Cloud Migration Pressure" \ --description "Industry shift to cloud-native architectures" # SWOT assessment dr add motivation assessment "Legacy System Debt" \ --description "Monolithic architecture limits agility" dr add motivation assessment "Strong Engineering Team" \ --description "Experienced team with cloud expertise" ``` ### Step 3: Define Goals and Values Articulate **WHAT we want to achieve**: ```bash # Strategic goal dr add motivation goal "Modernize Architecture" \ --description "Migrate to microservices architecture" # Value delivered dr add motivation value "Operational Efficiency" \ --description "Reduced deployment time and increased reliability" ``` ### Step 4: Specify Requirements and Principles Define **HOW we will operate**: ```bash # Functional requirement dr add motivation requirement "API Authentication" \ --description "All API endpoints must authenticate users" # Guiding principle dr add motivation principle "API-First Design" \ --description "All services expose RESTful APIs with OpenAPI specs" # Hard constraint dr add motivation constraint "AWS-Only Infrastructure" \ --description "All services must deploy to AWS (no multi-cloud)" ``` ### Step 5: Establish Relationships Connect motivation elements using predicates: ```bash # Driver influences Goal dr relationship add motivation.driver.cloud-migration-pressure \ motivation.goal.modernize-architecture --predicate influences # Goal realizes Value dr relationship add motivation.goal.modernize-architecture \ motivation.value.operational-efficiency --predicate realizes # Principle influences Requirement dr relationship add motivation.principle.api-first-design \ motivation.requirement.api-authentication --predicate influences # Stakeholder influences Goal dr relationship add motivation.stakeholder.product-manager \ motivation.goal.modernize-architecture --predicate influences # Assessment influences Goal dr relationship add motivation.assessment.legacy-system-debt \ motivation.goal.modernize-architecture --predicate influences ``` ### Step 6: Validate ```bash dr validate --layers motivation dr validate --relationships ``` --- ## Traceability Patterns ### Pattern 1: Goal Decomposition Hierarchy ``` Strategic Goal: "Improve Customer Satisfaction" ├── aggregates → Business Goal: "Reduce Response Time" │ ├── aggregates → Operational Goal: "Achieve <100ms API Latency" │ └── aggregates → Operational Goal: "Implement Caching Layer" └── aggregates → Business Goal: "Improve Mobile Experience" ├── aggregates → Operational Goal: "Launch iOS App" └── aggregates → Operational Goal: "Launch Android App" ``` ### Pattern 2: Requirement Hierarchy ``` Business Requirement: "Secure User Data" ├── aggregates → Functional Requirement: "Encrypt Data at Rest" │ └── influences → Technical Requirement: "Use AES-256 Encryption" ├── aggregates → Functional Requirement: "Encrypt Data in Transit" │ └── influences → Technical Requirement: "Use TLS 1.3" └── aggregates → Compliance Requirement: "GDPR Data Protection" └── influences → Technical Requirement: "Right to Deletion API" ``` ### Pattern 3: Principle Application ``` Principle: "Cloud-Native Architecture" ├── influences → Requirement: "Containerized Deployments" ├── influences → Requirement: "Stateless Services" ├── influences → Constraint: "No On-Premise Infrastructure" └── realizes → Value: "Scalability and Resilience" ``` ### Pattern 4: Stakeholder → Goal → Implementation Chain ``` Stakeholder: "CEO" └── influences → Goal: "Reduce Operating Costs by 20%" ├── influences → Requirement: "Automated CI/CD Pipeline" ├── influences → Principle: "Infrastructure as Code" └── realizes → Value: "Financial Efficiency" └── (lower layers reference this chain) ``` --- ## Common Modeling Scenarios ### Scenario 1: New Feature Justification **Question:** "Why are we building this feature?" **Approach:** 1. Add **Stakeholder** who requested it 2. Add **Driver** (market, customer, regulatory) 3. Add **Goal** the feature achieves 4. Add **Value** delivered 5. Lower layers reference the Goal ### Scenario 2: Regulatory Compliance **Question:** "How do we track GDPR compliance?" **Approach:** 1. Add **Driver** ("GDPR Regulation") 2. Add **Constraint** ("Data Residency: EU only") 3. Add **Requirement** ("Right to Deletion", "Data Portability") 4. Add **Principle** ("Privacy by Design") 5. Security layer references these elements ### Scenario 3: Architecture Decision Records (ADR) **Question:** "Document why we chose microservices?" **Approach:** 1. Add **Assessment** (strength/weakness of monolith) 2. Add **Principle** ("Microservices Architecture") 3. Add **Goal** ("Improve Deployment Frequency") 4. Add **Constraint** ("Team size supports distributed ownership") 5. Application layer references the Principle --- ## ArchiMate Integration When exporting to ArchiMate format: ```bash dr export archimate --layers motivation --output motivation.archimate ``` **Supported ArchiMate Elements:** - `Stakeholder` → ArchiMate Stakeholder - `Driver` → ArchiMate Driver - `Assessment` → ArchiMate Assessment - `Goal` → ArchiMate Goal - `Outcome` → ArchiMate Outcome - `Principle` → ArchiMate Principle - `Requirement` → ArchiMate Requirement - `Constraint` → ArchiMate Constraint - `Meaning` → ArchiMate Meaning - `Value` → ArchiMate Value **Supported Relationships:** - `aggregates`, `realizes`, `specializes`, `influences`, `associated-with` --- ## Best Practices 1. **Start with Stakeholders** - Understand WHO before WHAT 2. **Use SMART Goals** - Make goals Specific, Measurable, Achievable, Relevant, Time-bound 3. **Distinguish Requirements from Constraints**: - **Requirement**: "System MUST authenticate users" (functional need) - **Constraint**: "System MUST use OAuth 2.0" (limits HOW requirement is met) 4. **Link Principles to Requirements** - Every requirement should trace to a principle or goal 5. **Use Assessments for Trade-offs** - Document strengths/weaknesses to justify decisions 6. **Track Outcomes** - Update outcome status as goals are achieved 7. **Don't Over-Document** - Focus on high-value motivation elements that drive decisions --- ## Validation Tips Common validation issues: | Issue | Cause | Fix | | ---------------------- | --------------------------------------- | ----------------------------------------------- | | Orphaned Goal | No stakeholder influences it | Add stakeholder or driver that influences goal | | Unrealized Requirement | No goal justifies it | Link requirement to goal or principle | | Unused Principle | No requirements reference it | Either apply principle or remove it | | Missing Value | Goals don't realize any value | Add value elements and link goals | | No Traceability | Lower layers don't reference motivation | Add references from business/application layers | --- ## Quick Reference **Add Commands:** ```bash dr add motivation stakeholder --description dr add motivation driver --description dr add motivation goal --description dr add motivation requirement --description dr add motivation principle --description dr add motivation constraint --description ``` **Relationship Commands:** ```bash dr relationship add

--predicate influences dr relationship add

--predicate aggregates dr relationship add

--predicate realizes dr relationship add

--predicate specializes ``` **Query Commands:** ```bash dr list motivation --type goal dr search "" --layer motivation dr relationship list --direction outgoing ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/tinkermonkey) — claim your Tome and manage your conversions.