Home > Tasks > Reasoning > CounterfactualAnalysisTask

CounterfactualAnalysisTask

Explore "what-if" scenarios to understand causal relationships and decision impacts through structured comparative analysis.

Category: Reasoning Side-Effect Safe GPT-4 Preferred

⚙️ TaskConfig.json

{
  "actual_scenario": "Project deadline missed by 2 weeks.",
  "counterfactuals": [
    "What if we hired a senior dev in month 2?",
    "What if we cut the reporting module scope?"
  ],
  "compare_outcomes": true,
  "control_factors": ["Budget", "Tech Stack"]
}

→

👁️ Session UI

Overview

Actual Scenario

Counterfactuals

Comparison

Comparative Analysis

Key Differences: Hiring a senior developer would have likely mitigated the integration delays seen in month 4...

> Impact Assessment: High
> Primary Driver: Resource Bottleneck

Live Results Showcase

Explore actual analysis reports and transcripts generated by this task in the test workspace.

Execution Configuration

Field	Type	Description
`actual_scenario`*	String	The actual scenario or decision to analyze.
`counterfactuals`*	List<String>	Alternative conditions to explore (what-if scenarios).
`compare_outcomes`	Boolean	Whether to compare outcomes across scenarios. Default: `true`.
`control_factors`	List<String>	Factors to hold constant across scenarios for controlled comparison.
`related_files`	List<String>	Additional files for context (historical data, related analyses).
`input_files`	List<String>	Specific files or glob patterns (e.g. `*/.kt`) used as input.
`task_description`	String	Detailed description of the analysis objectives.
`task_dependencies`	List<String>	List of task IDs that must complete before this analysis.

Task Lifecycle

1. Initialization & Validation

The task validates that actual_scenario is present and at least one counterfactual is provided. It then initializes a TabbedDisplay in the Session UI to organize the multi-stage analysis.

2. Scenario Analysis

The task performs a deep dive into the Actual Scenario first, establishing a baseline. It then iterates through each Counterfactual, analyzing outcomes based on the provided context, related files, and control factors.

3. Comparative Synthesis

If compare_outcomes is enabled, a final pass compares all scenarios to identify causal relationships, risks, and benefits of alternative choices relative to the baseline.

4. Completion

Generates a comprehensive Markdown report (analysis_results.md) and updates the Session UI with a tabbed view of the findings. The transcript records all prompts and LLM responses for full transparency.

Embedded Execution (UnifiedHarness)

Invoke this task programmatically using the UnifiedHarness for automated CI/CD or agentic workflows.

EmbeddedExample.kt

val harness = UnifiedHarness(serverless = true)
harness.start()

val config = CounterfactualAnalysisTask.CounterfactualAnalysisTaskExecutionConfigData(
    actual_scenario = "The system migration failed due to database timeout.",
    counterfactuals = listOf(
        "What if we had increased the connection pool size?",
        "What if we performed the migration in smaller batches?"
    ),
    compare_outcomes = true,
    control_factors = listOf("Hardware Specs", "Network Latency")
)

harness.runTask(
    taskType = CounterfactualAnalysisTask.CounterfactualAnalysis,
    executionConfig = config,
    workspace = File("./migration-analysis"),
    autoFix = true
)

Direct Task Instantiation

OrchestrationConfig.kt

val task = CounterfactualAnalysisTask(
    orchestrationConfig = config,
    planTask = CounterfactualAnalysisTask.CounterfactualAnalysisTaskExecutionConfigData(
        actual_scenario = "Current marketing strategy focus on SEO",
        counterfactuals = listOf(
            "Focus on influencer partnerships",
            "Increase spend on paid search"
        ),
        compare_outcomes = true
    )
)

Prompt Segment

The following instructions are injected into the LLM context:

CounterfactualAnalysis - Explore "what-if" scenarios to understand causal relationships and decision impacts
  ** Specify the actual scenario or decision that occurred
  ** Provide a list of alternative conditions to explore (counterfactuals)
  ** Optionally specify factors to hold constant across scenarios for controlled comparison
  ** Enable outcome comparison to see differences between scenarios
  ** Useful for:
     - Risk analysis and mitigation planning
     - Decision validation and retrospective analysis
     - Understanding causal relationships
     - Exploring alternative strategies
     - Impact assessment of different choices
  ** Related files can include historical data, previous analyses, or context documents
  ** Output includes detailed analysis of each scenario and comparative insights