@documentation-robotics/cli 0.2.0 → 0.4.0

package/dist/integrations/github_copilot/skills/dr_01_motivation_layer/SKILL.md

@@ -14,13 +14,13 @@ triggers:
     "motivation",
     "archimate motivation"
   ]
-version: 0.8.1
+version: 0.8.3
 ---
 
 # Motivation Layer Skill
 
 **Layer Number:** 01
-**Specification:** Metadata Model Spec v0.8.1
+**Specification:** Metadata Model Spec v0.8.3
 **Purpose:** Captures stakeholder concerns, goals, requirements, and constraints that drive architectural decisions using ArchiMate motivation elements.
 
 ---
@@ -58,66 +58,137 @@ This layer uses **ArchiMate 3.2 Motivation Layer** standard without custom exten
 
 ---
 
-## Intra-Layer Relationships
+## 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
 
-### 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"       |
+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
 
 ---
 
-## Cross-Layer References
+## Intra-Layer Relationships
 
-**Motivation Layer is the highest layer** - It does **NOT reference any lower layers**. Instead, lower layers reference UP to this layer for governance.
+Note that the ArchiMate influence predicate is spelled `influence` (not `influences`).
+
+### Realization and Decomposition
+
+Requirements realize the outcomes, goals and principles they make concrete, and outcomes realize
+goals. Decomposition is same-type only: `aggregates` for parts, `specializes` for variants.
+
+| Source Type | Predicate   | Target Type | Example                                                             |
+| ----------- | ----------- | ----------- | ------------------------------------------------------------------- |
+| Requirement | realizes    | Goal        | "API must respond in <200ms" realizes "Improve Performance"         |
+| Requirement | realizes    | Outcome     | "99.99% availability" realizes "Downtime Under 1h per Quarter"      |
+| Requirement | realizes    | Principle   | "Orders API uses OAuth 2.0" realizes "Security by Design"           |
+| Outcome     | realizes    | Goal        | "Churn Reduced 10%" realizes "Improve Customer Satisfaction"        |
+| Goal        | aggregates  | Goal        | "Improve Customer Satisfaction" aggregates "Reduce Response Time"   |
+| Requirement | aggregates  | Requirement | "Secure User Data" requirement aggregates "Encrypt Data in Transit" |
+| Outcome     | aggregates  | Outcome     | "Global NPS 50" aggregates "EU NPS 50"                              |
+| Stakeholder | aggregates  | Stakeholder | "Finance" aggregates "Accounts Payable Team"                        |
+| Value       | aggregates  | Value       | "Lower Total Cost" aggregates "Lower Licence Cost"                  |
+| Goal        | specializes | Goal        | "Reduce API Latency" specializes "Improve Performance"              |
+| Requirement | specializes | Requirement | "99.95% Uptime SLA" specializes "High Availability Requirement"     |
+| Constraint  | specializes | Constraint  | "EU-only Data Residency" specializes "Data Residency Constraint"    |
+| Constraint  | constrains  | Requirement | "Must use OAuth 2.0" constrains "User Authentication"               |
+
+### Influence and Association Relationships
+
+`influence` is one motivation element shaping another. `associated-with` is kept for concerns
+(stakeholders, assessments evaluating drivers) and interpretation: meaning and value are associated
+with any concept and are always the source.
+
+| Source Type | Predicate       | Target Type | Example                                                               |
+| ----------- | --------------- | ----------- | --------------------------------------------------------------------- |
+| Stakeholder | influence       | Goal        | "CEO" influences "Reduce Operating Costs by 20%"                      |
+| Driver      | influence       | Goal        | "Digital Transformation" influences "Modernize Architecture"          |
+| Driver      | influence       | Requirement | "GDPR Regulation" influences "Right to Deletion"                      |
+| Driver      | influence       | Principle   | "Cloud-First Strategy" influences "Cloud-Native Architecture"         |
+| Driver      | influence       | Constraint  | "GDPR Regulation" influences "EU-only Data Residency"                 |
+| Assessment  | influence       | Goal        | "Legacy System Debt" influences "Modernize Architecture"              |
+| Assessment  | influence       | Requirement | "Slow Checkout Weakness" influences "Checkout must complete in <2s"   |
+| Assessment  | influence       | Outcome     | "Checkout p95 is 4s" influences "Checkout p95 Under 2s by Q3"         |
+| Goal        | influence       | Requirement | "Improve Security" influences "Enforce MFA for Admins"                |
+| Goal        | influence       | Principle   | "Modernize Architecture" influences "Cloud-Native Architecture"       |
+| Principle   | influence       | Requirement | "API-First Design" influences "Every Feature Exposes an API"          |
+| Constraint  | influence       | Goal        | "Fixed Q4 Budget" influences "Launch Mobile App by Q4"                |
+| Stakeholder | associated-with | Driver      | "Head of Compliance" associated with "GDPR Regulation"                |
+| Stakeholder | associated-with | Requirement | "End Users" associated with "Offline Mode Support"                    |
+| Assessment  | associated-with | Driver      | "GDPR Gap Analysis" associated with "GDPR Regulation"                 |
+| Value       | associated-with | Stakeholder | "Customer Loyalty" associated with "Customers"                        |
+| Value       | associated-with | Goal        | "Customer Loyalty" associated with "Improve Customer Satisfaction"    |
+| Value       | associated-with | Driver      | "Faster Time to Market" associated with "Market Competition"          |
+| Meaning     | associated-with | Value       | "Definition of Customer Success" associated with "Customer Loyalty"   |
+| Meaning     | associated-with | Requirement | "Definition of Session" associated with "Sessions Expire After 15min" |
 
