world-model-workflow

name	world-model-workflow
description	Build a rigorous world model with state, dynamics, uncertainty, and provenance. Use when creating digital twins, constructing system representations, building simulation foundations, or establishing baseline world state.
argument-hint	[goal] [scope] [constraints]
disable-model-invocation	false
user-invocable	true
allowed-tools	Read, Grep, Bash, Edit, Git, Web
context	fork
agent	general-purpose

Intent

Run the composed workflow world-model-workflow using atomic capability skills to construct a comprehensive, grounded representation of a system or domain.

A world model captures:

• State: Current entity states and attributes
• Dynamics: How the system evolves over time
• Uncertainty: Confidence bounds and unknowns
• Provenance: Source and lineage of all facts

Success criteria:

• Complete entity inventory with identity resolution
• State representation follows canonical schema
• Causal relationships and dynamics modeled
• Uncertainty quantified for all assertions
• Full provenance chain for every fact
• Simulation capability established

Compatible schemas:

• reference/world_state_schema.yaml
• reference/event_schema.yaml

Inputs

Parameter	Required	Type	Description
goal	Yes	string	The modeling objective (e.g., "model supply chain for disruption analysis")
scope	Yes	string|array	Domain, system, or entities to model
constraints	No	object	Limits (e.g., time horizon, resolution, confidence threshold)
sources	No	array	Data sources for world state extraction
prior_model	No	object	Existing model to extend or refine

Procedure

0. Create checkpoint marker if mutation might occur:

   • Create .claude/checkpoint.ok after confirming rollback strategy

1. Invoke /retrieve and store output as retrieve_out

   • Gather raw data from configured sources

2. Invoke /inspect and store output as inspect_out

   • Examine retrieved data for structure and quality

3. Invoke /identity-resolution and store output as identity-resolution_out

   • Resolve entity references and establish canonical IDs

4. Invoke /world-state and store output as world-state_out

   • Construct canonical state representation

5. Invoke /state-transition and store output as state-transition_out

   • Define rules for state evolution

6. Invoke /causal-model and store output as causal-model_out

   • Map cause-effect relationships

7. Invoke /uncertainty-model and store output as uncertainty-model_out

   • Quantify confidence and unknowns

8. Invoke /provenance and store output as provenance_out

   • Document source and lineage of all facts

9. Invoke /grounding and store output as grounding_out

   • Attach evidence anchors to assertions

10. Invoke /simulation and store output as simulation_out

    • Validate model through simulation runs

11. Invoke /summarize and store output as summarize_out

    • Generate human-readable model summary

Output Contract

Return a structured object:

workflow_id: string  # Unique model construction ID
goal: string  # Modeling objective
status: completed | partial | failed
world_model:
  version: string
  created_at: string  # ISO timestamp
  schema_version: string
  entities:
    count: integer
    by_type: object  # type -> count
    sample: array[object]  # representative entities
  relationships:
    count: integer
    types: array[string]
    sample: array[object]
  evidence_anchors: array[string]
state:
  snapshot: object  # Canonical world state
  hash: string  # Integrity hash
  timestamp: string
  evidence_anchors: array[string]
dynamics:
  transition_rules: integer
  causal_links: integer
  temporal_scope: string  # e.g., "real-time", "daily", "event-driven"
  evidence_anchors: array[string]
uncertainty:
  overall_confidence: number  # 0.0-1.0
  high_uncertainty_areas: array[string]
  unknown_factors: array[string]
  evidence_anchors: array[string]
provenance:
  sources: array[string]
  lineage_depth: integer
  coverage: number  # 0.0-1.0 (% of facts with provenance)
  evidence_anchors: array[string]
simulation:
  validated: boolean
  scenarios_tested: integer
  anomalies_found: array[string]
  evidence_anchors: array[string]
summary:
  description: string
  key_insights: array[string]
  recommended_actions: array[string]
  evidence_anchors: array[string]
confidence: number  # 0.0-1.0
evidence_anchors: array[string]
assumptions: array[string]

Field Definitions

Field	Type	Description
workflow_id	string	Unique identifier for this model construction
world_model	object	Metadata about entities and relationships
state	object	Canonical world state snapshot with integrity hash
dynamics	object	Transition rules and causal structure
uncertainty	object	Confidence levels and unknown factors
provenance	object	Source tracking and lineage
simulation	object	Model validation results
summary	object	Human-readable insights
confidence	number	0.0-1.0 based on evidence completeness
evidence_anchors	array	All evidence references collected
assumptions	array	Explicit assumptions made during modeling

Examples

Example 1: Build Supply Chain World Model

Input:

goal: "Model electronics supply chain for disruption risk analysis"
scope:
  - "suppliers"
  - "manufacturers"
  - "logistics"
  - "inventory"
constraints:
  time_horizon: "6 months"
  geographic_scope: "Asia-Pacific"
  confidence_threshold: 0.7
sources:
  - type: database
    connection: "postgres://supply-chain-db"
  - type: api
    endpoint: "https://logistics.api/shipments"

Output:

