# Fluix Recurring Issues

**One-line purpose:** Find the checklist items, defects, or failure types that keep showing up across many inspections, instead of treating every failed inspection as its own unrelated event. For each recurring issue, distinguish whether it's concentrated on one specific asset (a repair-that-unit problem) or spread across many assets of the same type (a systemic, model-wide problem) — since those need different fixes. Not a data-integrity pass on individual records (Fluix Data Integrity Check) and not a peer comparison (Fluix Benchmark) — this one answers "what keeps going wrong, and is it one unit or a pattern."

---

## When to trigger it

- "What issues have been reported repeatedly across our inspections in the last [X] days?"
- "What failures or defects happen most often on [asset type]?"
- "What keeps failing?" / "What's our most common defect?"
- Any request asking which problems recur across many records, as opposed to one record's own completeness (Data Integrity Check) or how one group compares to another (Benchmark)

## Inputs

Required:
- **Data source and tool family** — same discovery as the other Fluix skills (`tasks_list_reports` / `docs_list_datasets` / `docs_status_rows`). If no source is named, ask which one.
- **Time period** — "last N days" is the most natural framing here. If the request states one, use it directly; if not, ask via quick-select (Last 7 days / Last 30 days / Last 90 days / Custom). A very short window rarely has enough repetition to show a real pattern — if the resolved window returns too few records to tell a pattern from chance, say so rather than presenting a thin sample as a trend.

Optional, inferred from context or defaulted:
- **Asset/equipment type or site scope** — if the request names one, scope to it. Otherwise scan everything, and only break out by asset/equipment type when that breakdown reveals something the aggregate view doesn't (same rule the Dashboard skill uses for cross-tabs).
- **Recurrence threshold** — defaults to 2+ occurrences within scope to count as "recurring" rather than a one-off. State the default plainly when it's used, so the exclusion isn't silent.

## Workflow steps

