docs(nx-cloud): document new flaky tasks analytics (#33253)

Co-authored-by: nx-cloud[bot] <71083854+nx-cloud[bot]@users.noreply.github.com>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>

Author: 3 people

astro-docs/src/assets/features/ci-features/mark-task-as-likely-flaky.png

@@ -39,12 +39,60 @@ In this image, the `e2e-ci--src/e2e/app.cy.ts` task is a flaky task that has bee
 
 When a flaky task fails in CI with [distributed task execution](/docs/features/ci-features/distribute-task-execution) enabled, Nx will **automatically send that task to a different agent** and run it again (up to 2 tries in total). Its important to run the task on a different agent to ensure that the agent itself or the other tasks that were run on that agent are not the reason for the flakiness.
 
-## Manually Mark a Task as Flaky or Not Flaky
+## Flaky Task Analytics
 
-If you suspect that a task is flaky, but Nx has not confirmed it yet, you can manually **mark it as likely flaky** from the run details screen. Failed tasks that are not flaky will have a button that says **"Mark task as likely flaky"**.
+{% aside type="note" title="Enterprise Feature" %}
+Workspace flaky task analytics is currently available for organizations on the Enterprise plan. Reach out if your organization is [interested in Nx Enterprise](https://nx.dev/enterprise?utm_source=nx.dev&utm_medium=callout&utm_campaign=flaky-task-analytics).
+{% /aside %}
 
-![Mark task as likely flaky button](../../../../assets/features/ci-features/mark-task-as-likely-flaky.png)
+Nx Cloud provides analytics to help you understand and manage flaky tasks across your workspace. The analytics dashboard gives you insights into which tasks are flaky, how often they fail, and how much time is being wasted on reruns.
 
-Once you've resolved the issue that caused a task to be flaky, you can immediately mark the task as not flaky by clicking on **"Mark task as no longer flaky"** on the same run details screen.
+![Flaky Tasks dashboard](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-metrics-chart.avif)
 
-![Mark task as no longer flaky button](../../../../assets/features/ci-features/mark-task-as-no-longer-flaky.png)
+The dashboard displays key metrics over the time range selected (7 days vs 30 days) to give you a quick overview of your workspace health.
+
+- **Active flaky tasks** - The total number of tasks in your workspace that have a flake rate greater than 0 within the selected time window.
+- **Average flake rate** - A weighted average flake rate across all tasks in your workspace. This metric uses the sample size to weight each task's flake rate proportionally, so a task that ran 1000 times with 5% flake rate has more impact than one that ran 10 times with 50% flake rate.
+- **High risk tasks** - The number of tasks with a flake rate higher than 20%, indicating severe reliability issues that need immediate attention.
+
+The chart shown provides a visual representation of your flaky tasks, helping you quickly identify which tasks need the most attention.
+
+Tasks are plotted based on their **impact score**, which is calculated as `flake_rate × sample_size`. This means frequently-run flaky tasks are weighted higher than rarely-run flaky tasks.
+
+Priority levels are determined using percentile-based thresholds that scale across organizations of any size:
+
+- **High priority** (red) - Top 10% of tasks by impact score (90th percentile and above). These tasks have severe flakiness and should be addressed immediately.
+- **Medium priority** (yellow) - Next 23% of tasks by impact score (67th-90th percentile). These tasks have moderate flakiness with sufficient data.
+- **Low priority** (gray) - Bottom 67% of tasks by impact score. These tasks have minor flakiness or not enough data to be concerning.
+
+Tasks on the right side of the chart typically represent the highest priority items that need attention. The scatter plot shows up to 50 results, sorted by most recent flaked tasks.
+
+### Flaky Task Table
+
+The table provides detailed information about each flaky task in your workspace:
+
+![Flaky Tasks Analytics Table](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-table.avif)
+
+By default, the table loads your most recent flaky tasks. Each row includes:
+
+- **Task** - The project and target combination (e.g., `my-app:test`)
+- **Flake rate** - Measures how often a task succeeds due to flakiness. Specifically, it represents the percentage of total successes that came from unreliable (flaky) task hashes: `flaky_successes / (flaky_successes + non_flaky_successes)`. This tells you: "Of all the times this task succeeded, how many successes came from unreliable code?"
+- **Total reruns** - The number of times a task was executed more than once due to flakiness. This counts the "extra" executions that happened because the task failed and needed to be retried. Calculated as: `total_executions - unique_hash_count`
+- **Time wasted** - An estimate of the total time spent on reruns, calculated by multiplying the total reruns by the average task duration
+- **Last failure** - The timestamp of the most recent failure across all contributing task hashes
+
+#### Flaky Task Detail View
+
+Click on any row in the table to view detailed information about a specific flaky task.
+
+The **Overview** tab shows summary statistics and trends for the selected task such as flake rate, time wasted and automatic deflake counts
+
+![Flaky Task Detail Overview](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-details.avif)
+
+The **Activity** tab displays a timeline of all executions, showing when the task failed and succeeded to jump directly into the runs.
+
+![Flaky Task Detail Activity](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-detail-activity.avif)
+
+The **Environments** tab provides insights into the different environments where the task was executed, helping identify if certain environments contribute to flakiness.
+
+![Flaky Task Detail Environments](../../../../assets/features/ci-features/nx-cloud-flaky-tasks-detail-environment.avif)

astro-docs/src/assets/features/ci-features/mark-task-as-no-longer-flaky.png

@@ -92,6 +92,12 @@ A script that performs some action on your code. This can include building, lint
 
 > See: [Executors and Configurations](/docs/concepts/executors-and-configurations)
 
+### Flake Rate
+
+A metric that measures how often a task succeeds due to flakiness rather than reliable code. It represents the percentage of total successes that came from unreliable (flaky) task hashes: `flaky_successes / (flaky_successes + non_flaky_successes)`. This answers the question: "Of all the times this task succeeded, how many successes came from unreliable code?"
+
+> See: [Flaky Task Analytics](/docs/features/ci-features/flaky-tasks#flaky-task-analytics)
+
 ### Flaky Tasks
 
 Tasks that will sometimes succeed and sometimes fail without any change to the inputs. These tasks are often e2e tests and are particularly problematic in CI. Nx Cloud automatically detects flaky tasks and re-runs them.
@@ -110,6 +116,12 @@ A computer science concept that consists of nodes connected by edges. In the Nx
 
 > See: [Explore the Graph](/docs/features/explore-graph)
 
+### Impact Score
+
+A metric used in [Flaky Task Analytics](#flaky-tasks) to prioritize which flaky tasks need attention. Calculated as `flake_rate × sample_size`, it weights frequently-run flaky tasks higher than rarely-run flaky tasks. For example, a task with 50% flake rate and 100 runs has an impact score of 50, the same as a task with 10% flake rate and 500 runs.
+
+> See: [Flaky Task Analytics](/docs/features/ci-features/flaky-tasks#flaky-task-analytics)
+
 ### Launch Template
 
 Launch Templates are used to set up an agent machine. They specify a resource class, an image and a series of set up steps before tasks are executed on that machine.