Sankofa/docs/fairness-audit/USER_MESSAGES.md

# User-Facing Messages for Fairness Orchestration

## Overview

This document defines all user-facing messages shown in the fairness orchestration UI. Messages are designed to be clear, actionable, and avoid exposing internal math.

## Success Messages

### Feasible Configuration (No Warnings)

```
This fairness audit will process approximately {inputLoad} input units and generate {outputLoad} output units, taking approximately {estimatedTime} to complete.
```

**Example**:
> "This fairness audit will process approximately 100 input units and generate 5.0 output units, taking approximately 18 seconds to complete."

### Feasible with Warnings

```
This audit is feasible but has some considerations: {warnings}. Estimated time: {estimatedTime}.
```

**Example**:
> "This audit is feasible but has some considerations: Estimated processing time (2.5 hours) is close to timeline limit (3 hours). Estimated time: 2.5 hours."

## Warning Messages

### Output Complexity Warning

```
Output complexity ({outputLoad} units) is significantly higher than recommended ({targetOutputLoad} units)
```

**Suggestion**:
> "Consider reducing the number of outputs or simplifying output requirements"

### Timeline Exceeded Warning

```
Estimated processing time ({estimatedTime}) exceeds requested timeline ({requestedTime})
```

**Suggestion**:
> "Consider extending timeline to {suggestedTime} or reducing outputs"

### Timeline Close Warning

```
Estimated processing time ({estimatedTime}) is close to timeline limit ({requestedTime})
```

**Suggestion**:
> "Consider adding buffer time or reducing outputs for safety"

### Total Load Warning

```
Total process load ({totalLoad} units) is higher than expected ({expectedLoad} units)
```

## Info Messages

### How It Works (Info Box)

```
We design from the end result backwards. First we list every output you want (reports, files, metrics), then we calculate how much input validation and enrichment is needed — roughly 2× your input effort — and size the total job at about 3.2× the input.

You only choose: (1) What goes in, (2) What comes out, (3) When it needs to be ready.
The orchestration engine does everything in between.
```

### Output Selection Help

```
Select the outputs you want to generate. Each output has a weight that represents the processing effort required. The total output load is the sum of all selected output weights.
```

### Input Specification Help

```
Specify your input data. The engine calculates input complexity based on dataset size, number of sensitive attributes, date range, and filters. Input processing requires two passes: ingestion/enrichment and fairness evaluation.
```

### Timeline Help

```
Set when you need results. The engine validates that your requested timeline is feasible given the input and output complexity. You can run now, schedule for later, or set up continuous monitoring.
```

## Error Messages

### No Outputs Selected

```
Please select at least one output to generate.
```

### No Dataset Specified

```
Please specify a dataset to analyze.
```

### Invalid SLA Format

```
Invalid timeline format. Please use formats like "2 hours", "1 day", or "30 minutes".
```

### Infeasible Configuration

```
This audit configuration may not be feasible within the requested timeline. {warnings}. Estimated time: {estimatedTime}.
```

## Button States

### Run Button (Enabled)

```
Run Fairness Audit
```

### Run Button (Disabled - No Outputs)

```
Select outputs to continue
```

### Run Button (Disabled - No Dataset)

```
Specify dataset to continue
```

### Run Button (Disabled - Infeasible)

```
Adjust Configuration
```

## Real-Time Feedback

### Output Load Display

```
Total Output Load: {outputLoad} units
```

### Input Load Display

```
Estimated Input Load: {inputLoad} units
```

### Timeline Display

```
Estimated Time: {estimatedTime}
Total Process Load: {totalLoad} units
```

## Orchestration Analysis Display

### Load Breakdown

```
Input Load: {inputLoad}
× 2 = {inputPasses} (passes)

Output Load: {outputLoad}

Total Load: {totalLoad}
≈ {inputLoad} × 3.2 = {expectedTotal}
```

### Feasibility Status

**Feasible**:
```
✅ This configuration is feasible and ready to run.
```

**Feasible with Warnings**:
```
⚠️ This configuration is feasible but has some considerations.
```

**Not Feasible**:
```
❌ This configuration may not be feasible within the requested timeline.
```

## Suggestions Format

### Reducing Outputs

```
Consider reducing the number of outputs or simplifying output requirements
```

### Extending Timeline

```
Consider extending timeline to {suggestedTime} or reducing outputs
```

### Adding Buffer

```
Consider adding buffer time or reducing outputs for safety
```

## Time Formatting

### Seconds
```
{seconds} seconds
```

### Minutes
```
{minutes} minutes
```

### Hours
```
{hours} hours
```

### Days
```
{days} days
```

## Examples

### Example 1: Simple Request

**Input**: Small dataset (100 units)
**Outputs**: Metrics Export (1.0)
**Timeline**: 2 hours

**Message**:
> "This fairness audit will process approximately 100 input units and generate 1.0 output units, taking approximately 18 seconds to complete."

### Example 2: Complex Request

**Input**: Large dataset (500 units)
**Outputs**: All 8 outputs (13.0 units)
**Timeline**: 1 hour

**Message**:
> "This audit configuration may not be feasible within the requested timeline. Estimated processing time (88 seconds) exceeds requested timeline (1 hour). Estimated time: 88 seconds."

**Suggestion**:
> "Consider extending timeline to 2 minutes or reducing outputs"

### Example 3: Warning Case

**Input**: Medium dataset (200 units)
**Outputs**: All outputs (13.0 units)
**Timeline**: 2 hours

**Message**:
> "This audit is feasible but has some considerations: Output complexity (13.0 units) is significantly higher than recommended (240.0 units). Estimated time: 17.4 seconds."

**Suggestion**:
> "Consider reducing the number of outputs or simplifying output requirements"

## Message Guidelines

1. **No Math Exposure**: Never show formulas like "O + 2I" to users
2. **Plain Language**: Use simple, clear language
3. **Actionable**: Always provide suggestions when warnings occur
4. **Contextual**: Messages adapt based on user selections
5. **Positive**: Frame positively when possible ("consider" vs "don't")

## Related Documentation

- [Orchestration Engine](./ORCHESTRATION_ENGINE.md)
- [Orchestration Design](./ORCHESTRATION_DESIGN.md)
- [Output Weights](./OUTPUT_WEIGHTS.md)