workflow_id: "world_20240115_100000_supplychain"
goal: "Model electronics supply chain for disruption risk analysis"
status: completed
world_model:
  version: "v1.0.0"
  created_at: "2024-01-15T10:00:00Z"
  schema_version: "world_state_schema_v2"
  entities:
    count: 1247
    by_type:
      supplier: 156
      manufacturer: 23
      warehouse: 45
      distribution_center: 12
      product: 892
      shipment: 119
    sample:
      - id: "supplier-taiwan-001"
        type: "supplier"
        name: "Taiwan Semiconductor Co"
        location: "Hsinchu, Taiwan"
        capacity: 50000
        lead_time_days: 45
      - id: "mfg-shenzhen-005"
        type: "manufacturer"
        name: "Shenzhen Electronics Assembly"
        location: "Shenzhen, China"
        capacity: 100000
  relationships:
    count: 3456
    types:
      - "supplies_to"
      - "located_in"
      - "transports_via"
      - "stores_at"
      - "depends_on"
    sample:
      - subject: "supplier-taiwan-001"
        predicate: "supplies_to"
        object: "mfg-shenzhen-005"
        attributes:
          volume: 25000
          frequency: "weekly"
  evidence_anchors:
    - "tool:database:supply-chain-db/entities"
    - "tool:api:logistics.api/shipments"
state:
  snapshot:
    timestamp: "2024-01-15T10:00:00Z"
    entities: "[1247 entities - see world_state.yaml]"
    relationships: "[3456 relationships - see world_state.yaml]"
  hash: "sha256:def456abc789..."
  timestamp: "2024-01-15T10:00:00Z"
  evidence_anchors:
    - "file:state/supply_chain_world.yaml"
dynamics:
  transition_rules: 34
  causal_links: 89
  temporal_scope: "daily"
  evidence_anchors:
    - "tool:state-transition:rule_extraction"
    - "tool:causal-model:dependency_graph"
uncertainty:
  overall_confidence: 0.82
  high_uncertainty_areas:
    - "Supplier capacity utilization (estimated from public data)"
    - "Shipping delays (historical average, not real-time)"
  unknown_factors:
    - "Competitor orders affecting supplier allocation"
    - "Regulatory changes in transit countries"
  evidence_anchors:
    - "tool:uncertainty-model:confidence_analysis"
provenance:
  sources:
    - "postgres://supply-chain-db (primary)"
    - "https://logistics.api (secondary)"
    - "public filings (supplementary)"
  lineage_depth: 3
  coverage: 0.94
  evidence_anchors:
    - "tool:provenance:lineage_trace"
simulation:
  validated: true
  scenarios_tested: 5
  anomalies_found:
    - "Taiwan supplier shutdown causes 67% production halt within 2 weeks"
    - "Shipping route disruption adds 12-day average delay"
  evidence_anchors:
    - "tool:simulation:scenario_results"
summary:
  description: "Electronics supply chain model covering 156 suppliers, 23 manufacturers, and supporting logistics infrastructure in Asia-Pacific region"
  key_insights:
    - "Single-source dependency on Taiwan for 45% of semiconductor supply"
    - "Shenzhen manufacturing hub handles 60% of assembly volume"
    - "Average supply chain depth of 3 tiers with limited visibility beyond tier 1"
  recommended_actions:
    - "Diversify semiconductor sourcing to reduce Taiwan concentration risk"
    - "Establish buffer inventory for critical components"
    - "Develop secondary logistics routes for key shipping lanes"
  evidence_anchors:
    - "tool:summarize:executive_summary"
confidence: 0.82
evidence_anchors:
  - "tool:database:supply-chain-db"
  - "tool:api:logistics.api"
  - "tool:simulation:scenario_results"
  - "file:state/supply_chain_world.yaml"
assumptions:
  - "Database reflects current operational state"
  - "API provides accurate shipment tracking"
  - "Public capacity data is within 20% of actual"
  - "Lead times based on historical 90-day average"

Evidence pattern: Multi-source data integration, entity resolution across databases, causal analysis from transaction patterns, uncertainty from data freshness and coverage.

Verification

• Entity Coverage: All entities in scope identified with canonical IDs
• Relationship Completeness: Key relationships mapped with evidence
• State Validity: World state conforms to schema
• Dynamics Defined: Transition rules and causal links documented
• Uncertainty Quantified: Confidence scores for all major assertions
• Provenance Complete: Source documented for >90% of facts
• Simulation Validated: At least 1 scenario successfully executed

Verification tools: Read (for state files), Bash (for simulation), Web (for API validation)

Safety Constraints

• mutation: false
• requires_checkpoint: false
• requires_approval: false
• risk: medium

Capability-specific rules:

• Do not modify source data during modeling
• Flag entities with confidence < threshold
• Document all assumptions explicitly
• Preserve raw data alongside derived state
• Validate schema conformance before completion
• Rate-limit API calls to respect source limits

Composition Patterns

Commonly follows:

• retrieve - After gathering raw data
• receive - After ingesting real-time signals
• inspect - After initial data quality assessment

Commonly precedes:

• digital-twin-sync-workflow - World model is prerequisite for sync
• simulate - To run what-if scenarios
• forecast-risk - To predict future states
• summarize - To generate executive reports

Anti-patterns:

• Never skip identity resolution before state construction
• Never omit uncertainty modeling for production use
• Never finalize without provenance documentation
• Never deploy model without simulation validation

Workflow references:

• See reference/workflow_catalog.yaml#world-model-workflow for step definitions
• See reference/world_state_schema.yaml for canonical state format