-### 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-13**            | All layers can reference Principles, Constraints, Requirements, Goals for governance and traceability                             |
+## Cross-Layer References
 
-**Design Pattern:** Lower layers "look up" to the Motivation layer to justify WHY they exist and WHAT value they deliver.
+**Motivation Layer is the root of traceability.** The catalog defines no outgoing references from Motivation; elements in other layers point to motivation elements to justify WHY they exist and WHAT value they deliver.
+
+### Incoming References (Other Layers → Motivation)
+
+| Source Type                       | Predicate        | Target Type | Example                                                             |
+| --------------------------------- | ---------------- | ----------- | ------------------------------------------------------------------- |
+| `business.businessservice`        | realizes         | Goal        | "Online Ordering" realizes "Grow Digital Revenue"                   |
+| `business.businessservice`        | delivers         | Value       | "Same-Day Delivery" delivers "Customer Convenience"                 |
+| `business.businessprocess`        | satisfies        | Requirement | "Refund Processing" satisfies "Refunds Issued Within 5 Days"        |
+| `business.businessactor`          | references       | Stakeholder | "Customer" actor references "Customers" stakeholder                 |
+| `product.softwarecapability`      | supports         | Goal        | "Self-Service Returns" supports "Reduce Support Costs"              |
+| `product.feature`                 | satisfies        | Requirement | "Two-Factor Login" satisfies "Enforce MFA for Admins"               |
+| `product.persona`                 | references       | Stakeholder | "Busy Parent Persona" references "Retail Customers"                 |
+| `product.userworkflow`            | delivers         | Outcome     | "Checkout Flow" delivers "Cart Abandonment Reduced 15%"             |
+| `security.securitypolicy`         | satisfies        | Principle   | "Encryption Policy" satisfies "Security by Design"                  |
+| `security.countermeasure`         | satisfies        | Requirement | "Rate Limiting" satisfies "Prevent Credential Stuffing"             |
+| `application.applicationservice`  | realizes         | Goal        | "Recommendation Service" realizes "Increase Average Order Value"    |
+| `application.applicationfunction` | satisfies        | Requirement | "Audit Logging" satisfies "Log All Admin Actions"                   |
+| `technology.systemsoftware`       | satisfies        | Constraint  | "PostgreSQL 15" satisfies "Approved Open-Source Databases Only"     |
+| `api.operation`                   | satisfies        | Requirement | "POST /orders" satisfies "Orders Accepted via Public API"           |
+| `data-store.retentionpolicy`      | satisfies        | Constraint  | "Purge PII After 30 Days" satisfies "GDPR Data Minimization"        |
+| `apm.metricinstrument`            | measures-outcome | Outcome     | "checkout.duration" metric measures "Checkout Under 2s Outcome"     |
+| `testing.testcoveragemodel`       | satisfies        | Requirement | "Checkout Coverage Model" satisfies "Checkout must complete in <2s" |
 
 ---
 