1. **Find the data source and confirm tool family** — identical to the other Fluix skills.
2. **Get the schema first, always** — same field classification as the Dashboard skill. Specifically identify every checklist/finding-style field (a categorical field whose values include a fail/defect/non-compliant-style outcome), any unified issue-category field, any severity/priority-style field, and every available grouping dimension (asset/equipment type, site, work type) — same dimension detection as Benchmark. Treat a unified issue-category field and individual checklist/finding fields as complementary signals, not alternatives — when both exist, both get analyzed in the same run. The checklist fires on every inspection; the category field only fires when someone chooses to escalate it, so they answer slightly different questions, and the gap between them is itself worth surfacing.
3. **Resolve the time period** — via quick-select or a stated day count, same pattern as Pulse Digest. Don't pull data until this is settled.
4. **Identify the use case** — same reasoning as the other Fluix skills, since what counts as "an issue" depends on the process type.
5. **Pull the rows in scope.**
6. **Count frequency for every available signal**: if a unified issue-category field exists, count occurrences per category; separately, for every individual checklist/finding field, count how many times it registered a fail/defect-style value. Run both counts whenever both field types exist — don't pick one over the other.
7. **When both a unified issue-category field and individual checklist fields exist, check consistency between them.** For each checklist item that fired on a record, check whether a matching issue-category entry exists on that same record. Count how many checklist-level flags have no corresponding logged issue — that's a real, reportable number (a possible under-logging gap). Stop at the count and which records it touches; diagnosing *why* the gap exists is Data Integrity Check's job, not this one's.
8. **Filter to issues meeting the recurrence threshold** (2+ by default). A single occurrence isn't a pattern yet and stays out of the ranked list — but note the total count of excluded one-offs, so it's clear they were considered, not missed.
9. **For each recurring issue, check whether it's concentrated on one specific asset or spread across many different assets of the same type.** State which — a repeated failure on the same unit needs a repair; the same failure spread across many units of a type points at the model or the process, not one machine.
10. **Check for dependency between the available categorical signals, in both directions:**
   - *Issue-first:* for the top recurring issue(s), does the breakdown by site/asset-type/team concentrate somewhere, or spread evenly? Only surface this as its own view when it changes the story.
   - *Group-first:* does any individual site/team/asset-type have a distinctly different issue-type mix from the account's overall mix — one issue dominating there that isn't dominant elsewhere? This is a different finding than "issue X happens a lot at site Y" — it's "site Y's problems don't look like everyone else's problems," and it only shows up by comparing full mixes, not single-issue breakdowns.
   - *Frequency vs. severity, when a severity field exists:* rank issues by severity mix (share that's High/Critical), not just raw count, and compare the two rankings. A less-frequent issue that skews more severe is a different priority than the most-common one — don't let volume stand in for urgency. If severity varies meaningfully by site or team too, check that as its own pairing.
   - When no unified issue-category field exists, run the same checks directly on individual checklist/finding fields — which specific checklist item's fail rate depends on group, or on severity if one's tracked per-item. If a report's checklist fields show no variance at all (every answer the same value), say so plainly rather than forcing an empty dependency analysis.
   - When a real concentration or distinct mix turns up, check whether an available field (site country, asset model, mounting/installation type, install date) explains it — a shared attribute across the affected sites/assets, or the absence of one. State plainly when nothing in the data explains the pattern rather than speculating a cause.
11. **Cap the ranked list** at roughly 5-8 recurring issues, same as the other Fluix skills, noting "+N more recurring issues" rather than listing every one.
12. **Render as one widget**, same visual language as Benchmark: a metric-card strip (records in scope, distinct recurring issues found, one-off issues excluded, most frequent issue and its count, and — when checklist fields exist alongside a category field — the top checklist item and the unlogged-flag count from step 7), followed by a horizontal bar chart ranking issues by frequency. When both an issue-category field and checklist fields exist, include both frequency charts — the category-level ranking and the checklist-item-level ranking — in the same first output, not just the category view with checklist detail held back for a follow-up question. If step 10 found one issue worth breaking out by group, add a bar chart for that breakdown. If step 10 found that multiple issues each have their own distinct group signature, use a group-by-issue-type grid instead of a single breakdown chart. If step 7 found a strong correlation between a checklist item and a category (the item fires much more often on records with that category than without), a small comparison chart showing that split is worth including too — it shows the category is backed by what the checklist actually caught. Below the widget, narrative text naming what matters and why, not restating what the chart already shows, including the checklist-vs-category gap when step 7 found one.

## Output format

One widget — no separate narrative text section. The callouts that used to be prose render as cards inside it.

**The widget**, in this order:
1. A metric-card strip: records in scope, distinct recurring issues found, one-off issues excluded, the most frequent issue with its count — plus, when applicable, the highest-severity issue (if different from most frequent), and the top checklist item with its checklist-vs-category gap count.
2. One horizontal bar chart ranking recurring issues by frequency. When both a category field and checklist fields exist, a second bar chart ranking checklist items by fail count too — the checklist view belongs in the first output, not something added only when asked for separately.
3. When it adds real signal (per step 10): either a second bar chart breaking one issue down by group, or — when several issues each show their own group-level signature — a group-by-issue-type grid instead. When a checklist item correlates strongly with a specific category, a small comparison chart (that item's rate on records with the category vs. without it) is worth including too.
4. A styled card per recurring issue that made the ranked list — same card pattern as Fluix Risk Check: bold issue name, a badge showing its count (and severity share, when tracked), and one or two lines covering what the chart can't show: concentrated on one specific asset (name it) vs. spread across many, and any checklist-vs-category gap tied to that issue.
5. A muted footer line: one-off count excluded, the recurrence threshold used, sample size, and a demo/sample-data flag if warranted.

## Guardrails

- Never call a single occurrence "recurring" — the threshold is stated, and anything below it stays out of the ranked list.
- Don't restate a chart's numbers in a card's body text — name the issue and the part the chart can't show (concentrated on one asset vs. spread across many, which specific asset).
- Only add an asset/equipment-type breakdown chart when it changes the finding — an even spread doesn't need its own chart, just a sentence saying so.
- Check both directions of the dependency (does an issue concentrate by group, and does a group have its own distinct issue mix) — the second one is easy to miss if only the first is checked, and they surface different patterns.
- Don't let frequency stand in for severity — rank by both when a severity field exists, and call out when the most frequent issue isn't the most severe one.
- Never propose a cause for a concentration pattern without checking whether an available field actually supports it — state plainly when nothing in the data explains it, rather than speculating a reason that sounds plausible but isn't backed by anything pulled.
- Don't treat a unified issue-category field as a substitute for checklist-level detail, or vice versa — when both exist, both belong in the same output. The checklist catches more; the category field shows what got formally escalated; neither view alone is complete.
- A checklist-vs-category gap is a count to report, not a finding to explain — flag it and stop. Diagnosing why it happened is Data Integrity Check's job.
- If a free-text issue-description field is the only source of "what went wrong" (no structured checklist field), summarize the recurring theme in your own words rather than reproducing large chunks of the original text verbatim.
- This skill only surfaces patterns — it never files a corrective action, opens a work order, or modifies any record.
- Same data-quality stance as the other Fluix skills — flag demo/sample data or too-small samples rather than treating them as real signal.