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 Design
• Output Weights