@@ -203,6 +274,26 @@ TARGET_UPTIME_SLA = 0.9999
 
 ---
 
+## 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
@@ -212,15 +303,12 @@ Start by documenting **WHO cares** about the system:
 ```bash
 # Add key stakeholders
 dr add motivation stakeholder "End Users" \
-  --properties type=external \
   --description "Customers using the platform"
 
 dr add motivation stakeholder "Product Manager" \
-  --properties type=internal \
   --description "Defines product vision and priorities"
 
 dr add motivation stakeholder "Compliance Team" \
-  --properties type=internal \
   --description "Ensures regulatory compliance"
 ```
 
@@ -231,16 +319,13 @@ Identify **WHAT is pushing** the organization:
 ```bash
 # Market driver
 dr add motivation driver "Cloud Migration Pressure" \
-  --properties category=market \
   --description "Industry shift to cloud-native architectures"
 
 # SWOT assessment
 dr add motivation assessment "Legacy System Debt" \
-  --properties assessmentType=weakness \
   --description "Monolithic architecture limits agility"
 
 dr add motivation assessment "Strong Engineering Team" \
-  --properties assessmentType=strength \
   --description "Experienced team with cloud expertise"
 ```
 
@@ -251,12 +336,10 @@ Articulate **WHAT we want to achieve**:
 ```bash
 # Strategic goal
 dr add motivation goal "Modernize Architecture" \
-  --properties priority=critical,measurable=true,target-date=2024-12-31 \
   --description "Migrate to microservices architecture"
 
 # Value delivered
 dr add motivation value "Operational Efficiency" \
-  --properties type=operational \
   --description "Reduced deployment time and increased reliability"
 ```
 
@@ -267,17 +350,14 @@ Define **HOW we will operate**:
 ```bash
 # Functional requirement
 dr add motivation requirement "API Authentication" \
-  --properties type=functional \
   --description "All API endpoints must authenticate users"
 
 # Guiding principle
 dr add motivation principle "API-First Design" \
-  --properties category=application \
   --description "All services expose RESTful APIs with OpenAPI specs"
 
 # Hard constraint
 dr add motivation constraint "AWS-Only Infrastructure" \
-  --properties type=technology \
   --description "All services must deploy to AWS (no multi-cloud)"
 ```
 
@@ -287,31 +367,31 @@ Connect motivation elements using predicates:
 
 ```bash
 # Driver influences Goal
-dr relationship add "motivation/driver/cloud-migration-pressure" \
-  influences "motivation/goal/modernize-architecture"
+dr relationship add motivation.driver.cloud-migration-pressure \
+  motivation.goal.modernize-architecture --predicate influence
 
-# Goal realizes Value
-dr relationship add "motivation/goal/modernize-architecture" \
-  realizes "motivation/value/operational-efficiency"
+# Value associated with Goal (meaning and value are the source)
+dr relationship add motivation.value.operational-efficiency \
+  motivation.goal.modernize-architecture --predicate associated-with
 
 # Principle influences Requirement
-dr relationship add "motivation/principle/api-first-design" \
-  influences "motivation/requirement/api-authentication"
+dr relationship add motivation.principle.api-first-design \
+  motivation.requirement.api-authentication --predicate influence
 
 # Stakeholder influences Goal
-dr relationship add "motivation/stakeholder/product-manager" \
-  influences "motivation/goal/modernize-architecture"
+dr relationship add motivation.stakeholder.product-manager \
+  motivation.goal.modernize-architecture --predicate influence
 
 # Assessment influences Goal
-dr relationship add "motivation/assessment/legacy-system-debt" \
-  influences "motivation/goal/modernize-architecture"
+dr relationship add motivation.assessment.legacy-system-debt \
+  motivation.goal.modernize-architecture --predicate influence
 ```
 
 ### Step 6: Validate
 
 ```bash
-dr validate --layer motivation
-dr validate --validate-relationships
+dr validate --layers motivation
+dr validate --relationships
 ```
 
 ---
