# Fluix Bottleneck Finder

**One-line purpose:** Find what's actually wrong with a process or a form — not any single record. Works at two scopes: point it at one report and it finds which workflow step consistently takes longest, what's missing or poorly designed in the form, and which fixes are worth making, ranked by impact against effort. Point it at "which forms/reports" and it compares data quality across many sources at once to find which ones are the worst offenders. Structural and forward-looking either way: distinct from Fluix Data Integrity Check (which audits individual records within one source) and Fluix Risk Check (which diagnoses why one item is stuck) — this asks what's wrong with the process or the form itself, whether that's one process in depth or many forms compared side by side.

---

## When to trigger it

- "Where does our process get stuck" / "what's our biggest bottleneck"
- "What should we fix in this workflow" / "review this form for gaps"
- "What would improve this the most" / "where's the best ROI on fixing something here"
- "Which forms produce the most incomplete submissions" / "which inspection forms have the worst data quality this month"
- Any request about structural process or form-design problems, whether scoped to one report or comparing many — as opposed to a specific record's completeness (Data Integrity Check) or a specific item's blocker (Risk Check)

## Inputs

Required:
- **Scope** — a single named report/source, or a comparison across many ("which forms," "which reports," a named category like "inspection forms"). Infer from phrasing: a specific report name points to single-source mode; a "which X" comparison request points to multi-source mode. If genuinely ambiguous, ask.
- **Data source(s) and tool family** — same discovery as the other Fluix skills (`tasks_list_reports` / `docs_list_datasets`). In multi-source mode, this defaults to every report/dataset in scope rather than one.

Optional, inferred from context or defaulted:
- **Time range** — defaults to all available history, since both step-duration and cross-source comparison need volume to be reliable; if the person names a narrower window ("this month"), use that and note the smaller sample in the confidence line.
- **Specific workflow step(s) to focus on** (single-source mode only) — if named, narrow to those. Otherwise scan the full workflow.
- **Breakdown dimension** (single-source mode only) — workflow, site, or owner/assignee. Infer from phrasing when named; otherwise check all available and only surface the one(s) that reveal a real concentration, same rule Benchmark and Recurring Issues use for their own breakdowns.

## Workflow steps — single-source mode

1. **Find the data source and confirm tool family** — identical to the other Fluix skills.
2. **Get the schema first, always** — same classification as the Dashboard skill, plus a specific pass over the form/template design itself:
   - Fields that are rarely-to-never populated across records (a possible sign the field is unused, misunderstood, or the workflow never actually reaches it).
   - Free-text fields whose observed values collapse into a small, repeating set — even without visible formatting drift yet, a low ratio of distinct values to populated records is itself evidence the field belongs in a dropdown, before messiness has a chance to accumulate. Distinguish this from fields that are genuinely free text by nature (incident descriptions, notes) — those stay free text even if some values happen to be short.
   - Fields with generic, auto-generated-looking names (e.g. `radio-group-34`) whose purpose isn't clear from the field itself.
   - Apparent duplicate or near-duplicate fields capturing the same thing twice.
   - **Candidate conditionally-required fields**: any field whose plain-language purpose implies it should only be required when some other condition holds — evidence/photo fields tied to a defect or incident, a sign-off tied to a rejection, a follow-up date tied to a flagged issue. Note these for the cross-check in step 7.
