attribute

Intent

Establish causal relationships between observed effects and potential causes. This capability supports root cause analysis, dependency mapping, and causal reasoning for planning and debugging.

Success criteria:

• Causes identified for observed effects
• Causal strength estimated for each relationship
• Causal mechanism explained
• Alternative causes considered and ruled out

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Parameter	Required	Type	Description
effect	Yes	any	The observed effect to attribute
candidates	No	array	Potential causes to evaluate
context	No	object	Situational context for attribution
depth	No	string	Analysis depth: immediate, chain, comprehensive

Procedure

1. Characterize the effect: Understand what needs to be explained

   • Document the observed effect precisely
   • Note timing and circumstances
   • Identify what changed

2. Identify candidate causes: Generate list of potential causes

   • Use provided candidates if available
   • Generate additional candidates from context
   • Consider proximate and distal causes

3. Evaluate causal strength: Assess each candidate

   • Check temporal precedence (cause before effect)
   • Verify mechanism plausibility
   • Look for correlation evidence
   • Consider counterfactual (would effect occur without cause?)

4. Trace causal chain: Map the path from cause to effect

   • Identify intermediate steps
   • Note amplifying or dampening factors
   • Document the causal mechanism

5. Rule out alternatives: Eliminate unlikely causes

   • Document why alternatives are less likely
   • Note any confounding factors
   • Flag when multiple causes may contribute

6. Quantify confidence: Assess attribution certainty

   • Rate strength of causal evidence
   • Note missing evidence
   • Identify what would confirm/refute attribution

Output Contract

Return a structured object:

causes:
  - cause: string  # Identified cause
    strength: number  # 0.0-1.0 causal strength
    mechanism: string  # How cause produces effect
    evidence: array[string]  # Supporting evidence
    type: string  # direct, contributing, enabling
strengths:  # Comparative strengths
  cause_1: number
  cause_2: number
causal_chain:
  - step: string  # Intermediate step
    from: string  # Prior state/event
    to: string  # Resulting state/event
alternatives_ruled_out:
  - cause: string
    reason: string  # Why ruled out
confidence: 0..1
evidence_anchors: ["file:line", "log:entry"]
assumptions: []

Field Definitions

Field	Type	Description
causes	array	Identified causes with strength and mechanism
causes[].strength	number	Causal strength (0-1)
causes[].mechanism	string	Explanation of causal pathway
causes[].type	string	Direct, contributing, or enabling cause
causal_chain	array	Steps from cause to effect
alternatives_ruled_out	array	Rejected alternatives with reasons

Examples

Example 1: Attribute Performance Degradation

Input:

effect: "API response time increased from 200ms to 2000ms"
candidates:
  - "recent deployment"
  - "database load increase"
  - "memory leak"
context:
  timing: "started 2024-01-15 14:30"
  affected: "/api/users endpoint"

Output:

causes:
  - cause: "N+1 query introduced in recent deployment"
    strength: 0.85
    mechanism: "New eager loading removed; each user now triggers 3 additional queries"
    evidence:
      - "Deployment at 14:25, issue started 14:30"
      - "Query count per request increased from 2 to 50+"
      - "Database CPU correlates with API latency"
    type: "direct"
  - cause: "Database connection pool saturation"
    strength: 0.40
    mechanism: "Increased queries exhaust connection pool, causing wait times"
    evidence:
      - "Pool utilization at 95%"
      - "Connection wait time increased"
    type: "contributing"
strengths:
  n_plus_1_query: 0.85
  connection_pool: 0.40
  memory_leak: 0.05
causal_chain:
  - step: "Code deployed"
    from: "eager_load(:profile)"
    to: "no eager loading"
  - step: "Query multiplication"
    from: "2 queries/request"
    to: "50+ queries/request"
  - step: "Database overload"
    from: "normal CPU"
    to: "90% CPU"
  - step: "Response delay"
    from: "200ms"
    to: "2000ms"
alternatives_ruled_out:
  - cause: "memory leak"
    reason: "Memory usage stable, no growth pattern"
  - cause: "external service latency"
    reason: "No external calls in affected endpoint"
confidence: 0.85
evidence_anchors:
  - "git log --since='2024-01-15 14:00'"
  - "app/models/user.rb:45 (diff)"
  - "monitoring:query_count"
  - "monitoring:db_cpu"
assumptions:
  - "Monitoring data is accurate"
  - "No other deployments in window"

Example 2: Attribute Test Failure

Input:

effect: "UserService#create test failing with 'Email already taken'"
candidates:
  - "test data pollution"
  - "code change"
  - "database state"

Output:

causes:
  - cause: "Missing database cleanup between tests"
    strength: 0.90
    mechanism: "Test creates user, doesn't clean up, subsequent test finds duplicate"
    evidence:
      - "Test passes in isolation"
      - "Test fails when run after create_user_test"
      - "No database_cleaner configuration"
    type: "direct"
strengths:
  test_pollution: 0.90
  code_change: 0.05
  fixture_issue: 0.05
causal_chain:
  - step: "First test runs"
    from: "empty database"
    to: "user 'test@example.com' exists"
  - step: "Second test attempts create"
    from: "user exists"
    to: "uniqueness validation fails"
alternatives_ruled_out:
  - cause: "code change"
    reason: "No recent changes to UserService"
  - cause: "fixture issue"
    reason: "Test doesn't use fixtures"
confidence: 0.90
evidence_anchors:
  - "spec/services/user_service_spec.rb:45"
  - "spec/rails_helper.rb (no database_cleaner)"
  - "command:rspec spec/services/user_service_spec.rb:45 --order defined"
assumptions:
  - "Test failure is deterministic with this order"
  - "No parallel test execution"

Verification

• At least one cause identified with strength > 0.3
• Mechanism explains how cause produces effect
• Temporal precedence verified (cause before effect)
• Alternative causes considered
• Evidence supports attribution

Verification tools: Read, Grep (to verify evidence)

Safety Constraints

• mutation: false
• requires_checkpoint: false
• requires_approval: false
• risk: low

Capability-specific rules:

• Distinguish correlation from causation
• Consider multiple causes (multi-causality)
• Note when attribution is uncertain
• Do not assume causation without mechanism

Composition Patterns

Commonly follows:

• detect - Detect anomalies then attribute causes
• observe - Observations reveal effects to attribute
• measure - Measurements quantify effects

Commonly precedes:

• plan - Causal understanding informs remediation
• explain - Attribution enables explanation
• critique - Causal model enables critique

Anti-patterns:

• Never use attribute for prediction (use predict)
• Avoid attribution without sufficient evidence

Workflow references:

• See reference/workflow_catalog.yaml#debug_code_change for attribution in debugging
• See reference/workflow_catalog.yaml#world_model_build for causal modeling