@@ -335,30 +415,29 @@ Strategic Goal: "Improve Customer Satisfaction"
 ```
 Business Requirement: "Secure User Data"
 ├── aggregates → Functional Requirement: "Encrypt Data at Rest"
-│   └── influences → Technical Requirement: "Use AES-256 Encryption"
+│   └── aggregates → Technical Requirement: "Use AES-256 Encryption"
 ├── aggregates → Functional Requirement: "Encrypt Data in Transit"
-│   └── influences → Technical Requirement: "Use TLS 1.3"
+│   └── aggregates → Technical Requirement: "Use TLS 1.3"
 └── aggregates → Compliance Requirement: "GDPR Data Protection"
-    └── influences → Technical Requirement: "Right to Deletion API"
+    └── aggregates → 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"
+├── influence → Requirement: "Containerized Deployments"
+├── influence → Requirement: "Stateless Services"
+└── associated-with → 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"
+└── influence → Goal: "Reduce Operating Costs by 20%"
+    ├── influence → Requirement: "Automated CI/CD Pipeline"
+    ├── influence → Principle: "Infrastructure as Code"
     └── realizes → Value: "Financial Efficiency"
         └── (lower layers reference this chain)
 ```
@@ -410,7 +489,7 @@ Stakeholder: "CEO"
 When exporting to ArchiMate format:
 
 ```bash
-dr export archimate --layer motivation --output motivation.archimate
+dr export archimate --layers motivation --output motivation.archimate
 ```
 
 **Supported ArchiMate Elements:**
@@ -428,7 +507,7 @@ dr export archimate --layer motivation --output motivation.archimate
 
 **Supported Relationships:**
 
-- `aggregates`, `realizes`, `specializes`, `influences`, `associated-with`
+- `aggregates`, `realizes`, `specializes`, `influence`, `associated-with`
 
 ---
 
@@ -465,27 +544,28 @@ Common validation issues:
 **Add Commands:**
 
 ```bash
-dr add motivation stakeholder <name> --properties type=<type>
-dr add motivation driver <name> --properties category=<category>
-dr add motivation goal <name> --properties priority=<priority>
-dr add motivation requirement <name> --properties type=<type>
-dr add motivation principle <name> --properties category=<category>
-dr add motivation constraint <name> --properties type=<type>
+dr add motivation stakeholder <name> --description <description>
+dr add motivation driver <name> --description <description>
+dr add motivation goal <name> --description <description>
+dr add motivation requirement <name> --description <description>
+dr add motivation principle <name> --description <description>
+dr add motivation constraint <name> --description <description>
 ```
 
 **Relationship Commands:**
 
 ```bash
-dr relationship add <source-id> influences <target-id>
-dr relationship add <source-id> aggregates <target-id>
-dr relationship add <source-id> realizes <target-id>
-dr relationship add <source-id> specializes <target-id>
+dr relationship add <source-id> <target-id> --predicate influence
+dr relationship add <source-id> <target-id> --predicate aggregates
+dr relationship add <source-id> <target-id> --predicate realizes
+dr relationship add <source-id> <target-id> --predicate specializes
+dr relationship add <source-id> <target-id> --predicate associated-with
 ```
 
 **Query Commands:**
 
 ```bash
-dr search --layer motivation --type goal
-dr search --layer motivation --property priority=critical
+dr list motivation --type goal
+dr search "" --layer motivation
 dr relationship list <element-id> --direction outgoing
 ```