3. **Identify the use case** — same reasoning as the other Fluix skills.
4. **Pull rows across the full source** (not filtered to open-only — step duration needs the complete lifecycle of closed records too).
5. **Compute time spent at each workflow step/stage**, using whatever timestamp fields exist (created, submitted, approved, closed, etc.). Identify the step(s) with disproportionately long average dwell time relative to the others — the same concentration/outlier logic as the Dashboard skill, not a fixed duration threshold. If the source doesn't have enough timestamp fields to compute step duration, say so plainly rather than guessing at where time is lost.
5a. **Compute the current status distribution at each step, separately from duration** — how many open items sit in each status (e.g. NEW / IN_PROGRESS / overdue / stale-no-due-date, reusing Risk Check's tiering where it applies) at that step right now. Duration answers "how long does this step typically take"; distribution answers "how much is piled up here today" — they can disagree, so report both rather than assuming one implies the other.
6. **Break down the slow step(s) by the resolved breakdown dimension(s)** (workflow, site, or owner/assignee) — a bottleneck tied to one cause is a different, often easier, fix than one spread evenly across the board. Only render a breakdown that actually concentrates; state plainly when a dimension comes back even.
7. **For every candidate conditionally-required field from step 2, check whether it's actually populated conditionally.** Cross-tab it against the condition it's meant to respond to. If it's populated at the same rate regardless of the condition, it isn't functioning as conditional evidence — say so, and note whether the fix is enforcing the condition on the existing field or adding a dedicated one.
8. **Score candidate fixes on Impact and Effort**, plain labels (High/Medium/Low, or a range when the evidence doesn't cleanly land on one) with the specific evidence behind each — no hidden formula.
9. **Rank fixes by the strongest impact-to-effort combination first**, cap at roughly 5-8.

## Workflow steps — multi-source mode

1. **List every report/dataset in scope** via `tasks_list_reports` and `docs_list_datasets`, filtered per the resolved scope. A large list is fine — this mode is built to scan many sources, unlike the single-source path.
2. **For each source in scope, run Data Integrity Check's core logic**: schema, field classification, required-field inference from population patterns on completed records, and gap counts by type (missing required fields, missing photos/signatures, logic contradictions, placeholder values) — aggregated into one completeness rate per source rather than a per-record list.
3. **Compute the pooled, weighted account-wide average completeness rate** across every source in scope — the same weighted-not-unweighted logic Benchmark uses, so a source with 5 records doesn't move the average as much as one with 500.
4. **Rank sources by completeness rate**, worst first, each with its gap from the account average.
5. **For the worst-ranked sources, name the dominant gap type** — missing signatures, missing photos, contradictions, or placeholders each imply a different fix, so the type matters as much as the rate.
6. **Cap the ranked list** at roughly 5-8 sources, noting "+N more" rather than listing every report in the account.

## Output format

One widget — no separate text block. Findings render as cards inside it, same visual language across both modes.

**Single-source mode:**
1. A metric-card strip: slowest step and its duration, current status distribution at that step, a headline number from the conditional-requirement check when one was run, and the count of fixes identified.
2. A styled card per fix, ranked by impact-to-effort, capped at 5-8: bold fix name, Impact and Effort as two small badges side by side, an icon-led evidence line, an icon-led suggested-action line.
3. A muted footer line: minor form-labeling issues that didn't earn a full card, sample size, timestamp coverage, and a demo/sample-data flag if warranted.

**Multi-source mode:**
1. A metric-card strip: sources compared, account-wide average completeness rate, worst source and its rate, total gaps found across everything in scope.
2. A bar chart ranking sources by completeness rate, account average stated in the label above it.
3. A styled card per flagged source, capped at 5-8: bold source name, a badge with its rate and gap from average, an icon-led line naming the dominant gap type with its count, an icon-led suggested-fix line.
4. A muted footer line: time period used, thin-sample caveats, and a demo/sample-data flag if warranted.

## Guardrails

- Never assign an Impact or Effort label without stating the specific evidence behind it — no hidden scoring.
- If a source lacks the timestamp fields needed to compute step duration, say so rather than guessing where time is being lost.
- Never claim a conditional-requirement gap without actually cross-tabbing the candidate field against its condition.
- Don't conflate duration and status distribution — report both, don't infer one from the other.
- Only render a breakdown dimension (workflow/site/owner) that actually concentrates — an even spread is a sentence, not a chart.
- Never recommend converting a field to a dropdown on the strength of "it's free text" alone — check that observed values actually cluster into a small, repeating set.
- In multi-source mode, compute the account-wide average as pooled/weighted, never an unweighted mean across sources, and reuse Data Integrity Check's exact gap-detection logic rather than a looser or stricter standard just because the comparison spans sources instead of staying within one.
- Name the dominant gap type per flagged source in multi-source mode — a low rate driven by missing signatures needs a different fix than one driven by placeholder values.
- This skill only analyzes and suggests — it never modifies a workflow, a form, a template, or any record.
- Cap every ranked list; "+N more" is correct, exhaustive dumps are not.
- Same data-quality stance as the other Fluix skills — flag demo/sample data or too-small/thin samples rather than treating them as real signal.