Interactions

An Interaction represents a task or action that helps a user reach their goal. It's the "how": the concrete work that delivers user value.

What Makes a Good Interaction?

Interactions describe user-facing actions or behind-the-scenes work that supports user goals:

# User-facing interaction
et create interaction \
  --id "add_to_cart" \
  --description "Add products to shopping cart for later purchase" \
  --performed-by "customer" \
  --goal "complete_purchase"

# Behind-the-scenes interaction (still tied to user goal)
et create interaction \
  --id "process_payment" \
  --description "Securely process payment and verify transaction" \
  --performed-by "customer" \
  --goal "complete_purchase"

Interaction Fields

Field	Required	Description
id	Yes	Unique identifier
description	Yes	What the interaction accomplishes
performed_by	No	The actor performing this action
goals	No*	The goals this interaction supports (can be multiple)
tags	No	Labels for filtering and organisation
meta	No	Custom key-value metadata

*While optional, interactions without goals will be flagged by validation.

Creating Interactions

et create interaction \
  --id "submit_support_ticket" \
  --description "Submit a support request describing the issue" \
  --performed-by "customer" \
  --goal "get_issue_resolved"

Multi-Goal Interactions

Some interactions support multiple user goals. Use --goals to link an interaction to multiple goals:

# Single goal (traditional approach)
et create interaction \
  --id "export_data" \
  --description "Export customer data" \
  --performed-by "admin" \
  --goal "export_data"

# Multiple goals (when one interaction serves multiple purposes)
et create interaction \
  --id "export_data" \
  --description "Export customer data in standard format" \
  --performed-by "admin" \
  --goals "export_data,backup_data,analytics_prep"

This is useful when a single action contributes to multiple user outcomes.

Tags and Metadata

Tags help track verification status, source systems, and implementation priority for interactions.

Tracking Discovery and Verification

# Create interaction discovered during legacy system exploration
et create interaction \
  --id "export_csv" \
  --description "Export data as CSV file" \
  --performed-by "admin" \
  --goal "export_reports" \
  --tags "legacy,unverified" \
  --meta "discovered_in=admin_panel"

# Mark as verified after testing
et update interaction export_csv --add-tags "verified" --remove-tags "unverified"

Tracking Implementation Status

# Tag interactions by source system
et create interaction \
  --id "bulk_upload" \
  --description "Upload multiple records via file" \
  --performed-by "admin" \
  --goal "batch_import" \
  --tags "legacy-only" \
  --meta "source=legacy_app" \
  --meta "priority=high"

# Update when implemented in new system
et update interaction bulk_upload --tags "both" --meta "source=legacy_app,new_app"

Finding Work with Tags

# Find unverified interactions for a goal
et list interactions --goal export_reports --tag unverified

# Find all legacy-only interactions (gap analysis)
et list interactions --tag legacy-only

# Find high priority items using metadata (via JSON output)
et list interactions --format json | jq '.[] | select(.meta.priority == "high")'

Listing Interactions

# All interactions
et list interactions

# Interactions supporting a specific goal
et list interactions --goal complete_purchase

# JSON format
et list interactions --format json

Viewing Interaction Details

et show interaction add_to_cart

Updating Interactions

et update interaction add_to_cart \
  --description "Add products to cart with quantity selection"

Removing Interactions

# Will warn if referenced by journeys
et remove interaction old_interaction

# Force removal
et remove interaction old_interaction --force

Connecting Technical Work to User Goals

Every piece of technical work should be an interaction tied to a user goal:

Example: API Development

# User goal
et create goal \
  --id "track_order" \
  --description "Know where my order is and when it will arrive" \
  --actor "customer"

# Technical work as interaction
et create interaction \
  --id "order_tracking_api" \
  --description "Real-time order status and delivery tracking" \
  --performed-by "customer" \
  --goal "track_order"

Example: Performance Work

# User goal
et create goal \
  --id "responsive_search" \
  --description "Find products instantly without waiting" \
  --actor "customer"

# Technical work as interaction
et create interaction \
  --id "search_optimization" \
  --description "Optimized search with instant results" \
  --performed-by "customer" \
  --goal "responsive_search"

Validation

Interactions without goals are flagged:

et validate

Warnings:
  ! [interaction/orphan_task] Interaction is not linked to any goal

Best Practices

1. Always link to a goal: If you can't find a goal, create one or question the work
2. Describe the user value: Not just what happens, but why it matters
3. Use active voice: "Process payment" not "Payment is processed"
4. Keep granularity consistent: Don't mix high-level and detailed interactions

Next Steps

• Journeys: Sequence interactions into complete flows
• Breaking Down Work: How to approach new tasks