# Swarmia documentation

Get help with Swarmia's features, integrations & definitions.

<table data-column-title-hidden data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td>Get started in 15 minutes</td><td><a href="/pages/oWeDAf8N3sY0RodxdyPG">/pages/oWeDAf8N3sY0RodxdyPG</a></td><td><a href="/files/sS1moCpphibXnC4Xwyui">/files/sS1moCpphibXnC4Xwyui</a></td></tr><tr><td>Integrations</td><td><a href="/pages/ApCGSHS2U1sSkpeYe1RD">/pages/ApCGSHS2U1sSkpeYe1RD</a></td><td><a href="/files/6PbY4x1XBrDEGMWhQjtR">/files/6PbY4x1XBrDEGMWhQjtR</a></td></tr><tr><td>Configuration and data quality</td><td><a href="/pages/UpEjlcj5gxJutD1Pgpi1">/pages/UpEjlcj5gxJutD1Pgpi1</a></td><td><a href="/files/yS79uhHRnGXw8rLnv4hV">/files/yS79uhHRnGXw8rLnv4hV</a></td></tr></tbody></table>

Can't find what you're looking for? Reach out to us at <hello@swarmia.com>


# Get started in 15 minutes

Connect your code hosting platform, issue tracker, and messaging app, and create Swarmia teams to get started.

Swarmia is a software engineering intelligence platform that helps engineering leaders and their teams understand whether they’re working on the right things, find what’s holding them back, and keep getting better — with data they can trust and the tools to act on it. Follow these steps to get started.

{% hint style="info" %}
By default, Swarmia syncs 1 year of code and issue tracker data when you connect your integrations.
{% endhint %}

## Step 0: Sign up

[Sign up](https://app.swarmia.com/signup/) to create your Swarmia organization. You can choose from three authentication methods: Google, Microsoft, and GitHub. If you select GitHub, you need to install Swarmia in your GitHub organization to continue. After signing up, you can change the authentication method to any of the three or enable Okta.

The Swarmia app home page guides you through the initial setup steps.

<figure><img src="/files/NIQAB7mUO9nVuwaNoGY0" alt=""><figcaption></figcaption></figure>

## Step 1: Connect code hosting platform

If you signed up by authenticating with GitHub, you have already completed this step.

### GitHub

**GitHub Cloud**

1. Ensure you have [the necessary admin permissions on GitHub](https://docs.github.com/en/github-ae@latest/developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps#who-can-install-github-apps-and-authorize-oauth-apps)
2. Navigate to [code hosting settings in Swarmia](https://app.swarmia.com/settings/version-control), click **Connect**, and select GitHub Cloud
3. Select the GitHub organization
4. Select the repositories you want to sync to Swarmia
5. Review the required authorizations, and click *Install & Authorize*

**GitHub Enterprise Server**

1. Contact us at <hello@swarmia.com> to get you started
2. [See detailed instructions](https://help.swarmia.com/getting-started/integrations/github/github-enterprise-server)

### GitLab

**GitLab Cloud**

1. Create a service account user in GitLab and add it to the projects you want to import to Swarmia
2. Log in to the GitLab service account, navigate to [code hosting settings in Swarmia](https://app.swarmia.com/settings/version-control), click **Connect**, and select GitLab Cloud
3. Authorize the app
4. Add webhooks in GitLab settings

**GitLab Server**

1. Create OAuth app in your GitLab server
2. Create a service account user in GitLab and add it to the projects you want to import to Swarmia
3. Add the OAuth app details to Swarmia: Log in to the GitLab service account, navigate to [code hosting settings in Swarmia](https://app.swarmia.com/settings/version-control), click **Connect**, and select GitLab Server
4. Add webhooks in GitLab settings
5. Configure your firewall to allow Swarmia's IP address

[See detailed instructions](https://help.swarmia.com/getting-started/integrations/gitlab) for GitLab Cloud and GitLab Server.

{% hint style="info" %}
All users in your Swarmia organization can read the metadata (such as pull or merge request names) for all integrated repositories in Swarmia. Use caution if working with sensitive repositories.\
\
Swarmia collects the file names and sizes of commits from the source code. **We do not store your source code.** [Learn more about data security.](https://www.swarmia.com/security/)
{% endhint %}

## Step 2: Connect issue tracker

### Jira

1. Ensure you have Jira admin permissions
2. Navigate to [issue tracker settings in Swarmia](https://app.swarmia.com/settings/issue-trackers) and follow the installation guide
3. After the projects are synced and you have created your Swarmia teams (Step 4), [assign issue ownership for the teams](/settings/team/issue-ownership).

[See detailed instructions.](/settings/integrations/issue-trackers/jira)

### Linear

1. Ensure you have Linear admin permissions
2. Navigate to [Linear settings in Swarmia](https://app.swarmia.com/settings/linear) and follow the installation guide

[See detailed instructions.](/settings/integrations/issue-trackers/linear)

## Step 3: Connect messaging app

### Slack

1. Ensure you have Slack admin permissions
2. Navigate to [Slack settings in Swarmia](https://app.swarmia.com/settings/slack) and follow the installation guide
3. Sign in to your Slack workspace, review permissions, and click **Allow.**

### Microsoft Teams

1. Ensure Entra SSO is selected as your organization's authentication provider.
2. Ensure you have the Teams Administrator role or have permission to add apps to your Microsoft organization.
3. Navigate to [Microsoft Teams settings in Swarmia](https://app.swarmia.com/settings/microsoft-teams) and follow the installation guide.

[See detailed installation instructions](/settings/integrations/messaging-apps/microsoft-teams)

{% hint style="info" %}
Most engineers interact with Swarmia through Slack or Microsoft Teams by receiving personal notifications, team digests, and feedback on working agreements. [Read our blog post](https://www.swarmia.com/blog/github-slack-integration/) to learn about the benefits.
{% endhint %}

## Step 4: Create teams

Organize contributors into teams to see data across your organization in Swarmia. For new organizations, we automatically create a trial team consisting of all active contributors in your GitHub organization. The team lets you see relevant data from the start, and you can delete it after creating at least one new team.

Swarmia automatically merges user identities from all connected tools into contributors. You can review and edit them in [contributor settings](https://app.swarmia.com/settings/contributors).

Navigate to [team settings](https://app.swarmia.com/settings/teams), and choose from the following methods:

* Create teams manually by adding contributors to teams
* Import teams from GitHub
* Integrate with the Swarmia team API

[Learn more about creating & managing teams.](/settings/organization/managing-teams)

## **We're here for you**

Our team is ready to help you during setup and onboarding. For questions or feedback, reach out to us via the in-app form or email at <hello@swarmia.com>.


# Focus


# Focus summary

The focus summary allows you to easily explore what your teams and organization are spending the most effort (FTEs) on.

## Overview

The focus summary helps you understand where your teams are investing their time. By measuring effort in full-time equivalent (FTE) months across issues, initiatives, and contributors, you get a clear picture of what's actually being worked on – and how that effort is trending over time.

## What you can see in the focus summary

<figure><img src="/files/Lly3WO2XGK10MmxF5deQ" alt=""><figcaption></figcaption></figure>

Above the table, you'll see a panel showing **total effort** for the selected team and timeframe, measured in full-time equivalent (FTE) months. This is the full capacity in FTE months.

When you apply additional filters, a **filtered effort** panel shows how much of the total capacity matches all your current filters and is displayed in the table.

The table displays all issues matching your selected timeframe, team, and filters. Each issue can be expanded to reveal matching child issues.

For each issue, you'll see:

* **Issue details**
  * Issue name and key
  * Status
  * Time spent in progress
  * Total child issues
  * Lifetime effort: Total FTE months invested since the issue was created
* **Contributors:** Individual contributors with effort attributed to the issue
* **Effort breakdown:** FTE months invested in the issue and its percentage share among all shown work (during the selected timeframe)
  * Includes a monthly trend breakdown for the selected timeframe

### Interpreting effort trends

* **Inactivity:** The effort column displays the total number of FTE months during the selected timeframe, while the trend column indicates whether any months were inactive. This can surface a lack of focus in key initiatives.
* **Winding up vs. winding down:** The shape of the trend breakdown can also tell you whether a project is starting or ending. Generally, in cross-team projects, effort tends to be highest when multiple teams are contributing simultaneously, and towards the end, most teams have already moved on to other projects.

## Focus summary options

### Filtering the view

The primary filters in the focus summary are team and timeframe. You can also narrow down the view using all standard issue filters available in Swarmia - you can find most of them under "More filters…"

### Grouping by initiative

By default, issues are grouped by the highest level in your issue hierarchy. Alternatively, you can group work by Swarmia initiatives.

{% hint style="info" %}
Swarmia initiatives are not mutually exclusive; a single issue can belong to multiple initiatives, depending on how they have been defined. This means the total focus percentages in the view may exceed 100%.
{% endhint %}

### Showing unlinked pull requests

By default, unlinked pull requests are hidden from the focus summary. To see how much focus is dedicated to unlinked PRs, toggle them on under "More filters…"

## Example: Show the latest active stories on a timeline

Filters let you shape the focus summary into the view you need. As an example, you can see what stories a team has been working on over the past 6 months.

<figure><img src="/files/R7RxnpEzHOapFRMuFeok" alt="Focus summary in the Activity layout, filtered to stories and sorted by last activity"><figcaption></figcaption></figure>

1. Open "More filters…" and set **Issue type** to **Story**, so the view shows story-level work.
2. Switch the layout to **Activity** with the layout selector. This plots effort over time instead of showing the table.
3. Set the timeframe to the last 6 months.
4. Set the time bucket to **Week**, so each column covers one week.
5. Sort the rows by **Last activity** using the sort control, to bring the most recently active stories to the top.

You'll get a weekly timeline of story-level work across the past year, with the most recently active stories on top.


# Investment balance

Analyze team focus, improve time allocation and boost focus on top priorities

{% embed url="<https://www.youtube.com/watch?v=9o0T-2dL2RQ>" %}

## Overview

Building software products is a balancing act. To build sustainably, engineering teams must balance short-term and long-term goals, as well as new features, technical debt, and productivity improvements.

Investment balance helps engineering organizations get visibility into how they allocate their efforts across different priorities and identify where improvements can be made:

* Leadership can decide which teams need more headcount
* Engineering Managers and Product Managers keep different priorities in balance
* Developers can make a business case for a technical improvement project

## Setup

Swarmia creates a [Balance](https://www.swarmia.com/blog/balancing-engineering-investments/) breakdown by default, but you can create up to 5 breakdowns. Each breakdown has its own set of categories, for which you [define rules to categorize work](https://help.swarmia.com/configuring-investment-categories). You can also limit the scope of a breakdown to a subset of data (e.g., only work owned by a single team).

If you have a paid Swarmia plan, you can also enable [AI categorization](/settings/organization/investment-balance/automatic-categorization), which will categorize work based on your category descriptions in addition to any rules you've applied.

We don’t expect perfect issue-tracking hygiene, as Swarmia includes automated and manual tools to improve data quality. Your team will need to [link pull requests to issues](https://help.swarmia.com/how-do-i-link-pull-requests-to-issues-in-practice) using one of the supported mechanisms to improve accuracy.

## Using the investment balance

In Swarmia, you can create multiple investment breakdowns, define custom categories, and add custom rules to automatically attribute work to categories. For the primary investment breakdown, investment balance can be viewed on the organization, team, and individual levels.

We recommend starting with [the Balance framework](https://www.swarmia.com/blog/balancing-engineering-investments/), which splits the work into four categories:

* **New things:** new products and features
* **Improvements:** enhancing existing features, tools, or business processes
* **Productivity:** making it easier to get work done in the future
* **Keeping the lights on (KTLO):** maintaining existing systems and services

A healthy balance is to allocate 10-15% of the effort to productivity and keep KTLO under 30%. The remaining 60% can be invested in new things and improvements based on your objectives.

Start by configuring [your first categorization rules](https://help.swarmia.com/configuring-investment-categories), and then head to [investment balance overview](https://app.swarmia.com/investment), select a team, and review the categorized and uncategorized work.

Once your highest-level work items are categorized (e.g. initiatives or epics), Swarmia will process the issue hierarchy automatically to auto-categorize all remaining child issues and related coding contributions.

After the initial setup, data in balance views is updated in real-time.

<figure><img src="/files/hYUnkPcE8eIrv0BPI9Y6" alt=""><figcaption><p>Creating an investment breakdown</p></figcaption></figure>

<figure><img src="/files/yx3GR3QyIJP5ft6Mfqx8" alt=""><figcaption><p>Flexible categorization rules</p></figcaption></figure>

## Taking action

Decide on the initial breakdown and aim to achieve at least 80% categorization using automated categorization rules. Consider using a binary breakdown, such as Planned vs. Unplanned work for an easier start.

Consider establishing a convention for labeling your highest-level work items in your issue tracker. Additionally, review your highest-level uncategorized items and the largest investments in each investment category at least once a month.

Introduce the concept of investment balance to teams and facilitate discussions on the ideal balance they should strive for. If teams are struggling with maintaining essential operations (*keeping the lights on*), ensure they have the necessary support and strategies in place.

Swarmia provides [a working agreement to help teams categorize work](https://app.swarmia.com/working-agreements/explore/pull-request-linking) through timely Slack and Microsoft Teams reminders. These reminders are triggered only for work that wasn’t categorized by automated filters, minimizing context switch.

Swarmia provides additional views for viewing and balancing investment efforts:

* [Work Log](https://app.swarmia.com/work) helps teams prioritize their daily efforts.
* [Focus Summary](https://app.swarmia.com/insights/focus) shows the distribution of effort across different initiatives.
* [Developer Overview](https://app.swarmia.com/overview) helps individuals understand their personal investment balance.

### Common problems with balancing engineering investment

As organizations mature and grow, more things compete for teams' attention. This can result in teams spreading their focus too thin and not spending enough time on their top priorities.

It's easy to imagine the difference between a team spending 20% of their time towards a goal versus one that spends 40%: the time to deliver a solution at least doubles. This isn't good news for the team or the organization – **but there's a massive opportunity on the flip side: teams that can improve their roadmap focus can drastically increase their impact.**

Here are some questions Investment Balance can help you answer:

* **Are you spending less than 50% of your time on high priorities?** Spending little time on the most important category might mean your team has too many things to focus on, or that it's not clear how to move forward with the key projects.
* **Is a majority of your time going to bug fixing and maintenance work?** An increasing trend in bug fixes and maintenance work can indicate a problem with the team's health. This might require an action such as investing in infrastructure or addressing some of the technical debt the team has accrued.
* **Are you spending more time on ad hoc tasks?** As organizations and systems grow, so does complexity. It's sometimes easy to get overwhelmed by the number of goals, opportunities, and the difficulty of solving complex problems. This can cause teams and individuals to fall back on simple, reactive tasks that are easy to complete, but time spent on them might not maximize the team's impact.
* **Do you have a lot of unlinked work?** Drawing good conclusions without transparency to a major share of the work can be difficult. Creating routines to link issues and pull requests, and to categorize ad hoc work, pays off and enables the team to make well-informed decisions to improve performance.

Look out for decreasing trends in the most important work. This increases your odds of catching a problem early and correcting course before it becomes a real problem.

## Further reading

* Tools that help you [improve focus in your team](https://www.youtube.com/watch?v=ow0acM--NqM)
* Model for [measuring engineering effort](https://help.swarmia.com/effort) in Swarmia
* Learn more from our [blog](https://www.swarmia.com/blog/balancing-engineering-investments/)


# Activity and effort-based models

Swarmia supports two different models to measure the work: activity-based and effort-based

## **Activity-based model**

The activity-based model shows activity on pull requests and issues grouped by investment categories. The activity model includes both completed issues and merged pull requests.

## **Effort-based model**

The effort-based model normalizes GitHub and issue tracker activities for each developer. Normalizing means Swarmia takes into account different coding and working styles. In practice, this means a developer can have a maximum of 1 FTE (full-time equivalent) in a month. The FTE is distributed across all issues and pull requests the developer has worked on during the month.

[Read more about how Swarmia measures developer effort.](https://help.swarmia.com/metrics-and-definitions/developer-effort-ftes)

## **Activities are based on team memberships**

If your team members have contributed towards issues belonging to other teams, by default also those issues will be visible in your team's investment balance. Your team is investing its time somewhere, and the report shows you where that investment goes, even if it's not for the things you might've expected. You can filter out these items by selecting *Only work owned by team* as shown in the image below.

<figure><img src="/files/dzMUMaaYH5bPJ6zYhlJ8" alt=""><figcaption><p>Investment balance with "Only work owned by team" selected</p></figcaption></figure>

## **How work is grouped by category**

We start by looking at all contributions by all team members of the selected team, then determine the investment category based on [**the rules you've set up.**](https://help.swarmia.com/configuration/organization-setup/investment-balance)

Then work is grouped by investment category (these categories are [**mutually exclusive and collectively exhaustive**](https://help.swarmia.com/configuration/organization-setup/investment-balance)).

If multiple tasks belong to a bigger project, **it's possible to have different investment categories assigned to each task and the project as a whole**. In this case, we'll show each task in its respective category of work.


# Categorization

Configure custom categories and and improve the categorization rate.

### Configuring investment categories

Investment categories are fully customizable. Before you create your own categories, we highly recommend reading our blog post on [**balancing engineering investment**](https://www.swarmia.com/blog/balancing-engineering-investments/)**,** sharing best practices on how to think of these categories.

[**See a detailed guide on how to configure investment categories**](/settings/organization/investment-balance) in Swarmia.

### Categorizing work

Swarmia comes with a couple of handy tools that help you [**categorize work**](/settings/organization/investment-balance) in minutes. You can [**set up automated filters to categorize work**](/) based on certain criteria (for example, a label or a pull request title prefix) or [**toggle on the automatic categorization**](/settings/organization/investment-balance/automatic-categorization). These systems also work seamlessly together, so you may combine rules-based categorization with Swarmia's AI categorization.

Alternatively, you can also **link issues and pull requests to investment categories manually** by selecting them anywhere in the app.

To get the full benefit out of Swarmia's investment insights, we recommend [**linking pull requests to Issues**](/settings/organization/linking-pull-requests-to-issues). There's also a [**working agreement**](https://app.swarmia.com/working-agreements/a5fe9951-ee0f-405a-b759-c67a95687bd2) that help teams do that.


# Initiatives

Set up your initiatives to enable visibility beyond team-level work.

{% embed url="<https://www.youtube.com/watch?v=5i1j9uMWR4k>" fullWidth="false" %}

## Overview

Initiatives give you a high-level view of strategic, cross-team projects that can take months—or even years—to deliver. These projects are often hard to track with engineering tools because they’re spread across different boards and teams in your issue tracker. Swarmia consolidates all that information into a single view so you never lose focus on the bigger picture.

Initiatives show the big picture:

* What has already been done and what is next
* Is something stuck at the moment or at risk of getting dropped
* How many teams and people are working on the initiative
* Which team is driving the effort

## Setup

Using Swarmia requires that you have your issue tracker connected. Setting up initiatives in Swarmia varies slightly depending on whether you use Jira or Linear.

### Jira

For Jira, there are three ways to add initiatives. You can find each method under the "**Add"** button in the initiatives overview.

1. **Create initiatives from scratch.** Define a set of filters to build your initiative. Any issues matching those filters will be included. This method lets you create groups of issues that aren't linked to each other in Jira, making initiatives more exploratory.
2. **Import initiatives from Jira.** Select individual Jira issues to import as initiatives. Each issue you select becomes a separate initiative. This method works best when you have a handful of larger projects to track in Swarmia and new ones aren't created frequently.
3. **Set up auto-import for Jira.** Auto-import is enabled by default for new Swarmia organizations if we detect you're using the issue type "Initiative" in Jira. You can specify filters to narrow or broaden what gets imported and toggle auto-import on or off.

{% hint style="info" %}
For imported initiatives, you can define in settings whether you want to include linked work items. This setting is particularly relevant if you use Jira Plans or Product Discovery, which use issue links to connect issues across projects and will be empty if you don't include linked work items.
{% endhint %}

### Linear

For Linear, there are two ways to add initiatives.

1. **Import initiatives from Linear.** Linear initiatives are automatically imported to Swarmia as initiatives. You’ll see them as soon as you’ve connected Linear to Swarmia.
2. **Create initiatives from scratch.** Define a set of filters to build your initiative. Any issues matching those filters will be included. This lets you create groups of issues that aren't linked to each other in Linear, making initiatives more exploratory.

For initiatives you create from scratch in Swarmia, you can set the description, documentation link, start date, and target date. Imported initiatives sync from your issue tracker, where you manage that information.

## Using initiatives

<div data-full-width="false"><figure><img src="/files/PzEjoXZPyxka5Kg2El48" alt=""><figcaption></figcaption></figure></div>

### Initiatives overview

The initiatives overview gives a high-level view of all ongoing initiatives within the organization. From here, you can dive deep into initiatives that need steering.

For each initiative following attributes are displayed:

* **Start date:** The planned start date or first activity date
* **Target date:** The planned completion date (or last activity date for completed initiatives)
* **Completed:** Percentage of work items completed, with a trend chart showing progress over time
* **Effort:** Full-time equivalent (FTE) months invested in the initiative
* **Trend:** A monthly effort breakdown for the selected timeframe
* **Teams:** Teams that own issues within the initiative

The completed and effort columns are filtered to your selected teams and timeframe, allowing you to focus on the initiatives a specific team has worked on and the amount of work they have remaining.

You can create saved views based on selected filters by clicking the "+" icon in the tab bar. This allows you to easily revisit initiatives that are most important to you. These views are shared among your organization.

#### Spotting patterns in the initiatives overview

The completed and effort columns are particularly useful for gaining quick insights into project progress and which project is currently in focus. By default, initiatives are sorted by effort (highest first).

<div data-full-width="false"><figure><img src="/files/KDNQGCUJbOZ7Dier5FPz" alt="" width="563"><figcaption><p>Completed and effort columns create a quick view into the work happening under the surface.</p></figcaption></figure></div>

#### Common patterns to watch for

<div align="left"><figure><img src="/files/i7z9jrCs4IWORHPyuIvI" alt="" width="236"><figcaption><p>Increasing scope</p></figcaption></figure> <figure><img src="/files/WzYkwnjv13ahXp0sUipY" alt="" width="236"><figcaption><p>Steady progress</p></figcaption></figure></div>

* **Increasing scope:** Within the completed column, you can see planned (grey) and completed (green) work items. Sometimes you might see that the completed % has decreased since your last visit. This is due to the scope increasing faster than items are completed. By hovering over the area chart, you can see a tooltip breaking down changes month-to-month.
* **Steady progress:** When planned and completed work items increase at the same pace, the completed % stays in the same range between visits. The chart can give perspective on how much work is being done, even when the overall completed percentage doesn’t change.

<div align="left"><figure><img src="/files/O5zTdrZsRWVpmenElEAT" alt="" width="333"><figcaption><p>Inactivity</p></figcaption></figure> <figure><img src="/files/7yPUOU1O5IGUZufWhSj4" alt="" width="333"><figcaption><p>Winding up and down</p></figcaption></figure></div>

* **Inactivity:** The effort column shows the aggregate amount of FTE during the selected timeframe, while the trend column shows if there have been inactive months. This can surface a lack of focus in key initiatives.
* **Winding up vs. winding down:** The shape of the trend breakdown can also tell you whether a project is starting or ending. Generally, in cross-team initiatives, effort tends to be highest when multiple teams are contributing at the same time, and towards the end, most teams have already moved on to other projects.

How you interpret these patterns depends on how your development organization works and what initiatives you are tracking.

* An expanding scope mid-project might be cause for concern if your organization works more in a waterfall-like model, where work tends to be defined before it starts.
* If you are tracking a strategically important initiative, months with lower-than-expected or no effort may be a particularly important signal.

Remember, you can use filters to surface these patterns in not just the whole organization but also individual teams. Filtering to a single team will change the completed and effort columns to just the work items owned by that team. This allows you to easily tell how a single team moves from one initiative to another over time.

### Initiative view

The detailed initiative view is used to inspect the initiative's progress, identify potential bottlenecks, showcase contributors, and display the planned work to be started. Below are some things that can be inspected from the view.

#### See how your teams contribute to the initiative

<figure><img src="/files/aGxorL1M4orTlYgnYwUS" alt=""><figcaption></figcaption></figure>

The teams tab displays each team's contribution to the initiative. The table lists all teams that own issues within the initiative, showing:

* Issue-based progress relative to their scope
* The effort they contribute
* The trend of that effort over the selected timeframe

Click any team name to view the activity timeline filtered to that specific team.

#### Analyzing patterns in the activity timeline

The activity tab helps you understand the work within the initiative, including when issues were worked on and their sequence.

<div data-full-width="false"><figure><img src="/files/Nxl4R7H0lYYsMqJKs2g8" alt=""><figcaption></figcaption></figure></div>

Each dot in the activity timeline represents the volume of activity on a particular day or week. One of the best indicators of a stuck or blocked initiative is long periods of inactivity. When you spot long periods of inactivity, you can investigate further why work might be blocked. It’s possible to expand individual rows in the timeline to drill deeper into specific issues. You can also click on each dot on the timeline to see all contributions that happened on that day or week as a list. This way, you can pinpoint specific issues and unblock the work.

<figure><img src="/files/NUlD6ke0Fz0MAkbWT5OG" alt="Swarmia - Initiative work explorer" width="494"><figcaption></figcaption></figure>

The mismatch between the planned completion date and the unstarted work and inactivity. An initiative might contain subtasks that are idle and have not had steady activity lately or the initial plan has been too ambitious.

<div align="center"><figure><img src="/files/Wz3oaSJnLH709hz3PKfo" alt="Swarmia - Initiative activities tooltip" width="315"><figcaption><p>From the activity tooltip, you can see the ratio of done work for the time period<br></p></figcaption></figure></div>

Drill down to individual issues and inspect their progress

<figure><img src="/files/8iHtkbB9jbdpp1VDBv8Y" alt=""><figcaption></figcaption></figure>

The data in this view can be used to gain insights into the work being done towards an initiative. If your initiative seems to be at risk of getting stuck, you can start conversations with your team to make steady progress.

### Initiative status

Initiative status is determined by the status of its first-level issues. If all first-level issues have not been started, the initiative is considered not started. If all first-level child issues within an initiative are marked as done, the initiative is considered completed.


# Work log

Work log visualizes the various activities of your team. Knowing which work patterns to avoid and which to aim for helps teams improve their health and development speed.

## Overview

The work log helps you understand what your teams are actually working on day to day. Each dot represents a developer activity (a commit, pull request, review, or issue completion), giving you a more holistic picture of work in progress than your issue tracker alone can provide.

## How it works

<figure><img src="/files/85Z9UZM4oTYNoLWsmudR" alt="Swarmia - Controls in work log" width="563"><figcaption></figcaption></figure>

The controls at the top of the work log page give you flexibility in how you want to group the activity on the work log. The way you group your work will affect what you see on the left side, including the rows and which work activities are grouped on each row. In this example, we are grouping work by Issues and more specifically by epics. This is why we see all of the epics that had some linked activity during the visible time period.

The controls at the bottom let you select which type of activity to display in the work log. In the screenshot above, we have selected to view commits, pull requests, and issue completions.

With epics selected as the grouping and commits, pull requests, and issue completions selected as the visible activity, we are grouping all the work linked to any epic. For Jira issues, this means child issues; for pull requests and commits, it means a direct link to the epic or to any child issue in the issue hierarchy. In practice, a pull request with a link to a Jira task linked to a story, which is again linked to an epic, will be shown as linked to that epic in the work log when grouped by epics.

Activities that we are unable to link to any issue of the selected issue type will still be visible in their own rows on the work log.

The "Other Issues" row shows all activity linked to other issues owned by the team, but we are not grouping it by work log. For example, when grouping by epics, if the team has worked on a standalone task that is not linked to any epic, it will be shown under the "Other Issues" row.

<figure><img src="/files/IQcf1kT5uSTjnxP4AfY5" alt="Swarmia - Other issues in work log" width="563"><figcaption></figcaption></figure>

The "Bugs" row shows all activity linked to the issue type bug. Work related to bugs is separated into its own row, since most teams want to pay special attention to how much work is tied to the bugs they have.

<figure><img src="/files/vw4rwOl8tIy0XK9GQwpp" alt="Swarmia - Bugs in work log" width="563"><figcaption></figcaption></figure>

Finally, the "Everything else" row shows all the activity we cannot group into any of the rows above it. This can include unlinked commits and pull requests, as well as activity linked to Jira issues owned by other teams than the team we are looking at. The "Everything else" row is meant to highlight the more reactive work that might not be reflected in the team's issue tracker. This is why the work log can give you a more holistic picture of your work in progress compared to your issue tracker.

<figure><img src="/files/0dl2wBFgJnuZxQW5MSnS" alt="Swarmia - Everything else in work log" width="563"><figcaption></figcaption></figure>

## Unhealthy patterns

### **Working alone**

People tend to gravitate to working on their own things because it's easy and doesn't involve coordinating with others. However, great teams are built upon collaboration and sharing knowledge.

Look for epics, stories, or tasks where you can only see one contributor. Could they use a hand?

Being able to work on the same feature sets the bar higher for planning because you can't figure things out as you go. This is generally a good thing: better planning reduces wasteful rework, but it can feel painful at first.

<figure><img src="/files/rEw0d81CPUaxdjW67PKz" alt="Swarmia - Working alone in work log"><figcaption></figcaption></figure>

### **Siloed work**

Another form of siloing is when some people always gravitate to working together on the same features or when someone is stuck only fixing bugs or reviewing code.

Look for patterns in which individual contributors are only working on one kind of thing. In the example below, the bottom contributor is mainly reviewing code instead of a balanced mix of commits, pull requests, and reviews.

<figure><img src="/files/TenwGXmb6CQJMY2g2rT0" alt="Swarmia - Different activities in work log"><figcaption></figcaption></figure>

{% hint style="info" %}
Work log can also show you whether the author was on leave, if you have your [HR system connected](/settings/integrations/hr-systems) or you've [imported time off data](/settings/integrations/hr-systems/upload-time-off-data-via-csv).
{% endhint %}

### **Too much reactive work**

Housekeeping work is important to ensure the team's capability to deliver on roadmap work. But if priorities and focus are unclear, or the team is fighting fires, it can be easy to get lost in the weeds of ad hoc work.

If the work log is bottom-heavy with lots of reactive work (eg. bugs and tasks), try to correct the course by focusing more on high-impact stories and epics.

Is there a lot of bug-fixing work, and work that's not linked to any issues?

<figure><img src="/files/ZVBjmQQ0atlQp28JjU0d" alt="Swarmia - Not linked issues in work log"><figcaption></figcaption></figure>

### **Multitasking and days without progress**

We're encouraged to stop starting and start finishing, but something urgent always comes up. Even short disruptions can impair flow, and context switching is expensive.

Is the team getting interrupted or working on too many things at the same time? Or has the team a habit of creating larger commits and Pull Requests?

<figure><img src="/files/M61o8xq7TzPPVMhOTMOW" alt="Swarmia - Inactive days in work log"><figcaption></figcaption></figure>

## Healthy patterns

### **Team collaboration**

Issues that the team collaborates on are more likely to be completed faster and are usually more fun to work on due to social interaction, knowledge sharing, and quicker reviews.

Look for stories with a high amount of collaborators, and continuous delivery (commits happening regularly every day).

Plan for collaboration (eg. when breaking work into tasks) to increase the odds of collaboration.

<figure><img src="/files/PkKxrqWegxfBNkAyvwy6" alt="Swarmia - Good work habits in work log"><figcaption></figcaption></figure>

### **Increasing focus on the biggest priorities**

Limiting the amount of work is another way to increase team collaboration, and complete batches of work faster. This helps drive focus which ensures the team can progress in their most important priorities.

Again, ensure the stories get continuous progress and little to no empty days. Additionally, look for a step pattern. If there is one, the team transitions well between stories and takes the time to finish work before jumping on to the next topic.

<figure><img src="/files/HjUGNCitMS3Ejfs3OeUc" alt="Swarmia - Good focus in work log"><figcaption></figcaption></figure>


# Sprints

Swarmia tracks the issues linked to your sprints and helps you visualize scope increase and carryover.

{% hint style="info" %}
Sprint is currently in beta and supported only with Jira Cloud. Support for Linear Cycles and Jira On-Premises will be added in the future.
{% endhint %}

<div data-full-width="false"><figure><img src="/files/0X5G1dFRNT2R9UFxNzbA" alt=""><figcaption></figcaption></figure></div>

## Overview

Measure the amount of work added at the start of a sprint, including tasks that are carried over from past sprints or have extended beyond two sprints.

Select the individual sprint to view a complete timeline of related issue activity and coding contributions. In this sprint overview, you can also identify issues that are part of the sprint scope but have no activity, as well as those that were removed during the sprint.

These indicators demonstrate the effectiveness of your planning for current and previous sprints, helping you enhance future planning and recognize tasks that need to be carried over.

<figure><img src="/files/YFWrd50OlLuL8TUiHpDt" alt=""><figcaption></figcaption></figure>

## Using sprints

### Scope grouping

For each sprint, the graph displays two parallel stacked bars: the left bar shows the scope (all work assigned to the sprint), and the right bar shows the completed work. Both bars are broken down by the following categories.

* **Planned:** Issues added before the sprint started.
* **Scope increase:** Issues added after the sprint started. Removing an issue and re-adding it also counts as a scope increase.
* **Carryover:** Issues carried over from the immediately previous sprint.
* **Carryover (2+ sprints):** Issues carried over from two or more consecutive previous sprints.
* **Removed from scope:** Issues removed from the sprint and never added back. *(Hidden by default.)*

{% hint style="info" %}
**What is a consecutive sprint?**

In Swarmia, consecutive sprints are those that occur **within 5 days of** each other.

For example, we have 3 sprints.

Sprint 1 — March 1 - March 14

Sprint 2 — March 15 - March 29

Sprint 3 — April 1 - April 14

If issues are once in *Sprint 1*, and then removed, and re-added in *Sprint 3*, these are not counted as Carry Over because when the issue is added into *Sprint 3*, the previous issue sprint is *Sprint 1*. Thus, *Sprint 3* and *Sprint 1* are not consecutive sprints

From that, depending on when it is added to Sprint 3, the issue will either be planned or a scope increase.
{% endhint %}

### Sprint drill down

The new drill-down makes it easy to inspect what happened in each sprint. You can filter to see planned issues, scope increases, and carryovers separately. Issues removed from the sprint are shown in their own section, giving you the full picture of sprint changes.

Click any sprint in the chart to see all its issues with story points

### Story points

You can switch to Issues or Story Points mode when your story points are available; otherwise, we will default to issue count. You can also see the Story Points of each issue in the sprint drill-down popup or when you click to view the sprint details as well.

### Investment balance for sprints

Swarmia provides an investment breakdown of issues within each sprint, helping you identify patterns in your work. For example, you might notice that KTLO (keeping the lights on) work is consuming an increasing share of your capacity, or verify that you're meeting goals, such as dedicating over 70% of your effort to building new features.

<figure><img src="/files/5HJoUhqviOZ7vyIQFzBW" alt=""><figcaption></figcaption></figure>

The balance in sprints uses your primary investment balance breakdown. You can view the breakdown in either story points or issues.

#### Balance in the sprint list view

* For completed or in-progress sprints: shows the balance of completed issues
* For planned sprints: shows the balance of all issues in the sprint

#### Balance in the sprint detail view

When you drill into a specific sprint, you can view the investment balance for both all issues and completed issues. This comparison helps you spot patterns, such as whether your team tends to complete certain types of work more consistently than others.

### Where to find it

You can find Sprint in [app.swarmia.com/sprints](https://app.swarmia.com/sprints), and if you haven't set up the sprint for your team yet, please check out the [Sprint configuration](/settings/team/sprints) setup guide.


# Metrics


# Code metrics

### About

Code metrics help you understand how work moves through your development process, from the first commit to merge and beyond. They highlight how long work takes, where it gets stuck, and how quickly feedback is given. Use these insights to improve flow, reduce delays, and ship smaller changes more frequently.

### Why does it matter?

Code metrics help teams:

* Identify bottlenecks in development, review, or merge stages
* Improve feedback loops and collaboration
* Reduce risk by shipping smaller changes more often
* Separate development speed from deployment delays

If you’re looking to improve delivery performance, start with pull request cycle time and review metrics, then expand into deployment metrics like change lead time.

## Understanding the Code Metrics Page

The Code Metrics page in Swarmia provides a comprehensive view of your team's development process, helping you identify bottlenecks and foster a culture of continuous improvement. This page is designed to provide insights into key aspects of your coding lifecycle, from batch size to review processes. Use these metrics to understand your process and drive meaningful improvements. Focus on trends over time rather than isolated data points to get a true sense of your team's health and progress.

**1. Overview**

The Overview tab provides a high-level summary of your team's key pull request metrics. It also includes a team comparison table where you can see how your team's performance on metrics like Cycle Time and Batch size compares to other teams in the organization.

* Use Case: Use this view to get a quick pulse check on your team's health and to identify areas that might need a deeper look. The team comparison table is especially useful for spotting outliers and understanding your team's performance in the broader organizational context.
* Pro Tip: When using the comparison table, sort by different metrics to find teams that are excelling and could share best practices. Using percentiles like p90 instead of averages may give you a more realistic view, as averages can be skewed by a few unusually long-running pull requests.

**2. Trends**

The Trends tab is your primary tool for visualizing how your team's metrics evolve over time. You can track metrics like Cycle Time, Throughput, and Batch Size to see if your process is improving.

* Use Case: Use this view to spot spikes or dips in performance. For example, a sudden increase in Cycle Time might indicate a new bottleneck in the review process or an issue with the CI/CD pipeline.
* Pro Tip: Don't just look at the last week. Expand the timeframe to a quarter or even a year to identify long-term patterns or measure the impact of process changes you've implemented.

**3. Cycle Time**

This tab offers a visualization to the Cycle Time of your pull requests—the time from first commit to merge.

* Use Case: This view helps you to understand how the cycle times are divided among PRs, and see if there’s some outliers that may skew the average.
* Pro Tip: Use the detailed list of pull requests in this view to investigate anomalies. Click into a PR with an exceptionally long cycle time to understand the context, read the comments, and see what caused the delay.

**4. Review**

The Review tab focuses on the health and efficiency of your code review process. It visualizes metrics like Time to First Review and the number of comments per pull request.

* Use Case: This tab helps you answer questions like, "Are pull requests waiting a long time for a first review?" or "Are our reviews becoming more or less thorough over time?"
* Pro Tip: Look for patterns of long review times on certain days or for certain types of pull requests. This can help you organize your team's workflow better, for example, by setting aside dedicated time for reviews.

**5. Batch Size**

This tab analyzes the size of your pull requests, measured in lines of code changed. Smaller batches are generally preferred as they are easier to review, test, and merge, leading to a faster flow of value.

* Use Case: A wide distribution in batch size might indicate that there isn't a shared understanding of what a "small" pull request looks like. Use this view to have a conversation with your team and establish working agreements on PR size.
* Pro Tip: Filter this view to see if larger pull requests correlate with longer cycle times. This data can provide a compelling case for encouraging smaller, more frequent commits.

**6. Codebase**

The Codebase tab shows you which parts of your codebase are changing and how frequently. It aggregates file changes from pull requests into a tree structure, showing metrics like the number of PRs, lines changed, and contributors for each part of your code.

* Use Case: Use this view to identify "hotspots" in your code—areas that are frequently modified and might be candidates for refactoring. You can also see which teams are contributing to which parts of the codebase.
* Pro Tip: Combine this view with filters to answer specific questions, such as, "Which files have been most frequently edited by AI coding assistants this quarter?" or "Who has contributed to this legacy module recently?".

### How to use code metrics?

Code metrics in Swarmia focus on pull request–based measurements.

#### Pull request cycle time

Pull request cycle time measures how long a pull request takes from the first commit to merge.

In Swarmia, pull request cycle time is the sum of these three components:

* Time in progress — from the first commit or from when the pull request is opened, whichever happens first, to the first review request.
* Time in review — from the first review request (or from when the pull request was opened, if none) to the final approval.
* Time to merge — from the final approval to once the pull request is merged.

You can:

* View aggregate cycle time across pull requests
* Drill down into individual pull requests to understand delays
* Use Pull request insights and overview to identify slow or aging PRs

<figure><img src="/files/oq3RdtLUfKxXP2m28Pjg" alt=""><figcaption></figcaption></figure>

#### Review metrics

Swarmia includes metrics to understand how quickly pull requests are reviewed.

Time to first review

* Measures how long it takes to receive the first review after a review is requested
* Indicates how quickly new work gets picked up

Review time

* Measures how long each individual review takes

You can:

* View time to first review in Code overview, Trends, and Review
* Explore review timelines in the Review view
* Analyze review performance across pull requests

![](https://help.swarmia.com/~gitbook/image?url=https%3A%2F%2F2772466312-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMa8uBmGhQgR7MTPq9yh7%252Fuploads%252Fgit-blob-5c73dde98add8946d494b7ed2a50873b77a4ff38%252Fimage.png%3Falt%3Dmedia\&width=768\&dpr=3\&quality=100\&sign=4ccd704b\&sv=2)

#### Change lead time

Change lead time extends cycle time to include deployment.

* Pull request cycle time: First commit → merge
* Change lead time: First commit → deployment

Use both metrics together:

* Cycle time shows development and review efficiency
* Change lead time shows end-to-end delivery speed

![](https://help.swarmia.com/~gitbook/image?url=https%3A%2F%2F2772466312-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMa8uBmGhQgR7MTPq9yh7%252Fuploads%252Fgit-blob-bf7dc1fcf8586dadff076394d860b2e0d2fb2877%252Fimage.png%3Falt%3Dmedia\&width=768\&dpr=3\&quality=100\&sign=1f1971c\&sv=2)

#### How are draft PRs considered in cycle time? <a href="#how-are-draft-prs-considered-in-cycle-time" id="how-are-draft-prs-considered-in-cycle-time"></a>

We consider all PRs the same, regardless of the draft state. Since PR cycle time starts from the first commit (or PR open, whichever happens first), the total cycle time is the same, regardless of whether you open a PR as a draft early or ready to review later.

In other words, we consider the draft status by default to be part of the in-progress time. Our definition is based on the assumption that draft pull requests are used as an early indication of work in progress or to gather feedback before review. We try to catch as much of the in-progress time for pull requests as possible.

If you want to exclude draft PRs from Swarmia until they are ready to review, you can set a "Draft status is Draft" [exclusion rule](https://help.swarmia.com/settings/organization/pull-request-data-quality). This can be useful, for example, if you create proof-of-concept draft PRs with no intention to merge or close them. Another option would be to create a dedicated PR label for this and use it in the exclusion rule.

![](https://help.swarmia.com/~gitbook/image?url=https%3A%2F%2F2772466312-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMa8uBmGhQgR7MTPq9yh7%252Fuploads%252Fgit-blob-056a79ea2f0e8a67089d152c85f7cd921e55894d%252Fdraft-filter.png%3Falt%3Dmedia\&width=768\&dpr=3\&quality=100\&sign=94e0a909\&sv=2)

### What does good look like?

#### Pull request cycle time benchmarks

* Great: < 24 hours
* Good: < 5 working days
* Needs attention: ≥ 5 working days

### How can we take action?

To improve code metrics, focus on flow and feedback loops.

#### Reduce cycle time

* Limit work in progress (avoid too many open pull requests)
* Split work into smaller pull requests
* Prioritize reviews and merges
* Define clear ownership for moving pull requests forward

#### Improve review responsiveness

* Ensure new pull requests are picked up quickly
* Reduce delays in starting reviews
* Identify and address slow or outlier reviews

#### Use Swarmia to support improvements

* Clean up old or stale pull requests
* Exclude outliers to focus on current work
* Set working agreements (e.g. max PR age, WIP limits)
* Use daily digests to stay aware of aging pull requests
* Review pull request insights regularly as a team

### Where does the data come from?

Code metrics are based on pull request and review events, including:

* Commits
* Pull request creation
* Review requests and submissions
* Approvals and merges

Change lead time additionally requires deployment data.

Only pull requests linked to applications with deployments configured are included in change lead time.

### Metric definitions

Pull request cycle time\
\= Time in progress + Time in review + Time to merge

Time to first review\
\= Review request → first review submission

Review time\
\= Review request → individual review completion

Change lead time\
\= First commit → deployment

<br>

<figure><img src="https://help.swarmia.com/~gitbook/image?url=https%3A%2F%2F2772466312-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMa8uBmGhQgR7MTPq9yh7%252Fuploads%252Fgit-blob-c493dd694a303df231ca24f0431a24bc4819b70f%252Fimage.png%3Falt%3Dmedia&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=1bb125c2&#x26;sv=2" alt=""><figcaption></figcaption></figure>

### Something looks wrong

Common reasons:

* Very old pull requests skewing averages
* Draft PRs included when they shouldn’t be
* Proof-of-concept or abandoned PRs included
* PRs merged without formal approval → review time measured until merge
* Bot reviews not included in aggregates

Possible fixes:

* Exclude outliers
* Add exclusion rules for draft PRs or labels
* Clean up old pull requests


# PR cycle time

Pull request cycle time (or PR cycle time) is the total time a pull request spends in all stages of the development pipeline.

## Definition

In Swarmia, pull request cycle time is the sum of these three components:

* Time in progress — from the first commit or from when the pull request is opened, whichever happens first, to the first review request.
* Time in review — from the first review request (or from when the pull request was opened, if none) to the final approval.
* Time to merge — from the final approval to once the pull request is merged.

<figure><img src="/files/pS0fvnqNyRjMFCtHry73" alt=""><figcaption></figcaption></figure>

## Example

A pull request is opened on a Monday, and then the first review is requested on Wednesday, which equals 2 days in progress.

Then that pull request takes another day for review approval, which equals 1 day in review.

And finally, another full day passes between the final approval and the pull request being merged. That’s a 1-day time to merge.

Together, this equals a pull request cycle time of 4 days.

The average PR cycle time for a given time period would be the cycle time of all pull requests in that time period, averaged.

## Why it matters

Lower cycle time means:

* Shipping in small batches without interruptions
* Getting feedback from end users faster
* Reducing risk and overhead
* Reviewing and merging new code quickly

## Cycle time benchmarks

* **Great:** < 24 hours
* **Good:** < 5 working days
* **Needs attention:** ≥ 5 working days

Use [code metrics](https://app.swarmia.com/metrics/code) to look into cycle time and other pull request metrics in Swarmia.

## **What contributes to cycle time?**

Let's consider the key factors contributing to cycle time and how you can impact them. Among others, we suggest focusing on the following:

* **Work in progress queue:** Working on too many pull requests at once often correlates with longer delivery times. Use Swarmia's WIP working agreement to agree on a target with the team (e.g., up to 10 pull requests open at once) and keep track of it over time.
* **Time in progress:** Shorter *in-progress time* means focusing on splitting work into smaller batches that are easy to plan, review, and deploy.
* **Time in review:** Creating smaller pull requests that are easy to review, using code owners in GitHub to assign reviewers automatically once a pull request is open, are some ways to lower review time.
* **Pull request size:** Smaller pull requests are easier to plan, review, and deploy.
* **Time to merge:** Making approved pull requests a priority, agreeing on merge rituals with the team (Who has the responsibility to drive the pull request forward? Who can merge code?), and investing in production infrastructure helps to reduce waiting time between approval and merge.

## Lowering cycle time with Swarmia

### **Start with a clean-up**

If measuring cycle time wasn't ever a priority, there are likely some very old pull requests waiting to be closed. Use the [Pull Request overview](https://app.swarmia.com/pull-requests/) to identify old pull requests and decide what to do with them.

To get a more relevant view of your data, [exclude outlier pull requests](/settings/organization/pull-request-data-quality) from all metrics. This lets you focus on lowering cycle time for newly opened pull requests.

### **Adopt a working agreement**

Once you've identified cycle time as an improvement area, look at the Pull Request insights together with the team:

* Decide what a realistic maximum target is (7 to 14 days is a good starting point).
* Adopt a [pull request max age working agreement](https://app.swarmia.com/working-agreements/explore/max-pull-request-age) and set it to what you just decided.
* To address specific issues contributing to cycle time, consider adopting a [work-in-progress target](https://app.swarmia.com/working-agreements/explore/wip-pull-requests) and an agreement measuring [review time](https://app.swarmia.com/working-agreements/explore/max-pull-request-review-time) specifically

### **Build a feedback loop**

Enable [Swarmia's daily digest](/settings/team/team-notifications) in Slack or Microsoft Teams to get a daily reminder about pull requests not adhering to the agreement. Check the [Pull Request overview](https://app.swarmia.com/pull-requests/our-team) regularly with the team to spot emerging coding patterns early and close pull requests before they get old and stale.

## Frequently asked questions

### How are draft PRs considered in cycle time?

We consider all PRs the same, regardless of the draft state. Since PR cycle time starts from the first commit (or PR open, whichever happens first), the total cycle time is the same, regardless of whether you open a PR as a draft early or ready to review later.

In other words, we consider the draft status by default to be part of the in-progress time. Our definition is based on the assumption that draft pull requests are used as an early indication of work in progress or to gather feedback before review. We try to catch as much of the in-progress time for pull requests as possible.

If you want to exclude draft PRs from Swarmia until they are ready to review, you can set a "Draft status is Draft" [exclusion rule](/settings/organization/pull-request-data-quality). This can be useful, for example, if you create proof-of-concept draft PRs with no intention to merge or close them. Another option would be to create a dedicated PR label for this and use it in the exclusion rule.

<figure><img src="/files/qhQ83zvTKBM62fw18rOE" alt=""><figcaption></figcaption></figure>


# Time to review

Learn how Swarmia calculates pull request review metrics, including time to first review and review time.

Getting a clear view into pull request reviews is one of the key elements of improving both code quality and flow. This page explains how Swarmia measures review time and what you can do to influence it.

There are a few different metrics in Swarmia that account for pull request review time. We recommend starting with **time to first review**, since it’s the easiest to compare across situations and provides a good indicator of your team’s review practices.

### Time to first review

<figure><img src="/files/GF4DzxpjeTkjXsBBtAq4" alt=""><figcaption></figcaption></figure>

*Time to first review* measures the time from when a pull request review is first requested until the first review is submitted (whether it’s an approval or request for changes).

This metric shows how long a PR author waits before receiving any feedback. It’s intended to reflect the team’s responsiveness to new PRs and serves as a proxy for how quickly work is picked up for review.

In Swarmia, *time to first review* can be found on the [Code overview](https://app.swarmia.com/insights/code/overview) page and under [Metrics](https://app.swarmia.com/metrics). Learn more about how to streamline your code review process and [Review code faster](/guides/improve-pull-request-flow/review-code-faster).

{% hint style="info" %}
☝️ In some cases, a review may be requested but never formally approved before merge (for example, when approval is given informally in comments). In these situations, review time is measured from the review request until the merge.
{% endhint %}

{% hint style="info" %}
🤖 Reviews completed by bots are excluded from the aggregate *Time to first review* metric.
{% endhint %}

### Review time

*Review time* measures how long it takes to get each review—from the moment it’s requested until it’s received.

This metric helps you spot outliers, such as reviews that take much longer than others—especially when several reviews are required per pull request.

Individual pull request reviews can be viewed on [Code review](https://app.swarmia.com/insights/code/reviews) page, where you can also distinguish between reviews from your team and reviews assigned to other teams.

By selecting a pull request, you can see its review time in the context of cycle time and explore the full timeline in more detail. You can see this data as an aggregate on the [Pull requests](https://app.swarmia.com/pull-requests/our-team) page.

<figure><img src="/files/WFc7APKOD3P7mjr66WjT" alt=""><figcaption></figcaption></figure>


# What's the difference between "Change lead time" and "Pull request cycle time" metrics in Swarmia?

Change lead time includes the full lifecycle of the pull request from the first commit to deployment. Pull request cycle time includes only the time from the first commit to pull request merge, but excludes the last part of the lifecycle, time to deploy.

<figure><img src="/files/36lH3viZC2qOCvyOyTGL" alt=""><figcaption></figcaption></figure>

Despite being related, it makes the most sense to look at pull request cycle time and deployment metrics like change lead time separately. Slow time to deploy might mask the improvements you're making in the rest of your development process.

Using two separate metrics also ensures that missing lifecycle data does not skew the metrics. Pull request cycle time can be calculated for all pull requests, whereas change lead time is only calculated for pull requests that belong to applications that have [deployments configured](https://help.swarmia.com/configuring-deployments).


# DORA metrics

Analyze deployment frequency and quality across your entire organization in Swarmia.

*How often do you deploy code to production? How many of these production deploys cause unintended defects, as experienced by end-users? How long does it take to fix such defects?*

Swarmia's DORA and deployment insights help you answer these questions and analyze their trends across your organization (learn more from [this blog post](https://www.swarmia.com/blog/dora-metrics/)).

Tracking DORA metrics and their trends per team helps you assess both the frequency and quality of deployments. It provides teams with a tool for lowering their batch size and understanding the impact of their deployments.

{% embed url="<https://youtu.be/D6LmiXhYX2o>" %}

## Getting started

Start by setting up applications and configuring the way Swarmia tracks production deployments.

[**Configuring deployments in Swarmia**](https://help.swarmia.com/configuring-deployments)

## What you can measure

Deployment insights let you both measure your deployments and visualize their trends. Besides looking at the volume of deployments, you can track which deployments had defects. This helps you understand the quality aspect of deployments.

<figure><img src="/files/vsY7QRdmCC13w6gfyIsH" alt=""><figcaption></figcaption></figure>

### **Deployment Frequency**

Deployment frequency is used to indicate the performance of a software development team. Ultimately, deploys to production are what make any work visible all the way to the user – or what makes it possible for your work to deliver a business impact.

According to the authors of Accelerate, “elite” teams are able to deploy new code on-demand or multiple times per day, whereas the release frequency of high-performing teams is between once per day and once per week.

A low deployment frequency can be an indication of working with large batches, or signal other problems such as poor deployment infrastructure or lack of reliable automated tests.

{% content-ref url="/pages/bpeFXPgsCe2ls5xWmC9b" %}
[Deployment frequency](/definitions/dora-metrics/deployment-frequency)
{% endcontent-ref %}

### **Change Lead Time**

Measures the time it takes for pull requests to go from the first commit to a production deployment. Helps you identify wait times and bottlenecks in your development process.

According to Accelerate, “elite” teams can go from a code committed to production in less than an hour, while for high-performing teams, it takes between one day and one week.

High change lead time can indicate too large batch sizes, slow code review/QA, or long CI/CD wait times.

{% content-ref url="/pages/FvRfuV0Iku6IxwzdTop6" %}
[Change lead time](/definitions/dora-metrics/change-lead-time)
{% endcontent-ref %}

### **Time to Deploy**

Measures the time it takes from pull request merge to deployment. Part of change lead time.

This is useful for understanding, how much delay your current deployment process is causing in your deployment process.

{% content-ref url="/pages/0PrJvy03uqD1xqlxGW4F" %}
[Time to deploy](/definitions/dora-metrics/time-to-deploy)
{% endcontent-ref %}

### **Change Failure Rate**

The exact definition of a *change failure* is up to you. As a rule of thumb, it should be an incident that must be remedied immediately instead of waiting until the next regular deployment. If a deployment introduces a bug that doesn't need an immediate reaction, it probably shouldn't be defined as a change failure.

Swarmia uses deployments as the basis for change failures. Deploys that fix other deploys (eg. a patch, hotfix, rollback, forward fix) mark the original deploy as failure.

We look at the number of such failed deployments and calculate the Change Failure Rate by comparing this to the number of total deployments.

You can use the [**Deployments API**](https://help.swarmia.com/sending-deployment-information-to-swarmia) to mark a deployment as a fix for an earlier deployment. In addition to this, you can navigate to [**Deployments**](https://app.swarmia.com/infrastructure/deployments) and mark a deployment as fix manually.

{% content-ref url="/pages/D3aASdimBY7udpK7gMut" %}
[Change failure rate](/definitions/dora-metrics/change-failure-rate)
{% endcontent-ref %}

### **Mean Time To Recovery**

Mean Time To Recovery (MTTR) is the average time it takes to address change failures. It helps teams understand how quickly they're able to resolve issues.

Time To Recovery (TTR) can be determined for each failure as the time between the original deploy, and the fix for the problem. TTR can be used to understand the impact of each change failure (how long did the problem last, and what was its impact to the customer).

{% content-ref url="/pages/7P4VWbW9xYYfIksv64VE" %}
[Mean time to recovery](/definitions/dora-metrics/mean-time-to-recovery)
{% endcontent-ref %}

## How deployments are attributed to teams

The *Authors* column in the [**Deployments**](https://app.swarmia.com/infrastructure/deployments) table lists the authors of the [pull requests in each deployment](/features/metrics/track-dora-metrics/how-swarmia-links-prs-to-deployments). The *Team* and *Author* filters on the page are based on the authors. These are then aggregated to calculate DORA metrics per team in [Metrics / DORA](https://app.swarmia.com/metrics/dora). This lets you see DORA metrics for every team in your organization.

Note that one deployment can be linked to multiple teams if it has multiple pull requests or an author who belongs to multiple teams.

{% hint style="info" %}
A team's DORA metrics are calculated based on all the deployments that include the team's PRs. If those deployments contain PRs from other teams, that can skew your team's [change lead time](/definitions/dora-metrics/change-lead-time).
{% endhint %}

### About deployments and change failures

We define a **deployment as any change that was applied to your production code**. In other words, you should only include deployments that were processed successfully, resulting into some sort of change in your production application. This can also mean deploying a version that was live previously.

{% hint style="info" %}
Swarmia automatically generates deployments for some of your repositories. These applications and production environments can be configured further in [**Settings / Deployments**](https://app.swarmia.com/settings/deployments).
{% endhint %}

**Change failures are deployments that have defects that somehow impact the user of your production application**. Some typical examples are regressions, downgraded performance, or other types of bugs that impact the user.

There's no one definition for failures, but we offer some guidelines. The purpose of measuring failures is to understand when a team is moving too fast, to act as a feedback signal to slow down. You want to proxy the impact to users, so focus on production changes that are affect them.

To capture change failures, Swarmia forms links between deployment events to understand when a deployment is seeking to fix a previous production deployment. These targeted deployments will be considered failures.

### **Automating change failures**

Swarmia can [**automatically detect change failures**](https://help.swarmia.com/automatic-change-failure-detection) from rollbacks or reverted pull requests. This is enabled by default for new applications and is the easiest way to get started.

In addition, you can use the [**Deployments API**](https://help.swarmia.com/sending-deployment-information-to-swarmia) to mark a deployment as a fix for an earlier deployment. By integrating it into e.g. your forward-fixing process, you can maximize the quality of change failure data and get reliable insights on the quality of your engineering process.

### **Manually indicating change failures**

Alternatively, you can mark a deployment as a fix manually in [Deployments](https://app.swarmia.com/metrics/deployments). We fetch previous deploys for quick access, or you can find deployments from the past 90 days by searching with the version.

<figure><img src="/files/fhq8cdJguJ6zURhQxLbl" alt=""><figcaption></figcaption></figure>


# Automatic change failure detection

Automatically detect DORA change failures from application version rollback, pull request reverts, and advanced hotfix filters.

## About automatic change failure detection

When enabled, Swarmia automatically looks into every created deployment to see if it includes fixes to a previous change. When a fix is detected, Swarmia automatically records a change failure for the deployment that shipped the failing change to production.

Automatic change failure detection supports identifying [version rollbacks](#rollback-detection), [pull request reverts](#pull-request-revert-detection), and [advanced hotfix filters](#advanced-hotfix-detection-options).

Automatic change failure detection works with all available deployment sources.

## Enabling automatic change failure detection

Automatic change failure detection is enabled by default for all new applications.

You can enable or disable automatic change failure detection by navigating to your application in [**Settings / Deployments**](https://app.swarmia.com/settings/deployments) and toggling the "Automatically detect rollbacks, reverts and hotfixes" checkbox.

<figure><img src="/files/72TvNfcOfAliCDiFxl0J" alt=""><figcaption></figcaption></figure>

## Rollback detection

Rollback detection checks if the exact same version has been previously deployed to the same environment (e.g. production).

If Swarmia detects a rollback, a change failure is recorded to the first deployment after the deployment you rolled back to.

<figure><img src="/files/vw5d2Ov2Rwila17sQjEt" alt="" width="431"><figcaption></figcaption></figure>

## Pull request revert detection

To detect reverts, Swarmia checks if any of the pull requests included in your deployment were reverting a previously deployed pull request.

Swarmia first looks into all merge commit messages in the base branch to find a merge commit for a pull request that was reverted through the GitHub UI.

If none is found, we check pull request branch names (format: `revert-`*`PULL_REQUEST_NUMBER`*`-`) and descriptions (format: `Reverts #`*`PULL_REQUEST_NUMBER`*) for reverted pull request numbers.

If we find a reverted pull request, we record a change failure for the deployment where the pull request was deployed.

{% hint style="info" %}
**For applications using the Deployment API**, the payload you send must include commit and repository information. This data is automatically included if you have been using the examples from our latest [documentation](https://help.swarmia.com/sending-deployment-information-to-swarmia).
{% endhint %}

## Advanced hotfix detection options

Swarmia supports two additional methods for hotfix detection, used to calculate change failure metrics and available in [Settings/Deployments](https://app.swarmia.com/settings/deployments/).

### **Pull request filters**

You can identify change failures based on deployments linked to specific PRs using criteria like *pull request title* or *branch name*. Matching PR deployments will be considered fixes, marking the preceding deployment as a failure.

### **Issue filters**

Similarly, it's possible to detect change failures in deployments linked to specific issues in your issue tracker using criteria such as *issue title*, *label*, or *custom field*. Matching deployments will be considered fixes, marking the preceding deployment as a failure.

<figure><img src="/files/4ZHAABobiv3du4t8K5Zf" alt=""><figcaption></figcaption></figure>

## Limitations

* Automatic change failure detection only looks into the first 1000 commits per deployment. If your deployment includes more commits, those are not checked.
* We record a single change failure per deployment. If your deployment includes fixes for multiple change failures, only one of them will be marked as failed.


# How Swarmia links PRs to deployments

Linked PRs are used to calculate change lead time and time to deploy. The are also used to determine who owns the deployment.

A [deployment](/settings/organization/configuring-deployments-in-swarmia) can include one or more pull requests. These are used for two main purposes:

1. **Calculating the** [**Change lead time**](/definitions/dora-metrics/change-lead-time) **and the** [**Time to deploy**](/definitions/dora-metrics/time-to-deploy) **metrics.** If a deployment has no associated pull request, these two metrics will be unavailable.
2. **Defining a deployment's ownership.** Deployments are [attributed based on the authors of the PRs in the deployment](/features/metrics/track-dora-metrics#how-deployments-are-attributed-to-teams). A deployment without pull requests won't appear in any team's DORA metrics (but will be counted on the organization level).
3. **Adding better visibility into your deployments.** You can dig deeper into each deployment to see which changes (pull requests and the associated issues) were deployed to which environment and when.

## How PRs are automatically linked to deployments

When Swarmia receives a new deployment, we perform an automatic pull request detection for it. The PRs linked to a deployment are determined from the list of **merge commits** that occurred between the new deployment and the immediate previous deployment on the **same application** and **same environment**.

<figure><img src="/files/CANXBLTPsVJ80mZoKU81" alt=""><figcaption><p>Associating pull requests to deployments</p></figcaption></figure>

### What about monorepos?

When using monorepos, we offer additional fields to help track deployments. You can read more here:

{% content-ref url="/pages/wDudV4eMechHLjbWszCH" %}
[Generate deployments for monorepos via the API](/settings/organization/configuring-deployments-in-swarmia/generate-deployments-via-the-deployment-api/generate-deployments-for-monorepos)
{% endcontent-ref %}

The logic to associate pull requests with deployments is quite similar when using the `includedCommitShas` field ([field specification](https://help.swarmia.com/track-dora-metrics/generate-deployments-via-the-deployment-api#sending-a-deployment)) in the deployment payload, except that instead of using the git diff between the current deployment and the previous one, we will use only the commits provided in the payload.


# Issue metrics

Issue metrics help you understand how your engineering teams are delivering work — how fast issues move through your process, how much work is in progress, and how throughput changes over time.

## Overview

The Overview page is a team comparison table. Each row represents one team, and columns show key metrics for the selected timeframe:

* **Completed** — number of issues finished
* **Completed / FTE** — throughput normalized by team size
* [**Cycle time**](/definitions/defining-issue-lifecycle-and-cycle-time) — how long issues take from start to done
* **WIP** — average number of issues in progress at a time
* **FTE / Members** — team size context

Each metric shows a delta indicator comparing the current period to the previous period or the organization's average. Working agreement targets (if configured) are shown as badges next to Cycle Time and WIP.

Use Overview to spot which teams are improving, regressing, or outliers compared to the rest of the organization.

## Trends

The Trends page shows how metrics evolve over time for a single selected team. Metrics are plotted as bar or line charts in a grid:

* **Cycle time** — trend over time with previous-period comparison
* **Completed issues** — throughput per time bucket
* **Average WIP** — in-progress count per time bucket
* **Completed / FTE** — throughput per developer (available when time bucket is set to monthly)

You can switch between bar and line chart styles, adjust the time bucket (day/week/month), and change the aggregation function (avg, median, etc.).

Use Trends to understand whether a team's performance is improving, degrading, or seasonal over a longer horizon.

## Flow

The Flow page gives you issue-level detail for a selected team and timeframe. It is structured in three sections:

**Summary stats** at the top show current-period averages for WIP and Cycle Time, with deltas vs. the previous period.

**Two charts** sit below:

* *Issues in Progress* — a line chart showing daily WIP count over the timeframe, with a benchmark line if a WIP limit is set in working agreements
* *Cycle Time Scatter Plot* — one dot per completed issue, plotted by completion date and cycle time; includes a histogram overlay and inline stats (average, median, over-limit count, scope creep average)

The **issue table** at the bottom lists every individual issue, with columns for status, title, labels, linked pull requests, scope creep %, child issue count, and cycle time.

Use Flow to investigate the individual issues behind the aggregate numbers — find outliers, understand scope creep, and trace slow issues to their root cause.


# CI visibility

Swarmia provides you with the most important CI metrics for tracking your CI health

{% hint style="info" %}
Swarmia CI visibility is available for GitHub Actions.
{% endhint %}

## Why it matters

Keeping the CI fast and robust is essential for good developer experience and fast cycle times. As such, it is important to have good visibility into your CI pipeline, which is what Swarmia's CI insights aim to provide you with.

## Where to find it

You can find CI metrics under [Infrastructure → CI visibility](https://app.swarmia.com/infrastructure/ci).

## How to use it

You can start from the top-level view by identifying which of your repositories have the busiest / slowest CI pipelines. Then, you can drill down deeper into the repository and into the individual workflows to analyze the run time trends and which part of the workflow is slow.

When you know what is slowing you down, you can then work to improve the situation.

### **Repositories**

The top-level view offers an overview of your repositories’ CI activities:

* **Total CI run time**: Total time spent on CI runs per repository. *Note*: A high total runtime may indicate many CI runs (e.g., due to frequent pull requests), not necessarily slow CI processes.
* **Workflow run time distribution**: Visual representation of workflow runtimes. Use this to spot repositories with longer-running workflows.

<figure><img src="/files/5s4VfyAR8QyFrAaSjUyq" alt=""><figcaption></figcaption></figure>

### **Workflows**

Click on a repository to view detailed workflow insights.

* **Run time distribution**: Shows how long workflows take to run.
* **Typical run (p90)**: Monitor these trends to detect workflows that are slowing down over time.
* **Failure Rate**: High failure rates in testing or linting workflows are normal—they catch issues. High failure rates in deployment workflows may indicate flaky pipelines needing attention.

<figure><img src="/files/bULBQoWQBXeog8b1AFX5" alt=""><figcaption></figcaption></figure>

### **Jobs**

Within a workflow, click to view its constituent jobs.

* **Jobs**: Details each job within the workflow (e.g., testing, linting).
* **Job run time trends (p90, p75, p50)**: Observe how job runtimes change over time. An upward trend suggests optimization may be needed to prevent slowdowns.

<figure><img src="/files/drI9CHEwGaYlfHLmNxht" alt=""><figcaption></figcaption></figure>

### **Workflow runs**

* **Status**: Filter runs by success or failure.
* **Branches**: Filter runs by branch name. Helpful when the same workflow behaves differently on different branches (e.g., additional deployment steps on the main branch).

Click on a specific workflow run to open it in GitHub Actions. Examine logs and steps to diagnose and troubleshoot issues.

<figure><img src="/files/HUewl02COdZpqGxW3DA8" alt=""><figcaption></figcaption></figure>

## Video walkthrough

See the video below for an in-depth walkthrough of the feature:

{% embed url="<https://youtu.be/aDUyEgUvulY>" %}

## Metric definitions

The metrics provided by the CI visibility view are defined as follows:

### **Total run time**

This metric tells the total amount of time that the CI has spent running across the grouping of the view (repository, workflow, or job). Run time is calculated from the start of the workflow/job run to its end. Both failures and successes are included.

### **Run time percentiles**

On the workflow and job level, we show the p50, p70, and p90 trends of the run time. (p90 = 90% of workflow runs complete below this time.)

### **Run time distribution**

We show the distribution of the run times of the runs in the timeframe. For example, how many workflow runs had a run time between 5 to 10 minutes.

### **Failure rate**

The percentage of runs that failed. Neutral conclusions (such as skipped or canceled) are not considered failures.


# Explore

#### About

The ready made, opinionated Swarmia reports are helpful to understand your organization’s performance or team dynamics, but sometimes you might want to customize what you’re seeing to get all the data you need in one report. Explore lets you do exactly that, whether you need custom filtering, or want to combine multiple metrics from different standard reports into a single, tailored view that serves your needs best, or just want a few key metrics without any extra clutter.

#### Why does it matter?

Explore opens up all Swarmia data to all our customers, so you can build your own custom reports for both recurring reporting needs as well as ad hoc deep dives into issues or situations that need more clarity. It lets you go beyond the opinionated views, and drill down into what is important to your specific needs.

#### How to use Explore?

You can start building your own report in Explore in three different ways:

* Navigate to [Metrics → Explore](https://app.swarmia.com/explore) and use the ready-made templates as a starting point, or simply start with a blank page and build your report using columns and filters.
* Ask Swarmia AI in natural language to build a report for you on the Explore page or through the Chat function across the App, and take the results to the Explore page.

<figure><img src="/files/8v0yxEjFxwwofC635jG2" alt=""><figcaption></figcaption></figure>

* You can open any already existing Swarmia report in Explore by clicking the “Explore” button at the bottom of the page, and edit the report to fit your needs.

<figure><img src="/files/t66Crxq8rc929eALf0uz" alt=""><figcaption></figcaption></figure>

Whichever way you use to get started, you can edit and refine the report with the filters or by asking Swarmia AI to make changes for you, or editing the json at the bottom of the page. Remember to save your custom report if you want to create one for recurring needs. The saved reports will appear as tabs at the top of the Explore page. You can also download your custom reports as a csv.

#### How can we take action?

Are you seeing something in the report you created that raises questions? Use the [Ask Swarmia AI](https://help.swarmia.com/features/swarmia-ai) button on at the bottom of the page to dive deeper into the metrics, or list possible reasons or suggested actions to address the situation.

#### Where does the data come from?

The Explore page uses the exact same data as all the other Swarmia pages. If you’re seeing a mismatch between the ready-made, opinionated views and an Explore report, checking that the aggregate type (for example, is one of the views using P50 and the other average), and time frames match typically solves the issue.

If you used the Swarmia AI to produce the report, the AI will first produce a query that then produces the report. The query the AI produced will always result in the same data to be shown deterministically. You can check the exact query in the “Edit JSON” at the bottom of the page to find out how exactly the report you’re looking at was formulated, and make changes if you wish.


# Key metrics

Key metrics let you pin your most important engineering indicators to the Swarmia front page, so everyone in your organization sees the same shared view of performance every time they log in.

<figure><img src="/files/vtYX7K4lLPLfmTnm7PVD" alt=""><figcaption></figcaption></figure>

## Overview

Improving how your engineering organization works is a long game. Whether you're trying to reduce cycle times, increase throughput, or improve deployment frequency, it helps to keep your north star metrics visible — rather than buried three clicks deep.

Key metrics lets you choose the indicators that matter most to your organization and surface them at the top of the Swarmia home page. Every time someone logs in, they see the same shared view of your company's engineering performance.

<figure><img src="/files/ZzA6NPKXNfr8Sxtv0ldx" alt=""><figcaption></figcaption></figure>

You can also open key metrics in a dedicated view, making it easy to see how your teams compare across the selected metrics.

## Choosing your key metrics

Admins can pick from a curated set of ready-made metrics, including:

* **Throughput:** PRs merged, PRs merged per FTE, stories completed, stories completed per FTE, issues completed, issues completed per FTE
* **Cycle time:** Pull request cycle time, story cycle time, issue cycle time
* **DORA metrics:** Deployment frequency, change lead time, change failure rate, and MTTR
* **Investment balance:** Share of effort spent on any of your investment categories

<figure><img src="/files/JlQ6TUqqfbbtyGp6YPJz" alt=""><figcaption></figcaption></figure>

If none of those fit, you can also define your own key metrics using the same flexible reporting framework as [Explore](/features/metrics/explore). So whether your team cares most about a specific DORA metric, a code health indicator, or something entirely your own, you can surface it here.

## Defaults

You'll see a preselected set of key metrics the next time you log in to Swarmia:

* Average pull request cycle time
* PRs merged
* Stories completed

The default seed applies only to the data sources you've connected — code metrics require GitHub or GitLab, and issue metrics require Jira or Linear.

If you're an admin, you can edit the selection at any time to match what your organization actually cares about.

{% hint style="info" %}
Editing key metrics requires the **Manage key metrics** permission, which is granted to admins by default.
{% endhint %}


# AI tools

Track AI coding tool adoption, activity, impact, and agent usage in Swarmia.

Swarmia's AI tools pages help you connect AI coding tools, track adoption and activity, and understand how AI-assisted work moves through your engineering system.

## Get started

* [Set up AI coding tool integrations](/settings/integrations/ai-coding-tool-integrations) for GitHub Copilot, Cursor, and Claude Code.
* [Understand the impact of AI tools](/guides/understand-the-impact-of-ai-tools) with a practical guide for measuring adoption, productivity, agent usage, and developer sentiment.

## Feature pages

* [AI adoption](/features/ai-tools/ai-adoption): Track licenses, active users, idle seats, and adoption across teams.
* AI activity:
  * [GitHub Copilot activity](/features/ai-tools/github-copilot-activity): Understand Copilot usage across features, models, editors, and programming languages.
  * [Cursor activity](/features/ai-tools/cursor-activity): See how teams use Cursor across tab completions, agent, chat, and cmd+k.
  * [Claude Code activity](/features/ai-tools/claude-code-activity): Track Claude Code usage and action acceptance patterns.
* [AI impact: ROI](/features/ai-tools/ai-impact-roi): Weigh the combined cost of AI tools and engineering time against the stories, pull requests, and code your teams deliver.
* [AI impact: Code](/features/ai-tools/ai-impact-code): Compare how pull requests assisted, created, or reviewed by different AI tools perform across throughput, cycle time, review time, and batch size.
* [AI cost (beta)](/features/ai-tools/ai-cost): Track the token value of your GitHub Copilot, Cursor, and Claude Code usage, and see how it breaks down by team, person, and work.
* [Cloud agents](/features/ai-tools/cloud-agents): Analyze pull requests created by AI agents running in the cloud.
* [Review agents](/features/ai-tools/review-agents): See which AI agents review your pull requests and how much code they cover.
* [AI tool detection & filters](/features/ai-tools/ai-tool-detection-and-filters): Learn how Swarmia detects AI tool usage and how to filter AI-assisted work.


# AI adoption

Track GitHub Copilot, Cursor, and Claude Code licenses and adoption across your teams over time

Available at [AI tools → AI adoption](https://app.swarmia.com/ai/adoption/users-and-licenses)

Track your GitHub Copilot, Cursor, and Claude Code licenses and who is actively using them.

The **Teams** tab compares AI adoption against productivity metrics. Are teams with higher adoption seeing faster pull request cycle times? Are they keeping batch sizes in check? Use the insights to share successful practices from early adopters with teams still getting started.

<figure><img src="/files/CaWNLu2u2eY6vNrGwIQw" alt=""><figcaption></figcaption></figure>

The **Contributors/members** tab shows the AI tool license statuses of your team members:

* **Active:** The contributor has a license and has accepted code or used chat during the selected time period.
* **Idle:** The contributor has a license but hasn't accepted code or used chat during the selected period. These are the seats worth reviewing.
* **—** : The contributor doesn't have a license.

<figure><img src="/files/4r61HAbVZissXharNElb" alt=""><figcaption></figcaption></figure>

Members may have licenses for more than one tool but may not use them regularly. Revoke idle seats to cut costs, and share what's working from early adopters and high-adoption teams with everyone.

Read more in our guide on [understanding the impact of AI tools](/guides/understand-the-impact-of-ai-tools).

For more detailed tool-specific activity metrics, see:

* [GitHub Copilot activity breakdown](/features/ai-tools/github-copilot-activity)
* [Cursor activity breakdown](/features/ai-tools/cursor-activity)
* [Claude Code activity breakdown](/features/ai-tools/claude-code-activity)

## Setup

To enable GitHub Copilot, Cursor, and Claude Code metrics, see our instructions for [AI coding tool integrations](/settings/integrations/ai-coding-tool-integrations).

## Definitions

* **Members** = The number of current team members.
  * **Contributors** = The *Members* column is renamed to *Contributors* when you select the **Active contributors only** checkbox. This filters the whole view to the current team members who have created at least one pull request in the selected time period.
* **AI assistant enabled** = The number of team members with a GitHub Copilot, Cursor, or Claude Code license at some point during the selected time period.
* **Enabled rate** = *AI assistant enabled* / *Members*
* **Weekly active, avg.** = The average number of users who have accepted code or used chat during a calendar week.
* **Active rate, avg.** = *Weekly active, avg.* / *Members*

{% hint style="info" %}
The number of **active GitHub Copilot users before December 12th, 2025,** is based on [GitHub's `last_activity_at` definition](https://docs.github.com/en/copilot/reference/metrics-data#calculation), which includes receiving a code suggestion in an IDE (without necessarily accepting it).
{% endhint %}

## Examples

If you're looking at a team of 5 members and have the "last 14 days" timeframe selected:

* **AI assistant enabled**: If the team has one member who has had a license for the entire last 14 days, one person who terminated their license during that time, and one person who got a license during that time, they're all counted as enabled users, making the total 3. If someone has had a license but terminated it more than 14 days ago, they are not counted.
* **Enabled rate**: 3 / 5 = 60%
* **Weekly active, avg.**: If 3 people were active in the first week and 1 person was active in the second week, that makes the weekly average 2.
* **Active rate, avg.**: 2 / 5 = 40%

## Frequently asked questions

### What happens to historical numbers if the team composition changes?

The *Members* column shows the number of **current** team members, which doesn't consider [historical team memberships](/definitions/frequently-asked-questions/how-do-i-account-for-people-leaving-my-organization).

If people join the team, they're shown as members also for the period before they joined the team (given that they've created a PR during the selected time period.

If people leave the team, they are excluded from the members, also from the period before they left the team.

### Why is someone not shown as a user despite having a license?

1. Check that the user belongs to your organization's business plan instead of using a personal license. Can you see them in the [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/administer/organizations/managing-access-to-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization#configuring-access-to-github-copilot-in-your-organization), [Cursor](https://cursor.com/analytics), or [Claude](https://console.anthropic.com/settings/members) admin dashboards?
   1. If your **Copilot** licenses are in a different GitHub organization than your repositories, you must [connect both GitHub organizations to Swarmia](/settings/integrations/code-hosting-platforms/github/multiple-github-organizations) to properly track them.
2. Check that the **Cursor** or **Claude Code** account is connected to the right contributor in the [Contributor settings](/settings/organization/contributors).

   1. Select "All contributors" as the filter.
   2. Type the person's name into the search box.
   3. Use the checkboxes to select the Cursor or Claude Code identity and the contributor it belongs to.
   4. Click "Merge".

   <figure><img src="/files/45fM2Ewt68cRXooDH8U4" alt=""><figcaption></figcaption></figure>

### Why don't the active Copilot users in Swarmia match the number in GitHub's dashboard?

Swarmia and GitHub's dashboard use different definitions for active Copilot users. Swarmia includes only people who:

* Belong to at least one team in Swarmia.
* Have accepted Copilot-generated code or used Copilot Chat during the calendar week.

GitHub's dashboard can count people as active more liberally. For example, if someone sees a code completion suggestion but doesn't accept it, GitHub can count them as active, but Swarmia doesn't.

### Why is it showing 0 users for today?

Many of the APIs we use are not real-time. We sync the AI adoption data daily, so there can be a delay of up to 24 hours for the numbers to become visible in Swarmia.


# GitHub Copilot activity

See detailed GitHub Copilot activity patterns across teams, features, models, editors, and programming languages

Available at [AI tools → AI activity → GitHub Copilot](https://app.swarmia.com/ai/activity/github-copilot)

<figure><img src="/files/FQlfo6qtWyAO06Jz7d0V" alt=""><figcaption></figcaption></figure>

If you're looking for a productivity boost from GitHub Copilot, it's not enough to enable the tool for your teams and then forget it. People need to pick up the new habit and invest the time to learn how to use it effectively. To support that, you need proper visibility into the current activity patterns.

With GitHub Copilot activity breakdown, you can:

* Understand what Copilot features people are actively using.
* See usage trends and understand the volume of code being generated with Copilot.
* Understand which languages, IDEs, chat modes, and LLM models people are using with Copilot.

{% hint style="warning" %}
Not all accepted code ends up in the codebase. An engineer could accept 200 Copilot-generated lines over the course of creating a 10-line pull request.

You can't use these metrics to get an accurate number of the share of your code that's AI-generated.
{% endhint %}

Read more in our guide on [understanding the impact of AI tools](/guides/understand-the-impact-of-ai-tools).

To track GitHub Copilot licenses, see [AI adoption metrics](/features/ai-tools/ai-adoption).

## Setup

See our instructions for [enabling the GitHub Copilot integration](/settings/integrations/ai-coding-tool-integrations/github-copilot-integration).

## Frequently asked questions

### Why is data missing for the selected team?

The **Copilot usage metrics** feature must be enabled in your organization for us to get the usage data. [Check your organization's settings](https://help.swarmia.com/features/ai-tools/pages/rUPMRN7X5FzPqWzsNXju#id-2.-enable-copilot-metrics-apis). It can take up to 6 hours for Swarmia to sync the data after you've enabled the API.

### What data is included in this view?

This view is based on [GitHub Copilot usage metrics data](https://docs.github.com/en/copilot/concepts/copilot-usage-metrics/copilot-metrics#which-usage-is-included) provided by GitHub. The data comes from telemetry provided by Copilot surfaces like IDEs and Copilot CLI. End users must have telemetry enabled in their IDE to be included in these metrics.

The [supported editors](https://docs.github.com/en/copilot/concepts/copilot-usage-metrics/copilot-metrics#supported-ides) are:

* Eclipse
* JetBrains / IntelliJ
* Visual Studio
* VS Code
* Xcode

The data **does not include** activity from:

* Copilot Chat on GitHub.com
* GitHub Mobile
* [OpenCode](https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/)

### Do these metrics include Copilot agent mode and Copilot coding agent?

* [**Copilot agent mode**](https://docs.github.com/en/copilot/how-tos/chat-with-copilot/chat-in-ide?tool=visualstudio#copilot-edits-1) allows Copilot to make autonomous edits directly in your local development environment (as a part of the Copilot Edits feature in Visual Studio and Visual Studio Code).
  * ✅ Included in this view
* [**Copilot coding agent**](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) works autonomously in GitHub Actions to complete tasks assigned through GitHub issues or GitHub Copilot Chat prompts, and creates pull requests with the results.
  * 👉 Not included in this view, but available in the [cloud agents view](/features/ai-tools/cloud-agents).


# Cursor activity

See detailed Cursor activity patterns across teams and modes

Available at [AI tools → AI activity → Cursor](https://app.swarmia.com/ai/activity/cursor)

<figure><img src="/files/vqP8Vvq9pPIrHK4RJnbF" alt=""><figcaption></figcaption></figure>

If you're looking for a productivity boost from Cursor, it's not enough to enable the tool for your teams and then forget it. People need to pick up the new habit and invest the time to learn how to use it effectively. To support that, you need proper visibility into the current activity patterns.

With the Cursor activity breakdown, you can:

* Understand where Cursor is gaining traction and where extra support may be needed.
* Know if people are just trying it out or actively relying on it in their work.
* Notice patterns in how suggestions are used across tab completions, agent, chat, and cmd+k.

Read more in our guide on [understanding the impact of AI tools](/guides/understand-the-impact-of-ai-tools).

To track Cursor adoption and licenses, see [AI adoption metrics](/features/ai-tools/ai-adoption).

## Setup

See our instructions for [enabling the Cursor integration](/settings/integrations/ai-coding-tool-integrations/cursor-integration).

## Definitions

* **Active users** = The number of users who have accepted code or used chat.
* **Code suggestions** = The number of Cursor code suggestions (excluding tab completions)
* **Code acceptances** = The number of Cursor code suggestions (excluding tab completions) accepted by users
* **Acceptance rate (suggestions)** = *Code acceptances / Code suggestions*
* Chat requests:

  * **Agent** = Requests in the chat using the "Agent" mode
  * **Ask** = Requests in the chat using the "Ask" mode
  * **CMD+K** = "Quick Edit" inline edits (⌘K on Mac)
  * **Composer** = Cursor's legacy multi-file edit feature

  <figure><img src="/files/yj665yCYXulvBwGJ6xnd" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Not all accepted code ends up in the codebase. An engineer could accept 200 Cursor-generated lines over the course of creating a 10-line pull request.

You can't use these metrics to get an accurate number of the share of your code that's AI-generated.
{% endhint %}


# Claude Code activity

See detailed Claude Code activity patterns across teams and modes

Available at [AI tools → AI activity → Claude Code](https://app.swarmia.com/ai/activity/claude-code)

<figure><img src="/files/3FNnY9bnAHlbgf4FNqr0" alt=""><figcaption></figcaption></figure>

If you're looking for a productivity boost from Claude Code, it's not enough to enable the tool for your teams and then forget it. People need to pick up the new habit and invest the time to learn how to use it effectively. To support that, you need proper visibility into the current activity patterns.

With the Claude Code activity breakdown, you can:

* Understand where Claude Code is gaining traction and where extra support may be needed.
* Know if people are just trying it out or actively relying on it in their work.
* Notice patterns in action proposals

Read more in our guide on [understanding the impact of AI tools](/guides/understand-the-impact-of-ai-tools).

To track Claude Code adoption and licenses, see [AI adoption metrics](/features/ai-tools/ai-adoption).

## Setup

See our instructions for [enabling the Claude Code integration](/settings/integrations/ai-coding-tool-integrations/claude-code-integration).

## Definitions

* **Active users** = The number of users who have accepted code or used chat.
* **Lines added / removed** = Total number of lines added / removed by the Claude Code across all files (not necessarily committed)
* **Actions accepted / rejected** = The number of Claude Code tool action proposals that the user accepted / rejected. Includes all file editing and creation actions.
* **Action acceptance rate** = *Actions accepted / (Actions accepted + Actions rejected)*

{% hint style="warning" %}
Not all accepted code ends up in the codebase. An engineer could accept 200 Claude Code-generated lines over the course of creating a 10-line pull request.

You can't use these metrics to get an accurate number of the share of your code that's AI-generated.
{% endhint %}


# AI impact: Code

See how pull requests assisted by different AI coding tools — or no AI tools — perform across metrics like throughput, cycle time, batch size, and review time.

The Code tab on the [AI tools → AI impact](https://app.swarmia.com/ai/impact/code) page helps you understand how pull requests assisted by different AI coding tools — or no AI tools — perform across metrics like throughput, cycle time, batch size, and review time.

This makes it easier to [answer questions like](https://www.swarmia.com/blog/staged-approach-AI-adoption-for-engineering/): Is AI-assisted work moving through your system faster or slower? Which teams benefit most from AI tools? Are AI-assisted pull requests staying small enough to review well?

## How to use the Code tab

Use it to understand how AI-assisted pull requests move through your delivery system:

* **Speed**: See how [pull request cycle time](/guides/improve-pull-request-flow/reducing-pull-request-cycle-time) and [throughput](/guides/improve-pull-request-flow/diagnosing-low-pull-request-throughput) change depending on AI use. Compare teams with different adoption levels, and pay attention to the share of review time versus time in progress.
* **Batch size**: Monitor [pull request batch sizes](/guides/improve-pull-request-flow/analyzing-pull-request-batch-size) to keep review quality high. AI assistants make it easy to generate large pull requests, and large changes are harder to review well.

Use these metrics to understand where AI helps, where it introduces new bottlenecks, and what your teams should look into next.

<figure><img src="/files/iva6ZfDtRlK0lh78c0tG" alt=""><figcaption></figcaption></figure>

## Available metrics

* PRs merged (throughput)
* Cycle time
* Time to first review
* Time in review
* Batch size

## Available selections

### Comparison type

First, use the tabs to select how the pull requests are grouped:

* **AI tools:** GitHub Copilot vs Claude Code vs Cursor vs everything else.
* **Modes:** [local changes (editor/CLI)](/features/ai-tools/ai-tool-detection-and-filters#local-changes-editor-cli) vs [cloud agent](/features/ai-tools/ai-tool-detection-and-filters#cloud-agent) vs [review agent](/features/ai-tools/ai-tool-detection-and-filters#review-agent) vs everything else.
* **AI used:** AI-assisted PRs (based on the tools and modes you select) vs everything else.

The structure of the tab is the same for all comparisons.

<figure><img src="/files/yQSnl64x27GquVWOZ6fk" alt=""><figcaption></figcaption></figure>

### Included tools

Select which AI tools (GitHub Copilot, Claude Code, and Cursor) are included in the comparison.

<figure><img src="/files/ifImDSYbSvwOwPZbhUKe" alt=""><figcaption></figcaption></figure>

### Included modes

Select which modes ([local changes (editor/CLI)](/features/ai-tools/ai-tool-detection-and-filters#local-changes-editor-cli), [cloud agent](/features/ai-tools/ai-tool-detection-and-filters#cloud-agent), and [review agent](/features/ai-tools/ai-tool-detection-and-filters#review-agent)) are included in the comparison.

There's also an option to [include only high-confidence matches](/features/ai-tools/ai-tool-detection-and-filters#local-changes-high-confidence-only) in the *local changes* mode.

<figure><img src="/files/8GWYwDSfyi56fdG4e5PI" alt=""><figcaption></figcaption></figure>

## Frequently asked questions

### Why is the total under "PRs merged" lower than the sum of its parts?

A single pull request can be associated with multiple AI tools and modes. For example, a developer might use both Cursor and Claude Code on the same PR. In that case, the PR is counted once in the Cursor category and once in the Claude Code category.

### How do you determine which AI tools to show for a PR?

Read more about our [automatic AI tool detection](/features/ai-tools/ai-tool-detection-and-filters).


# AI impact: ROI

Compare the combined cost of your AI tools and engineering work against the stories, pull requests, and code your teams deliver.

Available at [AI tools → AI impact → ROI](https://app.swarmia.com/ai/impact/roi)

The ROI tab puts cost and output side by side, so you can see what your organization spends per unit of delivered work and whether that number is moving. It combines the [token value](/features/ai-tools/ai-cost#token-value) of your AI coding tools with the estimated cost of engineering time, then divides it by the stories, pull requests, and code your teams ship.

This helps you answer questions your finance and leadership teams tend to ask: What are we spending per story or pull request? How much of our engineering cost is AI tools now? Is the AI spend translating into more output per engineer?

Pick a timeframe and optionally a team to drill into. Everything is bucketed by calendar month, and all amounts are shown in US dollars.

<figure><img src="/files/Nv0ggsBStgsk1CD34rYq" alt=""><figcaption></figcaption></figure>

### Total cost

The first chart stacks **developer cost** and **AI cost** per month, so you can see how the two move relative to each other. Alongside it you get the timeframe totals: developer cost, AI cost, AI cost per FTE per month, and AI cost as a share of total cost.

### Throughput and cost per unit

Three sections pair a throughput metric with the matching cost per unit of output:

| Section          | Throughput                                   | Cost                         |
| ---------------- | -------------------------------------------- | ---------------------------- |
| Issue throughput | Stories or epics completed per FTE per month | Cost per story or epic       |
| PR throughput    | Merged pull requests per FTE per month       | Cost per merged pull request |
| Code throughput  | Lines changed per FTE per month              | Cost per line changed        |

Throughput is divided by [developer effort](/definitions/developer-effort-ftes) rather than headcount, so growing or shrinking teams don't distort the trend. The cost charts stay stacked into developer cost and AI cost, which shows you whether a change in unit cost comes from AI spend or from engineering time.

Use the **Stories** and **Epics** tabs in the issue throughput section to switch between the two issue types.

### Team breakdown

The table at the bottom breaks the same metrics down by team. Select a team to drill into its child teams, and download the table as a CSV.

Teams are attributed the pull requests and issues they own, and the AI cost and effort of their current members. If people switch teams, their past cost and effort move with them.

## How the costs are calculated

Both cost components are estimates, and each has its own caveats:

* **AI cost** is the [token value](/features/ai-tools/ai-cost#token-value) of your AI coding tool usage: the list price of the tokens consumed, based on the [AI coding tool integrations](/settings/integrations/ai-coding-tool-integrations). It isn't your invoice, and it doesn't include seat or subscription fees.
* **Developer cost** is estimated from [developer effort](/definitions/developer-effort-ftes) and an organization-wide average: a team's monthly FTE multiplied by one twelfth of your configured average yearly developer cost.

To get developer cost, an [organization admin](/settings/organization/managing-users-and-roles) needs to turn on **Show estimated cost** and set an **Average yearly developer cost** in [Settings → Organization → General](https://app.swarmia.com/settings/organization/general). The figure should cover salary, benefits, and overhead. Until it's set, the ROI tab shows AI cost only, and the cost-per-unit metrics reflect AI spend alone. Estimated developer cost is visible to admins only.

If you configure the average developer cost in euros, Swarmia converts it to US dollars at a fixed rate so both cost components share one currency.

## What good looks like

Start with the AI cost share, because it tells you where your effort is worth spending. If AI spend is a small fraction of developer cost, the upside is in getting more out of the tools, not in trimming the tool bill: shaving a few percent off a small AI cost barely moves the total, while a real gain in throughput per FTE does. Cutting AI cost is worth the attention once it makes up a significant share of your total cost.

From there, read the tab as a trend rather than as a single month.

### Is the AI spend paying off?

* **AI cost share climbing while cost per unit falls.** You're trading engineering time for tool spend and getting more out per unit of effort.
* **AI cost share climbing while cost per unit holds or rises.** The spend isn't translating into output yet.

### How has the shape of the work changed?

The three unit costs often move in different directions. Read together, they tell you what changed about the work, not just whether it got cheaper.

* **Cost per line changed falls while cost per merged pull request rises.** Your pull requests are getting bigger: AI produces more code per change, but each change still needs a review. Check [batch size](/guides/improve-pull-request-flow/analyzing-pull-request-batch-size) and review time in [AI impact: Code](/features/ai-tools/ai-impact-code) to see whether review has become the constraint.
* **Cost per merged pull request falls while cost per story holds.** The code is flowing faster, but there's no clear increase in customer-facing increments. That points at something outside coding, such as scoping.

### What the numbers don't tell you

Cost per issue is the closest thing here to a business outcome, so it's also the one worth questioning: does one story or epic still represent the same amount of customer value it did a year ago? Teams that change how they work with AI tools might change how they split and size issues too.

Treat the unit costs as directional rather than exact. They measure output, not the value of what you shipped, so pair them with quality signals like [DORA metrics](/features/metrics/track-dora-metrics). For the wider picture, see the guide on [understanding the impact of AI tools](/guides/understand-the-impact-of-ai-tools).

## Requirements and limitations

* [GitHub Copilot](/settings/integrations/ai-coding-tool-integrations/github-copilot-integration), [Cursor](/settings/integrations/ai-coding-tool-integrations/cursor-integration), or [Claude Code](/settings/integrations/ai-coding-tool-integrations/claude-code-integration) integrations are required for AI cost.
* Issue throughput and cost per story require an [issue tracker integration](/settings/integrations/issue-trackers), with issues mapped to the story and epic issue types.
* Lines changed counts merged pull requests and excludes [auto-generated files](/definitions/batch-size#excluding-auto-generated-files).
* FTE follows the usual [effort rules](/definitions/developer-effort-ftes): contributors with fewer than 10 monthly activities are excluded, and each person contributes at most 1.0 FTE per month. Contributors need their Git and AI tool identities connected in the [Contributor settings](/settings/organization/contributors) for their cost and effort to land on a team.
* The current, incomplete month is included in the charts, so the latest data point moves as the month fills in.

## Frequently asked questions

### Why don't the figures match what we pay for AI tools?

AI cost is [token value](/features/ai-tools/ai-cost#token-value): the list price of the tokens your tools consume, including the harness. Seat and subscription fees aren't included, and on plans where heavy usage doesn't increase your bill, token value won't match your invoice.

### Why is developer cost missing?

Either cost estimation isn't set up yet, or your [user role](/settings/organization/managing-users-and-roles) doesn't allow you to see estimated cost. Admins can turn it on in [Settings → Organization → General](https://app.swarmia.com/settings/organization/general).


# AI cost (beta)

Track the token value of your organization's GitHub Copilot, Cursor, and Claude Code usage, and see how it maps to teams, people, and work

Available at [AI tools → AI cost](https://app.swarmia.com/ai/cost/overview)

AI cost shows how much your organization's AI coding tool usage is worth and breaks it down by team, by person, and by the work your teams deliver. It's based on [token value](#token-value): the list price of the tokens your tools consume.

## Token value

Token value is the list price of the tokens used, including the harness (overhead the agent adds, like system prompts and tool calls), regardless of what you actually pay. On subscription plans where heavy usage doesn't increase your bill, this tells you what that usage is worth. All amounts are shown in US dollars.

Where the data comes from depends on the tool:

* **GitHub Copilot:** [GitHub AI credit](https://docs.github.com/en/copilot/concepts/billing/usage-based-billing-for-individuals) usage from the [GitHub Copilot integration](/settings/integrations/ai-coding-tool-integrations/github-copilot-integration). Data is available from June 19, 2026 onwards.
* **Cursor:** Usage data from the [Cursor integration](/settings/integrations/ai-coding-tool-integrations/cursor-integration). Includes the list price of token usage and the Cursor fee, without discounts.
* **Claude Code:** Anthropic's "estimated cost" from the [Claude Code integration](/settings/integrations/ai-coding-tool-integrations/claude-code-integration) (supports both the [OpenTelemetry monitoring](/settings/integrations/ai-coding-tool-integrations/claude-code-integration#opentelemetry-monitoring) and the [Analytics API](/settings/integrations/ai-coding-tool-integrations/claude-code-integration#analytics-api)). Includes the list price of token usage, as well as harness costs such as prompt caching and tool use.

Token value isn't your invoice. It's a single comparable number that lets you aggregate AI usage across tools, teams, people, and work items. See [why we report token value instead of token counts](#why-do-you-report-the-token-value-instead-of-the-token-count) for the reasoning.

## The AI cost page

Pick a team and a timeframe, and the page shows:

* **Token value chart:** Claude Code, Cursor, and GitHub Copilot token value over time, with the total for the timeframe compared to the previous one.
* **Teams tab:** Token value per tool for each team, alongside the number of [AI-assisted pull requests](/features/ai-tools/ai-tool-detection-and-filters) merged and the number of people who used AI tools. Hover over the **Users** column to see each person's token value, and select a team to drill into its child teams.
* **Users tab:** The same breakdown per person for the selected team.
* **Work tab:** An embedded [focus summary](/features/focus/focus-summary) scoped to the selected team and timeframe, so you can see which issues and initiatives the spend went to.

<figure><img src="/files/HHnA0QkvC28PwimQ3zuO" alt=""><figcaption></figcaption></figure>

Both the Teams and Users tabs can be downloaded as a CSV.

The breakdowns are based on your current team members. Historical team memberships aren't supported: if people switch teams, their past token value moves with them to their current team. People who don't belong to any team are left out of the Users tab.

## AI spend in the focus summary

The [Work tab](#the-ai-cost-page) of the AI cost page and the [focus summary](/features/focus/focus-summary) include an **AI spend** column next to each issue or initiative. It shows the [token value](#token-value) from GitHub Copilot, Cursor, and Claude Code attributed to that work and its share of the total in the view. You can hover on the values to see a breakdown by AI tool and the time range of the data.

<figure><img src="/files/ICzaDFOnzBVyyYWF6zIX" alt=""><figcaption></figcaption></figure>

To attribute token value to work, Swarmia spreads each person's daily AI usage across the issues and pull requests they contributed to that day, in proportion to their [effort](/definitions/developer-effort-ftes). If someone uses AI tools on a day without attributable work, that usage is left out of the focus summary breakdown.

## AI spend in the issue pop-up

You can open any issue in Swarmia to see a spend breakdown by AI tool and contributor.

<figure><img src="/files/43B5lSjd2FcOTKQeEOhQ" alt=""><figcaption></figcaption></figure>

## Setup

AI cost is built on the [AI coding tool integrations](/settings/integrations/ai-coding-tool-integrations), so no separate setup is needed:

* **GitHub Copilot** requires the [GitHub Copilot integration](/settings/integrations/ai-coding-tool-integrations/github-copilot-integration).
* **Cursor** requires the [Cursor integration](/settings/integrations/ai-coding-tool-integrations/cursor-integration).
* **Claude Code** requires the OpenTelemetry setup described in the [Claude Code integration](/settings/integrations/ai-coding-tool-integrations/claude-code-integration#opentelemetry-monitoring).

For token value to land on the right person, each contributor's AI tool identities need to be connected in the [Contributor settings](/settings/organization/contributors).

## Frequently asked questions

### Why don't I see costs for today?

Like other AI tool data in Swarmia, cost data is synced periodically, so the numbers can be up to a day behind.

### Why is someone's cost attributed to the wrong person or missing?

Check that their AI tool identities are connected to the right contributor in the [Contributor settings](/settings/organization/contributors). Swarmia attributes cost to the merged contributor, so unmerged identities can leave cost unattributed.

### Why doesn't the token value match our AI tool invoice?

Token value is the list price of the tokens and harness (overhead the agent adds, like system prompts and tool calls) used, not your billed cost. On subscription plans like Claude Team, token usage doesn't map directly to what you pay. Seat license costs aren't included either.

### Why do you report the token value instead of the token count?

Adding up tokens into a single number would lead to an apples-to-oranges comparison:

1. Different LLMs price tokens differently. Claude Fable tokens are [over three times as expensive](https://platform.claude.com/docs/en/about-claude/pricing) as Claude Sonnet tokens, which arguably also reflects the value you get from them.
2. Each model uses its own tokenizer, so the same work can produce different token counts. For example, [Claude Opus 4.7 produces about 30% more tokens](https://www.anthropic.com/news/claude-opus-4-7) than Claude Opus 4.6 for the same exact text.
3. Different token types (input, output, cache read, and cache write) are priced differently — an output token can be [50 times the cost](https://platform.claude.com/docs/en/about-claude/pricing) of a cache-read token.

Token value converts usage into one comparable metric: the list price of the tokens used. This allows you to compare and aggregate AI spend across teams, people, issues, pull requests, and AI tools.


# Cloud agents

Gain visibility into the pull requests created by AI agents running in the cloud. See how they perform across metrics like throughput, merge percentage, and batch size.

## What is a cloud agent?

Cloud agents are AI coding agents responsible for creating pull requests end-to-end — planning work, editing code, running tests, and responding to reviews — not just suggesting code in your editor.

Most often, users assign AI cloud agents individually from issue trackers or prompt them to create a single pull request. AI cloud agents can also be autonomous, in which case they will have a backlog or objective and continuously pick work items on their own.

### Examples of cloud agents

* [**GitHub Copilot cloud agent**](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent) can create pull requests from [various sources](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent), including IDEs, GitHub.com, GitHub issues, GitHub Mobile, CLI, and MCP.
* [**Cursor Cloud Agents**](https://cursor.com/docs/cloud-agent) can create pull requests from [cursor.com/agents](https://cursor.com/agents), or you can trigger them via integrations, such as [Slack](https://cursor.com/docs/integrations/slack) and [Linear](https://cursor.com/docs/integrations/linear).
* [**Claude Code GitHub Actions**](https://code.claude.com/docs/en/github-actions) can create pull requests when you mention `@claude` in PRs or issues.
* [**Claude Code on the web**](https://code.claude.com/docs/en/claude-code-on-the-web) is available in research preview to selected pricing plans and can create pull requests from [claude.ai/code](https://claude.ai/code).
* [**Claude by Anthropic**](https://github.blog/changelog/2026-02-04-claude-and-codex-are-now-available-in-public-preview-on-github/) GitHub partner agent can create PRs from github.com, GitHub Mobile, and VS Code.

## Understanding your cloud agent performance

To help you understand how your AI cloud agents are performing, Swarmia automatically detects pull requests created by GitHub Copilot, Cursor, or Claude Code cloud agents. Swarmia provides a dedicated [**cloud agents**](https://app.swarmia.com/ai/agents/agents) (previously called "coding agents") view for analyzing them.

<figure><img src="/files/SBIDeyJLkhk7dtz10Xsc" alt=""><figcaption></figcaption></figure>

### Agent PR throughput

The Agent PR throughput chart shows how much work AI cloud agents help you ship.

**Agent PRs**, **Merged**, and **Closed** show the raw number of AI cloud agent pull requests.

**Merge percentage** tells you about your conding agent performance and how effectively people are able to use agents. Ideally, the number should grow close to 100%, but never quite reach it. Even though every closed pull request is technically waste (i.e., work done that was never shipped), a small percentage of closed pull requests indicates that people are experimenting with AI cloud agents and pushing their limits.

<figure><img src="/files/OdHIFwIXfa9QBCTmAOEG" alt=""><figcaption></figcaption></figure>

### Agent commit percentage

The **Agent commit percentage** chart breaks down your merged pull requests based on how much human intervention was needed for the work to be shipped.

Ideally, all your agent pull requests would have 100% agent commits, which means that the person was able to complete the whole task through the agent interface (e.g., GitHub Copilot's pull request integration). If a pull request ends up in the other buckets, it means that someone needed to pull up their coding environment and commit code to finish the work.

<figure><img src="/files/Crpx39f8I51Ohsl0p6Yr" alt=""><figcaption></figcaption></figure>

### Batch size

The **Batch size** chart helps you compare the distribution of AI cloud agent pull requests with your overall [Batch size](https://app.swarmia.com/metrics/code/batch-size) metrics. It also gives you an indication of the complexity of work AI cloud agents can tackle.

Depending on how you start using AI cloud agents, you might see that most agent pull requests initially fall in the smallest 1–5 or largest 500+ buckets. As your AI cloud agent usage develops, you should see the distribution move toward the buckets in the middle. This means your agents can tackle tasks of all sizes and ship code in manageable increments.

<figure><img src="/files/L3ykOCUQFio3Zb47eO60" alt=""><figcaption></figcaption></figure>

### Teams breakdown

The "Teams" tab provides a breakdown of the core metrics shown in the top charts, grouped by team.

<figure><img src="/files/opqGYQTWZKvP6nomXMMS" alt=""><figcaption></figcaption></figure>

### Pull requests tab

You can use the "Pull requests" tab in combination with the pull request filters at the top to inspect the individual agent pull requests.

<figure><img src="/files/5jBNpts78PgZ3vcLYCj1" alt=""><figcaption></figcaption></figure>

## Filtering PRs from cloud agents

You can use *cloud agent* mode in the [AI tool filter](/features/ai-tools/ai-tool-detection-and-filters#ai-tool-filter) to view pull requests created by cloud agents across the Swarmia app.

<figure><img src="/files/cv3ek2ah8YxRSsiEOMcD" alt=""><figcaption></figcaption></figure>

## Frequently asked questions

### Which AI cloud agents does Swarmia support?

We currently support GitHub Copilot, Cursor, and Claude Code. ([See examples here](#examples-of-coding-agents).) If you're using a different cloud agent or have built your own custom AI coding agents, reach out to us at <hello@swarmia.com> with the agent details (the agent's GitHub account or Git commit email, and an example pull request) you'd like to track.

### How do you identify PRs created with cloud agents?

Swarmia attributes a PR to a cloud agent if the PR or its first commit has been authored by GitHub Copilot, Cursor, or Claude Code.

Read more about our [automatic AI tool detection](/features/ai-tools/ai-tool-detection-and-filters#cloud-agent).

### Why is my PR not attributed to a cloud agent?

Swarmia attributes a PR to a cloud agent if the PR or its first commit has been authored by GitHub Copilot, Cursor, or Claude Code.

[See the examples here](/features/ai-tools/ai-tool-detection-and-filters#why-is-my-pr-not-attributed-to-a-cloud-agent).

### How does Swarmia attribute GitHub partner agents?

The [Claude by Anthropic](https://github.blog/changelog/2026-02-04-claude-and-codex-are-now-available-in-public-preview-on-github/) GitHub partner agent can create PRs from github.com, GitHub Mobile, and VS Code. Although you pay for it through the GitHub Copilot billing, Swarmia attributes it as the Claude Code cloud agent because it's using a Claude harness.

## Further reading

Swarmia blog: [Five levels of AI coding agent autonomy, and why higher isn’t always better](https://www.swarmia.com/blog/five-levels-ai-agent-autonomy/) by Miikka Holkeri, Product Manager · Mar 19, 2026


# Review agents

See which AI agents are reviewing your pull requests, how much of your code they're covering, and how many findings they're leaving per PR.

## What is a review agent?

A review agent is an AI tool that automatically reviews pull requests — leaving comments, flagging potential issues, and suggesting improvements — without creating any code itself. Unlike [cloud agents](/features/ai-tools/cloud-agents), which author PRs from start to finish, review agents act as an additional reviewer on top of your existing pull request process.

### Examples of review agents

* [**GitHub Copilot code review**](https://docs.github.com/en/copilot/using-github-copilot/code-review/using-copilot-code-review) can review pull requests directly on GitHub and leave inline suggestions.
* [**Cursor Bugbot**](https://cursor.com/bugbot) scans pull requests for bugs and posts a summary to the PR description.
* [**Claude Code**](https://code.claude.com/docs/en/code-review) can review pull requests when triggered via GitHub Actions or mentioned in a PR.

## Understanding your review agent coverage

Swarmia automatically detects pull requests reviewed by GitHub Copilot, Cursor, or Claude Code and shows them in the [**AI tools → Review agents**](https://app.swarmia.com/ai/reviews).

<figure><img src="/files/RBUwqS1nbvMDiZvn5qBr" alt=""><figcaption></figcaption></figure>

### Agent-reviewed PRs

The **Agent-reviewed PRs** chart shows the share of your pull requests that received at least one review agent comment over time. The stacked bars distinguish PRs reviewed by an agent from those that weren't, and the review ratio makes it easy to track adoption across your organization.

Use this chart to understand whether review agent usage is growing and to spot teams that haven't adopted them yet.

### Findings per PR

The **Findings per PR** chart shows the distribution of pull requests by the number of comments review agents left on them. "Findings" are individual review comments or suggestions from the agent — not just a summary at the top level.

A healthy distribution means agents are leaving substantive feedback rather than just passing PRs silently. If you see a spike at zero findings, it may mean agents are being triggered but not surfacing meaningful feedback.

### Tabs: Teams, pull requests, and review agents

The table below the charts has three tabs:

* **Teams**: Breaks down agent-reviewed PRs, coverage percentage, total findings, and findings per PR by team. Useful for comparing adoption across your organization.
* **Pull requests**: Lists individual PRs with the agents that reviewed them and how many findings each agent left. Use this together with the PR filters to inspect specific repositories or time ranges.
* **Review agents**: Shows per-agent stats — how many PRs each agent reviewed, their share of total PRs, and their average findings per PR.

## Frequently asked questions

### Which review agents does Swarmia support?

Swarmia currently detects reviews from GitHub Copilot, Cursor, and Claude Code. If you're using a review agent that isn't showing up, reach out to us at <hello@swarmia.com> with the agent's GitHub account or email and an example pull request.

### How does Swarmia detect review agents?

Swarmia identifies a review agent by matching the author of review comments against known email addresses and GitHub login patterns for GitHub Copilot, Cursor, and Claude Code.

Read more about [automatic AI tool detection](/features/ai-tools/ai-tool-detection-and-filters#review-agent).

### How is this different from cloud agents?

[Cloud agents](/features/ai-tools/cloud-agents) create pull requests end-to-end. Review agents only leave feedback on pull requests created by humans (or cloud agents). The two can overlap: a cloud agent PR can also be reviewed by a review agent.

Swarmia tracks them separately so you can understand each type of AI involvement in your workflow.


# AI tool detection & filters

Swarmia automatically detects pull requests assisted by GitHub Copilot, Cursor, or Claude Code

## Automatic AI tool detection

To help you understand how AI use affects developer productivity metrics, Swarmia automatically detects pull requests assisted by GitHub Copilot, Cursor, or Claude Code. You can see the AI tools involved in an individual pull request by opening it anywhere in the app.

### Local changes (editor/CLI)

A pull request is considered to have local AI changes (editor/CLI) if at least one of these conditions is met:

* Any of its commits were authored or co-authored by an AI tool *(high confidence)*
* Any of its commits has the `Made-with: Cursor` Git trailer *(high confidence)*
* It has the `claude-code-assisted` label *(high confidence)*
* Any of its commits were made by an author who used an AI tool within the previous 24 hours *(low confidence)*

You can see the reason for tagging an individual pull request in a tooltip by hovering over the AI tool badge:

<figure><img src="/files/0Gqal4MVZuKP7ZQd8bJp" alt=""><figcaption></figcaption></figure>

### Cloud agent

Swarmia attributes a PR to a [cloud agent](/features/ai-tools/cloud-agents) if the PR or its first commit has been authored by GitHub Copilot, Cursor, or Claude Code.

The AI coding agent used to create a pull request is shown on top of the pull request author’s avatar. You can hover over the avatar to see more details:

<figure><img src="/files/yEsdbTjDesrbvODvCOZ3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
In Swarmia, pull requests authored by AI tools are attributed to the people who initiated them. For example, if GitHub Copilot creates a PR on your behalf, Swarmia shows you as its author.
{% endhint %}

### Review agent

Swarmia attributes a PR to a review agent if it has reviews from GitHub Copilot, Claude Code, or Cursor.

## AI tool filter

You can use the **AI tool** filter to view pull requests in [Code metrics](/features/metrics/pull-request-cycle-time), [PR exclusion rules](/settings/team/team-pr-exclusions), and [investment category rules](/settings/organization/investment-balance) based on the AI tools involved.

The filter includes two selections:

* **Tools:** GitHub Copilot, Cursor, and Claude Code
* **Modes:** [local changes (editor/CLI)](#local-changes-editor-cli), [cloud agent](#cloud-agent), and review agent
  * For local changes, you can choose to [include high-confidence matches only](#local-changes-high-confidence-only) (read more below)

<figure><img src="/files/FRGIVwNuxGD0CFrDxMoR" alt=""><figcaption></figcaption></figure>

### Local changes: High confidence only

This is an optional setting that applies to [local changes (editor/CLI)](#local-changes-editor-cli) only.

* **Enabled**: Match *only* work directly tagged by AI tools (labeled with *"high confidence"* in [the list above](#local-changes-editor-cli)). This can result in underreporting AI involvement.
* **Disabled**: Also match work based on the authors' activity times in AI tools (labeled with *"low confidence"* in [the list above](#local-changes-editor-cli)). This can result in overreporting AI involvement.

<figure><img src="/files/f9UfbqXje7lGOFpZhMeh" alt=""><figcaption></figcaption></figure>

## Frequently asked questions

### Why is my PR marked AI-assisted even though I didn't use AI for it?

Some AI coding tool providers don't share PR-level activity data in their analytics APIs. To address this, we use certain heuristics, such as checking if the commit authors have used an AI tool within the previous 24 hours. (See [the full list of rules](#local-changes-editor-cli) above.)

This can result in false positives (overreporting AI involvement). For example, if you simultaneously work on tasks A and B, but only use AI for task A, Swarmia inaccurately associates the tool usage also with task B. You can use the [high-confidence filter](#local-changes-high-confidence-only) to avoid reporting false positives.

You can hover over the AI tool label to see the exact attribution reason for any pull request:

<figure><img src="/files/CREIhTUZuy03hrcucIJ4" alt=""><figcaption></figcaption></figure>

### Why is the attribution window 24 hours?

It accounts for cases where you create code with AI today but commit it tomorrow. Also, some AI coding tool providers report user activity only on the daily level, so we can't get more granular than that.

You can use the [high-confidence filter](#local-changes-high-confidence-only) to disable the time-based attribution.

### Why is my PR not attributed to a cloud agent?

Swarmia attributes a PR to a [cloud agent](/features/ai-tools/cloud-agents) if the PR or its first commit has been authored by GitHub Copilot, Cursor, or Claude Code.

Example 1: With [GitHub Copilot coding agent](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent), GitHub shows *Copilot* as the PR author. Swarmia shows this as a GitHub Copilot agent PR:

<figure><img src="/files/ApYzPz9iavatqnBZYPB6" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Note: Regardless of what GitHub displays, Swarmia always shows the author as the person who initiated the AI coding agent PR.
{% endhint %}

Example 2: When using [Cursor Cloud Agents](https://cursor.com/docs/cloud-agent), GitHub shows *cursoragent* as the author of the first commit, and the user who started the agent as the PR author. Swarmia shows this as a Cursor agent PR:

<figure><img src="/files/UOY7lPT6OwWMj8lVyQVo" alt=""><figcaption></figcaption></figure>

Example 3: The first commit in this PR was authored by *Claude* but committed by *cursoragent*. Swarmia shows this as a Claude Code agent PR:

<figure><img src="/files/uXZLfIhTIDphSmAlXV8C" alt=""><figcaption></figcaption></figure>

### If I ask an AI tool to create a PR with my local changes, is it considered a cloud agent PR?

No, we don't regard that as a cloud agent PR since you review and accept the suggestions (and perhaps manually write some of the code) before creating the PR.

The AI tool uses your local Git identity, so you are marked as the PR author and the commit author. (The tool might mark itself as the co-author, however.)

Swarmia shows these PRs as [local changes](#local-changes-editor-cli).


# PR inbox

See all open pull requests and where they are going in a team context.

With GitHub, it is surprisingly difficult to see all open pull requests and where they are going in a team context. Especially when you are working in an environment with multiple repositories and lots of cross-team collaboration, it can be easy for pull requests to fall through the cracks. [The Pull Request view](https://app.swarmia.com/pull-requests/our-team) in Swarmia works in real-time and helps teams manage their pull requests in progress, make sure they are moving forward swiftly, and ensure no pull request is forgotten.

Our team heavily uses the pull request view to see if there are PRs that could be merged or if there are PRs waiting for review to help a teammate before starting something new.

<figure><img src="/files/SbTapLqYX0DFK0DGC7r1" alt=""><figcaption></figcaption></figure>

## Pull request flow of delivery graphs

You can see two graphs on top of the Pull Request view giving you a rough idea of how the pull request flow of delivery functions within your team.

<figure><img src="/files/ulAQQOv6jfRWcR9v6z2O" alt=""><figcaption></figcaption></figure>

The cycle time graph shows you how long, on average, it takes for pull requests to take from the first commit to be merged. You will also see the split between how long pull requests on average spent in progress versus in review versus merge phase based on the activity in GitHub. Pull Requests move into the "review" state when a review is requested in GitHub and again to the "merge" state when approved. The "waiting for review" status covers the entire review phase. It stays the same whether no one has started yet or a reviewer is actively commenting — until the PR is approved.

The throughput chart shows how many pull requests you get through as a team over time. The colors on the stacked bars represent the status of the pull requests opened on that specific day. In the throughput chart, we focus most on the yellow part. Seeing a lot of yellow in the past would indicate that on some days, we open a lot of PRs but are just unable to get them in. Then it might make sense to focus on getting the old pull requests merged or closed before taking on more work.

## Pull request view filters

Multiple filters on the left side of the page help you separate the signal from the noise.

**Our team** - This is the default filter and it shows you all of the pull requests that have been authored by the members of the team. Not only can you see your own pull requests here, but you can also identify a way to help your teammate by reviewing their pull request waiting for review.

**Participating** - This is a personal filter that is unique to every Swarmia user based on which pull requests you are participating in yourself by authoring it, being assigned as a reviewer, or just participating in the discussion.

**From others** - This filter shows you all of the pull requests sent to your team for review from any other team. This is a neat way to ensure you are also swiftly reviewing pull requests related to team interfaces since these pull requests easily fall through the cracks.

**Bots** - We also separate pull requests authored by bots under their own filter. So if you are using dependency bots or renovates it will not get as noisy when they open a whole lot of dependency prs some night.

**>30 days old** - Under the old PRs we show you everything that is getting so old that you might want to clean them up by closing in GitHub to maintain good GitHub hygiene.

**>24h stale** - The stale PRs are at risk of being forgotten, so it makes sense to check these together with your colleague to see if they are still relevant, and if they are, work through them so no one has to do any major rebasing or anything like that.

**Unlinked** - This filter is one way that Swarmia helps your team link pull requests to issues. Under this filter, you will see all unlinked pull requests and can link them directly through the UI into categories or issues.

**Custom filters** - Below the "Unlinked" filter are a number of custom filters which are up to you to configure as you wish. These filters are called "Investment Categories" in Swarmia, and you can manage them from [the investment category settings](https://app.swarmia.com/settings/investment-categories). These investment categories are also used in different parts of the app; more about them [in this article.](https://help.swarmia.com/configuring-investment-categories)

**Excluded** - If you exclude a pull request in Swarmia you will still be able to access it through this filter on the Pull Request view. If you change your mind about excluding a pull request, you can also re-enable it in the metrics and alerts in Swarmia through here.

## Pull request popup

We want to enable you to drill down into the details in Swarmia. By clicking on the three dots on the very right side of any pull request, you can open the pull request popup. This view gives you more details on the individual pull request level.

If you feel like particular pull requests should rather be excluded from the metrics and alerts in Swarmia, you can switch the toggle for any pull request to exclude it from the metrics.

<figure><img src="/files/amtHm7f28MnYI4V1vtVt" alt=""><figcaption></figcaption></figure>

## To conclude

[The Pull Request page](https://app.swarmia.com/pull-requests/our-team) in Swarmia helps team members stay on top of their pull requests and make sure they are moving forward without any pull request falling through the cracks. If you want to make managing pull requests in progress even easier, we recommend looking into [the Swarmia personal Slack and Microsoft Teams notifications for pull requests](https://help.swarmia.com/personal-notifications).


# Working agreements

Working agreements help teams continuously improve with clear goals and consistent execution

## **Work better together**

We believe in self-organizing teams that own their ways of working. With Swarmia’s [Pull Request Dashboard](https://app.swarmia.com/pull-requests), [Work Log,](https://app.swarmia.com/work) and [Insights](https://app.swarmia.com/insights), you already get full visibility into your process and can identify potential improvements — but transparency alone is not enough to become better and stronger as a team.

You’re probably used to sitting down (or standing up!) together as a team and deciding to change something about how you’re working. Maybe this is something you do as a matter of process, for example, in a retrospective meeting every couple of weeks. Having retrospectives and systematically improving ways of working is something that all teams should do, but without considerable self-discipline and support from the organization, decisions to improve can end up being ignored or forgotten.

[Swarmia's working agreements](https://app.swarmia.com/working-agreements) help you spring from idea to action, execute consistently, and form new habits as a team.

## **A multi-functional tool for continuous improvement**

Some issues you can identify with Swarmia are clear-cut, while others have considerable nuance and complexity. For instance, code reviews are probably not slow because developers are lazy but because of deeper issues with focus or infrastructure. In cases like these, exceptions highlighted by working agreements are opportunities to dive deeper into the root causes and have meaningful conversations as a team. [You can read more about why and how to review code faster here](/guides/improve-pull-request-flow/review-code-faster).

On the other hand, managing work in progress is widely recognized as the most critical driver of focused teams that deliver fast. Simply limiting the number of Stories, Tasks, or Epics the team can have on its plate at a given time is all but guaranteed to result in faster cycle times and better team dynamics.

## **Get started with working agreements**

Ready to jump in? Why not have a conversation with your team about issues you’ve detected about team focus or Pull Request cycle times, and head over to the [working agreements](https://app.swarmia.com/working-agreements) to get started!

<figure><img src="/files/yRc11uJR3mWZDlKDVYuf" alt=""><figcaption><p><em>Explore working agreements and decide what to improve</em></p></figcaption></figure>

After choosing what to improve and setting up the working agreement, you get insights about how you’re doing as well as a list of all exceptions from the past two weeks helping you pinpoint specific issues or discussions to have with the team.

<figure><img src="/files/BLg9r4YQ7ThWYt1VS7kV" alt=""><figcaption><p><em>Set up working agreements and see how you’re doing</em></p></figcaption></figure>

Finally, the daily digest keeps you up to date about progress and exceptions and helps your team stick to new habits. If you haven't enabled the daily digest yet, now is a good time to do it for [Slack](https://app.swarmia.com/settings/slack) or [Microsoft Teams](https://app.swarmia.com/settings/microsoft-teams)!

<figure><img src="/files/lJp8QSbMND379QLCshiK" alt=""><figcaption><p><em>Daily feedback helps stick to new habits</em></p></figcaption></figure>


# Surveys

See what truly affects developer experience and productivity by viewing relevant survey results alongside your system data.

When engineers voice their frustrations and suggest improvements, you start to understand what is behind the metrics and get concrete ideas on what to improve. For example, you might learn that long epic cycle times are caused by interruptions, unclear priorities, or missing technical validation.

{% embed url="<https://youtu.be/28YwYav3oY4>" %}

#### Read more on our blog

* [Minimizing noise and bias in developer surveys](https://www.swarmia.com/blog/minimizing-noise-and-bias-in-developer-surveys/)
* [35 questions to ask in your developer experience surveys](https://www.swarmia.com/blog/developer-survey-questions/)
* [Complementing engineering metrics with developer experience surveys](https://www.swarmia.com/blog/complementing-engineering-metrics-with-developer-experience-surveys/)
* [How to run developer survey retrospectives in your team](https://www.swarmia.com/blog/developer-survey-retrospectives/)


# Creating a survey

Improve developer experience by collecting insights directly from your engineers at scale. Identify patterns and turn them into actions.

{% hint style="info" %}
Only Swarmia users with the [**Admin role**](/settings/organization/managing-users-and-roles) **can create and manage surveys**. Contact <hello@swarmia.com> if you'd like to allow everyone in your organization to create surveys.
{% endhint %}

## Prerequisites

* [Teams created in Swarmia](/settings/organization/managing-teams)
* [Messaging app connected](/settings/integrations/messaging-apps) (optional step to send survey invites and reminders for higher response rate)

## Create new survey

To start creating an engineering survey, navigate to the *Surveys* page from the sidebar and click *Create survey*.

<figure><img src="/files/f6onlk9Jr4cBlhsxxj6D" alt=""><figcaption></figcaption></figure>

Your progress is **automatically saved as a draft** so you can exit the view and resume later.

Give the survey a **name**, which will also be visible to the respondents.

## Questions

Select the **questions to include in the survey**. Choose from Swarmia's questions, carefully crafted in collaboration with experts in psychometrics. They are all framed as statements, and the respondents answer them on a **five-point scale** from *strongly disagree* to *strongly agree*. You'll see the **estimated time to complete** based on your selections.

<figure><img src="/files/vbSJj56UUkE3cG9zJqf5" alt=""><figcaption></figcaption></figure>

In addition to the questions you select, the survey will also include an option for the respondents to add **open comments** at the end.

<figure><img src="/files/MHlESK59wls0LRCAPn8U" alt=""><figcaption></figcaption></figure>

### **Custom questions**

You can also **add your own questions** by selecting *Add question* in one of the topics.

<figure><img src="/files/skMkN9qrjv4JvaugQ7Pw" alt=""><figcaption></figcaption></figure>

These use the same format as the built-in questions. They should be statements, and the respondents rate how much they agree with each on a five-point scale. Agreeing with the statement is considered good and yields the highest score of 5.

{% hint style="info" %}
[Read our tips for creating high-quality questions](https://www.swarmia.com/blog/minimizing-noise-and-bias-in-developer-surveys/) on our blog.
{% endhint %}

<figure><img src="/files/TLCGTY38k8XFV4YOORG9" alt=""><figcaption></figcaption></figure>

## Teams and schedule

On the next tab, **select the teams** for which the survey will be available.

<figure><img src="/files/0vRoEvrakm4opxIdhohR" alt=""><figcaption></figcaption></figure>

The team structure and memberships will be saved as a static "snapshot" when the survey goes live. New people added to the selected teams afterward will be **automatically added to live surveys**.

You can edit a live survey to add more teams to it.

{% hint style="warning" %}
You can't remove people from the survey after launching it.
{% endhint %}

Choose an **end date** for the survey. When it's reached, the survey will close for responses, and the results will become available to admins. You can edit a live survey to change the end date later.

The **start date** can't be changed. The survey will go live immediately when you launch it.

## Preview

Click *Preview* to see **how the respondents will see the survey**.

<figure><img src="/files/gic2rrxNMGWoRWXqIm23" alt=""><figcaption></figcaption></figure>

A pop-up opens, showing the preview with your latest selections. (You can respond as if you belong to any team, but your submission won't be recorded.)

<figure><img src="/files/36rDN2abHkrKGOBt05KI" alt=""><figcaption></figcaption></figure>

## Launching the survey

Click *Launch survey* when you're ready to go live. The survey is **open for responses immediately**.

To distribute the survey, click *Copy link* to get a **link you can send to your teams**. We also provide you with an example message with all the survey information prefilled.

<figure><img src="/files/p0tEZakTJY20GM59d39E" alt=""><figcaption></figcaption></figure>

Users in the audience will also see a notification banner on their Swarmia home page:

<figure><img src="/files/RWuAbM1d0IZ5KlVtVjWr" alt=""><figcaption></figcaption></figure>

## Reminders

Swarmia automatically sends a Slack notification to everyone in the survey audience (except the survey creator) one hour after the survey opens. After that, Swarmia will notify people who haven’t responded about 7, 3, and 1 day(s) before the survey closes. (Reminders are only sent on weekdays. You can see the exact times when creating a survey.)

<figure><img src="/files/Ob8LMbO8BktxC1ajBgs2" alt=""><figcaption></figcaption></figure>

You can see if we can't find some of the people from Slack and connect their accounts before launching the survey.

You can [follow the survey participation rates](/features/run-developer-experience-surveys/managing-surveys) by the team to manually remind those lagging behind.

## Frequently asked questions

### **Why should I run developer surveys?**

You need data to make the most informed decisions for improving your engineering effectiveness. To get the full picture, you can't rely only on system metrics from sources like version control systems or issue trackers. Surveys help you form a comprehensive understanding of how your developers perceive their work. They also allow engineers to voice their frustrations, suggest improvements, and feel heard.

### **How are developer surveys different from employee engagement surveys?**

Employee engagement surveys are a generic way to measure job satisfaction and identify areas for improvement, usually at the company level. Swarmia's developer surveys are purpose-built for engineers with questions about topics like code reviews, automated tests, and technical debt.

Instead of just informing the human resources department and executives, they're a resource for the engineering organization and teams to address hands-on problems autonomously. The engineers can describe challenges in technical terms and get understood.

We recommend running developer surveys alongside any engagement surveys in your company. If you're concerned about the overlap between the two, you can disable some or all the questions under *Direction*, *Collaboration*, and *Culture*.

### Why can't I edit existing survey questions?

A different wording can change the interpretation of the question, after which the results are not comparable. You can create a new custom question and archive the old one (although built-in questions can't be archived). This means, however, that Swarmia treats those as [different questions in the results view](/features/run-developer-experience-surveys/viewing-and-sharing-survey-results#comparisons).

### Can I add people to a live survey?

Yes! See [#teams-and-schedule](#teams-and-schedule "mention") above.

### Can I edit the end date of a live survey?

Yes! See [#teams-and-schedule](#teams-and-schedule "mention") above.

### Can I add people without GitHub accounts to a survey?

Yes! If you use [Google](/settings/integrations/authentication/google-single-sign-on) or [Okta](/settings/integrations/authentication/okta-single-sign-on) SSO, you can [add those people to teams](/settings/configuration/team-setup) once they have signed up for Swarmia. Then, simply include the team in the survey audience.


# Managing surveys

You can create, preview, duplicate, close, and delete surveys.

## Creating a survey

[Read more about creating a survey here](/features/run-developer-experience-surveys/creating-a-survey).

## Survey actions

Here's what you can do to draft live, unpublished, and published surveys on the [**Surveys**](https://app.swarmia.com/surveys) tab.

You can access the following actions by clicking `...` in the *Actions* column:

<figure><img src="/files/uaaAMVLaTAjKdpV7QtoN" alt=""><figcaption></figcaption></figure>

### **Preview**

Open a popup showing how the respondents saw, see, or will see the survey. You can respond as if you belong to any team, but your submission won't be recorded.

### **Duplicate**

Start creating a new survey based on another one. You can make changes before [launching the new survey](/features/run-developer-experience-surveys/creating-a-survey).

### **Close**

Close a live survey for responses and [access the results](/features/run-developer-experience-surveys/viewing-and-sharing-survey-results). A closed survey can't be re-opened.

### **Delete**

Permanently delete a survey or draft.

### **Edit survey**

Add new teams to audience, or change the end date.

### View the survey audience

To see the exact people included in the survey audience, click the team avatars in the *Teams* column.

<figure><img src="/files/wBs2m24BOnDgMNueJbGv" alt=""><figcaption></figcaption></figure>

### View participation by the team

Click the indicator in the *Participation* column to see the response rates in each team. It’s also available for live surveys to help remind the teams that are falling behind others.

<figure><img src="/files/BrSn0eJ6PA6SDrinWhFV" alt=""><figcaption></figcaption></figure>


# Viewing and sharing survey results

After a survey ends, you can review the results, publish them to your teams, or export them

{% hint style="info" %}
Results are **available only from surveys that have ended**. You can't view results from live surveys, but you can [view their participation numbers](/features/run-developer-experience-surveys/managing-surveys).
{% endhint %}

To access a survey's results, click on the name of a survey that has ended, or select *View results* from the right-side menu.

## Analyzing the results

### **Heatmap**

The heatmap shows a color-coded overview of **each team's average ratings** across the survey.

You can see the **number of responses** from a particular team by hovering your mouse on the row.

The scores are aggregated on all levels of the team hierarchy. You can expand and collapse teams to view just the scores you're interested in.

<figure><img src="/files/5FkPII7xf8df7cpM8vw4" alt=""><figcaption></figcaption></figure>

The main overview shows **average scores across all the questions in a topic**. You can expand the topics to see a more detailed **breakdown of each question**.

<figure><img src="/files/oUvspKUQnSqvP99HF8NT" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/W6joT00QFQRP64wnPqnM" alt=""><figcaption></figcaption></figure>

You can click any of the cells in the heatmap to see more details on the *Questions & comments* tab.

### **Comparisons**

{% hint style="info" %}
The survey scores aren't normalized between questions. A higher score in one question is not necessarily better than a lower score in another question. To make conclusions, you need to compare the scores to trends, benchmarks, or other teams.
{% endhint %}

The "Compare with..." menu in the heatmap offers you three ways to compare survey results:

<figure><img src="/files/tLnkePuei9eU92afjwyg" alt=""><figcaption></figcaption></figure>

* **Survey average**: Shows how much each team is above or below the survey’s average (all teams) in each topic and question.
* **Industry benchmarks**: Shows how your results compare with average survey ratings for each question from organizations using Swarmia. You can choose from three percentiles: p50 (median), p75, and p90.
  * The benchmarks are available for [Swarmia’s built-in questions](https://www.swarmia.com/blog/developer-survey-questions/).
  * The benchmarks for each topic are calculated as averages only based on the questions you have included in the survey.
  * Any custom questions you have created are ignored in the topic averages.
* **Another survey**: Select any of your surveys and see the changes in scores between them.
  * If the two surveys have a different set of questions, the topic averages are calculated based on the overlapping questions. Questions available only for one of the surveys are ignored.
  * Each team is considered the same team across the two surveys, regardless of any changes to its members or sub-teams.
  * The ratings for the "All teams" row are calculated by comparing the following:
    * This survey: all teams in this survey
    * Other survey: the teams that can be found in both surveys

### **Questions & comments**

On the *Questions & comments* tab, you can see **all the comments and the detailed distribution of ratings by topic, question, and team**.

On the left side, you have controls for topic and team filters.

On the right, you have options for sorting by

* Original order
* Highest score
* Lowest score
* Most comments
* Most skips

Click any of the questions to see its comments.

You can hover over the distribution bar to see the detailed rating counts.

You can also view trends for each question across your past surveys where that question appeared.

<figure><img src="/files/CAvhldsES7XBKlWX9ISV" alt=""><figcaption></figcaption></figure>

### **Participation**

On the *Participation* tab, you can see **the response rate in each team**.

<figure><img src="/files/qNCy0jBV9NyfUQlvmU2G" alt=""><figcaption></figcaption></figure>

The participation numbers are based on [team memberships](/settings/organization/managing-teams), not the primary team respondents select in the survey. If someone belongs to multiple teams, they are counted in the participation numbers in each of them (for both team size and the number of respondents).

{% hint style="info" %}
**Example**

Team Blue:

* Aron
* Bella

Team Red:

* Bella
* Charlie

If only Bella responds to the survey, both teams have a participation of 1 / 2 (50%) — regardless of whether she selects Blue or Red as her primary team.
{% endhint %}

### **Related metrics**

Some of the survey questions have related metrics to provide more context on the results. You can find them by expanding the questions on the *Questions & comments* tab. You can click the metrics to access the relevant Swarmia page filtered by the selected team.

<figure><img src="/files/JdWPSXylvEZMSph3UCga" alt=""><figcaption></figcaption></figure>

The links work also the other way around. You can see the latest survey results for the selected team within the selected timeframe next to your [pull request data](https://help.swarmia.com/pull-request-insights), [issue insights](https://help.swarmia.com/understanding-the-issue-life-cycle), and [DORA metrics](https://help.swarmia.com/deployment-insights). To see the rating distribution and comments, simply click on the score to access the detailed survey report.

<figure><img src="/files/teVXylW9qHg5CCrIypIb" alt=""><figcaption></figcaption></figure>

## Publishing the results

After the survey ends, **the results are first available only to the survey creator and** [**admins**](https://help.swarmia.com/users-and-roles). This allows you to review them before sharing them with your team.

{% hint style="info" %}
If the results contain sensitive or offensive comments, contact Swarmia to get them removed.
{% endhint %}

**When you're ready to show the results to others**, select *Publish* in the top-right corner. You can publish the results to just the survey audience or your whole organization. You'll get a link and a pre-written message template for easy sharing, and people in the audience will automatically get notified via Slack in one hour.

<figure><img src="/files/ee4iGMLesLrNsfdpZCLH" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Published results can be **unpublished** by clicking the *Published* button.
{% endhint %}

## Downloading the results

You can also export the results to use them elsewhere. Just click the *Download survey results* button in the top-right corner.

<figure><img src="/files/IXMV8PlGSR7CmYWVAb7T" alt=""><figcaption></figcaption></figure>

You'll get a ZIP archive with **three comma-separated values (CSV) files**:

### **Scores**

One row for each team-question pair:

* `question`: The question the rating relates to
* `questionGroup`: The topic the question belongs to
* `team`: The team associated with this rating (selected as their primary team by the respondents)
* `rating`: The average rating the team gave for the question on a scale from 1 to 5 (excluding skips). If everyone in the team skipped the question, the value is `null`.
* `numberOfSkips`: The number of responses that skipped the question
* `totalNumberOfRespondents`: The number of people in the team who selected it as their primary team and responded to the survey (= rated or skipped the question)
* `numberOf1Ratings`: The number of score 1 ratings (strongly disagree) given
* `numberOf2Ratings`: The number of score 2 ratings (disagree) given
* `numberOf3Ratings`: The number of score 3 ratings (neutral) given
* `numberOf4Ratings`: The number of score 4 ratings (agree) given
* `numberOf5Ratings`: The number of score 5 ratings (strongly agree) given

### **Comments**

One row for each comment:

* `question`: The question the comment relates to
* `questionGroup`: The topic the question belongs to
* `team`: The primary team the comment's author selected in the survey
* `comment`: The contents of the comment
* `authorName`: The name of the user who wrote the comment

### **Participation**

One row for each team:

* `totalNumberOfRespondents`: The number of people in the team who responded to the survey
* `totalNumberOfTeamMembers`: The number of people in the team who had access to the survey


# How we show your survey responses

Responses are reported by team. You can choose whether to show your name in comments.

You need to be logged in to respond to a survey in Swarmia. We link your responses to your Swarmia profile and handle the information confidentially according to our [Privacy Policy](https://www.swarmia.com/privacy/). The survey administrators can see **only the information described in this article**. They'll have an option to share the results with the rest of your organization.

## How we report ratings

We report **ratings in aggregate by team**. We don't disclose which rating each individual has given.

<figure><img src="/files/bBjtZ6rl2keLqXdIc1K6" alt=""><figcaption></figcaption></figure>

Each response is linked to only one team. If you're a member of multiple teams in the survey's audience, you can choose your primary team when starting the survey.

<figure><img src="/files/eazt22MvIxrKOqW1HVnJ" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
In some cases, such as very small teams, **inferring identities from team aggregates** might be possible.

If your team is part of a **higher-level team**, you can choose to record your response to it (as long as the survey creator has included it in the audience).

You can **skip individual questions** if you don't feel comfortable answering them.
{% endhint %}

## How we report comments

Comments are a way to contribute your improvement ideas related to the survey's themes. You can **choose whether to link your name to each of your comments**. We recommend commenting with your name to foster more open and actionable discussion.

If you don't want to associate yourself with a comment, you can tick the ***Hide my name*****&#x20;checkbox**.

You can add **both comments with and without your name** to the same question. You'll see a **preview of how each comment will be shown** in the survey results.

<figure><img src="/files/j99LAsunGEqCTT0dqRJz" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
Even if you choose to hide your name from a comment, we still **show it comes from your team**. In some cases, such as very small teams, it might be possible to **guess who gave the comment**.

It might also be possible to **identify you based on your writing style**.
{% endhint %}


# Survey communication guide and templates

You can use this messaging sequence and templates to communicate your developer experience survey to your teams.

Good communication is crucial for successful surveys. You need to make the target audience aware of the survey's existence, understand the logistics, and be convinced it's worth responding. Importantly, people must understand why you're running the survey and what you're going to do based on the results. Communication failures often manifest as low response rates which yields you less representative data.

Here's our recommended messaging sequence along with some templates you can modify to suit your needs.

## 📣 Before the survey

### **Pre-informing team leads**

Team leads play an important role in encouraging their teams to respond and make sense of the survey results. That’s why we recommend engaging them separately throughout the journey.

**To team leads:**

> Heads up!
>
> We’ll run a developer experience survey with Swarmia on `[dates]`. It will give us a better picture of how we’re doing across the organization and where we can improve. As a manager, you should find this data particularly useful for guiding discussions, improving ways of working, and increasing team engagement.
>
> The survey will influence our engineering priorities, so it’s important for us to get a representative sample. I’d appreciate your help in getting everyone on your team to respond.
>
> 👀 **Please do this now:** Check that your team’s information in Swarmia is up-to-date: [app.swarmia.com/settings/teams](https://app.swarmia.com/settings/teams)

### **Introducing the survey to engineers**

People often miss individual messages, so we recommend using multiple channels to inform them about the survey. One good place for this would be an engineering all-hands meeting. Communicating before the survey is open can help you explain its importance and build a bit of anticipation.

**To everyone:**

> 🤠 Hi all,
>
> As you know, developer experience is a big priority for us. We want to understand what’s causing you friction and where we can improve. Thus, we’re running an engineering survey with Swarmia on `[dates]` to gather your feedback.
>
> I want to highlight that we’re not collecting data just for the sake of it, but we’ll take action based on the results, both in teams and at the company level. I’m asking everyone to take a few minutes to respond so we can find out what’s working, what’s not, and where you’d like to see improvements.
>
> I’ll send you more detailed instructions once the survey is live.

***

## 🗳️ During the survey

### **Announcing the survey**

We recommend explaining at least the following when announcing the survey:

* why are you running the survey
* how to respond
* who will see the responses
* what will you do after the survey closes

When you launch your survey in Swarmia, we automatically generate a message template with all the necessary details filled in.

<figure><img src="/files/IGEs4x2bcYiaCHM51ot0" alt=""><figcaption></figcaption></figure>

### **Automatic reminders**

Swarmia notifies people on Slack 1 hour after you launch the survey. People who haven't responded will be reminded about 7, 3, and 1 day(s) before the survey closes. (Reminders are only sent on weekdays. You can see the exact times when creating a survey.)

<figure><img src="/files/94KNcFDodvgzGWF94MOP" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/HaHWWvcLoULdGM8xaph1" alt=""><figcaption></figcaption></figure>

### **Reminding team leads to activate their teams**

While Swarmia automatically sends reminders to people, there’s a chance some people don’t notice them for one reason or another. Reminding people personally can make them feel more accountable.

<figure><img src="/files/47AgTzeR2FIECv6Y3RmX" alt=""><figcaption></figcaption></figure>

You can see the detailed participation in each team by clicking the participation cell in the survey listing. This can serve as a conversation starter.

**To team leads:**

> Hi again,
>
> Our survey is well underway, but we need more responses to hit our target of 90%. Teams `[teams with the highest participation]` are setting an example for others. I need your help getting everyone to respond.
>
> ⏳ **Please do this now:** Check your team’s participation and remind people to take the survey. You can see the live numbers here: <https://app.swarmia.com/surveys>

***

## 📊 After the survey

### **Informing team leads about the follow-up**

Team leads play an important role in ensuring their teams take action based on the survey results.

**To team leads:**

> Thank you!
>
> The survey has now closed, and I appreciate your support in making it happen. Remember to thank people in your team for responding.
>
> The work is not over yet. Next, we'll review the results and take action. Each team is responsible for addressing their specific improvement needs, while we'll address wider issues at the company level.
>
> 📅 **Please do this now:** Schedule a one-hour retrospective to define your team’s focus areas and action points. Post notes from the meeting to `[where to post the notes]`. You can find instructions here: [swarmia.com/blog/developer-survey-retrospectives](https://www.swarmia.com/blog/developer-survey-retrospectives/)

### **Announcing the results**

You, the survey creator, and all Swarmia admins get access to the results when the survey closes. This gives you a chance to prepare some communications before publishing the results to the rest of the organization.

We show you a message template you can copy when you publish the results. We also recommend mentioning:

* Your top 3 findings from the results
* Instructions on what happens next

<figure><img src="/files/3wdy5l7E6cH8JDeWWlo3" alt=""><figcaption></figcaption></figure>

**Automatic results message**

Swarmia automatically sends a Slack message to the survey participants 1 hour after you publish the results.

<figure><img src="/files/YBycoNzKA1U8EmCz6w83" alt=""><figcaption></figcaption></figure>


# Software capitalization

Use developer activity data from Swarmia to generate capitalization reports and blend with cost data.

{% embed url="<https://www.youtube.com/watch?v=yw5JW-tZrZU>" %}

Accounting and engineering rarely meet, but in modern software development organizations, that sometimes becomes a must. When software development costs are treated as long-term assets, it's essential to accurately connect effort with specific projects.

<figure><img src="/files/HsIVzdzHnif72sTt3HlK" alt=""><figcaption><p>How software capitalization works in Swarmia</p></figcaption></figure>

Swarmia helps organizations track and report on capitalizable software development costs with precision:

* We connect data from your Git and issue tracker to accurately understand how developers allocate their time. Data accuracy is ensured because your developers regularly view and verify their activity in Swarmia.
* You can define custom rules to match what work qualifies as capitalizable
* Your finance team can export monthly or yearly software capitalization reports

### Using Swarmia

<figure><img src="/files/yEwd1nrdzQJcPsjUK1bT" alt="Swarmia - Software capitalization"><figcaption><p>Reports on software capitalization based on your Swarmia data.</p></figcaption></figure>

Swarmia automatically generates monthly reports based on developer activity, issue hierarchy, and capitalization rules. You can manually generate data and override the previous snapshot for the given month.

{% hint style="info" %}
This feature is only available for **admin users**.
{% endhint %}

### Setting up your categorization

Software capitalization reporting can be configured by categorizing issues manually or setting issue filters to categorize them automatically. You may even use a combination of these.

{% hint style="info" %}
Remember that only work linked to issues can be capitalized. If much of your organization's effort involves unlinked pull requests, consider creating issues and linking them to enable capitalization.
{% endhint %}

#### Manual categorization

Manual categorization works well if you capitalize a small number of large projects annually. These projects are easily identified in the [**work tab**](https://app.swarmia.com/capitalization/work) and marked "Capitalizable." When you categorize issues manually, you'll see a small hand icon next to the category.

<figure><img src="/files/lgzLekTCfw8wENY4emiy" alt=""><figcaption><p>The work tab shows all issues for the year grouped by the highest level.</p></figcaption></figure>

#### Automatic categorization

Automatic categorization works best if you already have clear categories in your issue tracker and want to transfer them to Swarmia. On the [**setup tab**](https://app.swarmia.com/capitalization/setup), you'll find a section called "Rules for software capitalization," where you can configure filters to identify capitalizable work.

<figure><img src="/files/FxZVIggkUSlXd1HkX4Sz" alt=""><figcaption><p>A typical way of doing automatic categorization is via a Jira custom field connected to capitalizable initiatives or epics.</p></figcaption></figure>

### Reviewing your capitalizable work

Swarmia gives you two different ways to review your capitalization data before exporting.

The [**work tab**](https://app.swarmia.com/capitalization/work) allows you to examine issues and see how much of each is marked as capitalizable. The issues are grouped at the highest level, which means the capitalization percentage represents how much of the work grouped underneath is capitalizable.

If you've set automatic categorization rules and see a lower-than-expected capitalization percentage, it is likely because child items do not match your rules.

The [**employees tab**](https://app.swarmia.com/capitalization/employees) shows individual contributors and their respective capitalization percentages. This means how much of their total accumulated effort is directed towards capitalizable issues. This view also shows excluded days (time offs and inactive days), which lower a contributor's accumulated effort. You can find more on this topic in [the effort article](/definitions/developer-effort-ftes).

### Building reports

Once you've categorized work (either manually or automatically), reports will automatically be generated and delivered to the [**reports tab**](https://app.swarmia.com/capitalization/reports). In this view, you'll find monthly and yearly exports. The exports are split into employees (yearly) and capitalization (yearly/monthly) files.

You can use these files as raw data or alternatively, compile them into a capitalization report using our reporting template. To use the reporting template, copy it by clicking the "Copy reporting template" button on the reports tab and follow the instructions inside.

### **Frequently asked questions**

**Q: Can the work be aggregated by a specific Jira issue type in the software capitalization report?**

**A:** It's not possible right now, but we're going to add support for this in the future. Currently, the work is aggregated by the highest-level issue that we can find from your Jira issue hierarchy. However, you can already see the FTE values for any of your issues from Swarmia's UI.

**Q: Can I capitalize unlinked pull requests?**

**A:** No. Software capitalization only accounts for work linked to issues. We require each line item in your capitalization report to have proper documentation in the form of an issue. If you have significant effort in unlinked pull requests, consider creating issues and linking them to enable capitalization.

**Q: What's the optional "additional info" field in software capitalization settings?**

**A:** It is an extra column in the work export that provides more context about the capitalizable project (e.g., the reason for capitalization, and the capitalization date).

Concretely, it's a field in your Jira issues, e.g. a label or a custom field, that's pulled to the capitalizable work export as a separate column. It can be used for custom reporting purposes if you don't prefer to use software capitalization reporting template.

**Q: Can I convert the software capitalization reporting template to a .xlsx file?**

**A:** It's not possible right now as some of the formulas used in the Google Sheet reporting template are not available on Microsoft Excel. We're planning to build a reporting template for Excel in the future.


# Timesheets

Timesheets help your organization record, approve, and export hours at the daily and individual level without manual tracking during work.

{% hint style="info" %}
Swarmia Timesheets is currently in closed beta. If you are interested in enabling the feature for your organization, please contact your account manager or <hello@swarmia.com>.
{% endhint %}

### Overview

<figure><img src="/files/p6uhtzliab2RBr7gcG48" alt=""><figcaption></figcaption></figure>

Swarmia automatically generates daily timesheets for every developer that can be edited and approved for compliance.

#### **Who is it for?**

Timesheets are designed for organizations that need to track and approve hours at a daily level for reporting purposes. The primary use case is compliance with **R\&D tax credit systems** and government R\&D subsidies, including:

* [**WBSO**](#what-is-wbso) (Netherlands)
* **SR\&ED** (Canada)
* **CIR** (France)
* **R\&DTI** (Australia)
* **Forschungszulage** (Germany)
* **State R\&D tax credits** (US)

#### **Key features**

* **Automated time allocation:** Swarmia analyzes development activities from your integrated tools (like Jira and GitHub) and converts them into daily hours for each person. The system includes special tracking for activities like debugging or research that don't generate Git activity.
* **Timesheet view:** This view shows a daily breakdown of hours worked by each team member, grouped by epics that are tagged for timesheets. Each row includes the issue key and related initiative for easy reference.
* **Review and edit:** Team admins can manually adjust the auto-populated hours. Any manually changed cells are highlighted to track adjustments.
* **Approval workflow:** Team admins approve their team's timesheets. If a timesheet isn't approved within five days, a reminder is sent to the parent team's admin.
* **Day-off management:** The feature can sync with your HRIS system to account for time off, which can also be marked manually.

### Using timesheets

#### **Getting started**

1. **Enable the feature:** Swarmia Timesheets is currently a feature-gated release. Please contact your Swarmia representative to have it enabled for your organization.
2. **Define rules and tag projects:** The feature identifies work that you want to track in timesheets using issue filter rules, typically based on a custom field in your Jira Epics. For example, a “WBSO Project” custom field can mark epics in your R\&D tax credit program. Swarmia then applies a filter to identify all work linked to tagged epics, automatically categorizing hours for review and approval.
3. **Assign team admin roles:** Assign team admin roles to the managers or leads who will be responsible for reviewing and approving timesheets for their teams. Team admins will be notified when a new timesheet requires approval.

#### Reviewing and exporting

1. **View timesheets:** Once set up, anyone in your organization can visit [app.swarmia.com/timesheets](http://app.swarmia.com/timesheets) to view timesheets. The interface lets you examine all approved hours organization-wide for up to a year, then drill down to specific teams for detailed 2-week periods broken down by individual members. Team view shows both pending and approved hours.
2. **Review & approve:** At the beginning of every two-week period (10 working days), the designated team admin for each team will receive **a Slack notification** to review their team’s timesheet for the previous period.
3. **Export for reporting:** After approval, admins can export the timesheet data as a CSV file, ready for reporting to external reporting (such as tax authorities) or for other internal needs.

### Frequently asked questions

#### How does Swarmia calculate hours?

1. **Daily FTE:** We begin by examining an engineer's work for a full day. We collect data points, including commits, pull requests, and comments. Based on those data points, we divide the full-time equivalent working day (1.0 FTE) between work items, such as different epics or untagged work.
   * Example:
     * Untagged Work: 0.25 FTE
     * Epic 3: 0.25 FTE
     * Epic 1: 0.5 FTE
     * *Note: For WBSO, we group work by tagged epics. Any activity that isn't linked to a tagged epic (e.g., reviewing an unlinked pull request) is categorized as "Untagged Work."*
2. **Conversion to Hours:** Next, we convert these FTE values into hours. We assume a standard 8-hour workday, so 1.0 FTE equals 8 hours per day. The FTE for each task is multiplied by 8 to determine the time spent in hours.
   * Example:
     * Epic 1: 0.5 FTE \* 8 hours = 4 hours
     * Epic 3: 0.25 FTE \* 8 hours = 2 hours
     * Untagged Work: 0.25 FTE \* 8 hours = 2 hours
     * *Note: We round work items to the nearest 30 minutes, ensuring a distribution of 8 hours.*

#### **What is WBSO?**

The WBSO (Wet Bevordering Speur—en Ontwikkelingswerk) is a Dutch tax credit that reduces wage tax and social security costs for employees involved in approved Research and development (R\&D) projects. To comply, companies must maintain and manage detailed daily timesheets for all employees working on these projects.

Timesheets automate this process by generating daily time allocations based on developer activity. Managers are prompted to review and approve these allocations every 10 working days. The workflow in Swarmia is designed to comply with WBSO requirements, and the exports are ready for reporting to the RVO (Netherlands Enterprise Agency).


# Swarmia AI

Swarmia AI lets you ask questions about your engineering data in plain language. Responses can include summaries, tables, charts, and next steps. You can ask follow-up questions, adjust what's shown, and open results in the [Explore view](https://help.swarmia.com/features/metrics/explore) to save them for later.

### Getting started

Two ways to start a conversation:

1. Click **Swarmia AI** in the main navigation to open a new chat.
2. Click **Ask Swarmia AI** from any supported view — Code metrics, Issue metrics, AI adoption, AI impact, Coding agents, or Surveys.

<figure><img src="/files/y1wFLFnII7tgaIr0jJcU" alt=""><figcaption></figcaption></figure>

Starting from a specific view includes that view's context automatically, so you can ask targeted questions about the data in front of you.

### Asking questions

Type your question in plain language. More specific questions get better answers. For example:

* "Summarize our latest survey results and suggest next steps"
* "Why did technical debt increase for the platform team last month?"
* "How are code reviews distributed across the team this quarter?"
* "What's the average PR cycle time per team this month, and which teams are the highest?"
* "How has GitHub Copilot adoption changed over the past 3 months?"

Swarmia AI can analyze both quantitative metrics and qualitative feedback (such as survey comments). It draws on the [Build book](https://www.swarmia.com/build/) where relevant, and can suggest next steps alongside its analysis.

<figure><img src="/files/0PRpqqxO3FAWUo8oMH2n" alt=""><figcaption></figcaption></figure>

### Response format and follow-ups

Responses can include:

* **Summaries** — plain-language analysis and recommendations
* **Tables** — breakdowns by team, person, time period, or metric
* **Charts** — trends and comparisons visualized

After each response, you can:

* Ask follow-up questions to go deeper
* Request a different breakdown (e.g., by team, by author, by time period)
* Add or remove data from a chart
* Open results in the **Explore** view to tweak, save and revisit them

By default, Swarmia AI responds quickly. You can increase the reasoning level to get more detailed analysis — this may take a bit longer.

<figure><img src="/files/xIADaCNNo9gURKrUgMBj" alt=""><figcaption></figcaption></figure>

### Saving results

Any table or chart in a response can be opened in the [Explore view](https://www.swarmia.com/changelog/2026-04-02-explore-view), where you can save it as a custom report to revisit later.

### **Limitations** and approprate use

Results depend on available data — missing or inconsistent data can affect accuracy.

Swarmia AI identifies patterns in engineering activity. It doesn't measure individual productivity, performance, or competence, and its outputs can be incomplete or wrong. Activity counts (such as PRs opened or merged) vary widely with project type, review load, batch size, and role, and do not indicate how well or how much a person contributed.

Don't use Swarmia AI outputs — including any per-person metric, ranking, or comparison — as a basis for decisions about individuals, such as performance reviews, compensation, promotion, discipline, or termination. These outputs aren't designed or validated for that purpose. Use them for team- and system-level insight, and apply your own judgment with full context.

Every AI-generated insight is backed by an explicit data query. Click **Explore** to see exactly what was asked, adjust if needed, and rerun it any time.

### Sharing feedback

Rate each response with 👍 or 👎. For more detailed feedback, reach out to your customer success manager or email <hello@swarmia.com>.


# Developer overview

Visualize engineering work with Developer Overview

Developer overview shows you how individual engineers are spending their time — what they're working on, where they're getting stuck, and how their work connects to team priorities.

<figure><img src="/files/og32EOrEDkHpw3YeWLlL" alt=""><figcaption></figcaption></figure>

## Where to find it?

You can **navigate to Developer Overview by clicking anyone's avatar**.

{% hint style="info" %}
To see your own data, click [My overview](https://app.swarmia.com/overview) under your profile picture in the navigation sidebar.
{% endhint %}

## What does it do?

Developer Overview combines activity from issues and PRs to visualize what each developer has worked on. This aims to surface potential areas of improvement and helps facilitate discussions about work.

The feature allows developers and their managers to:

* **Make work visible.** Identify who the developer has worked with recently, compare the ratio of own pull requests to reviewed pull requests, and navigate to past work items to analyze them in more detail.
* **Visualize activity patterns**. Quickly see all the projects the developer has contributed to and spot systemic issues like too much work in progress or working alone on bigger issues.
* **Analyze focus.** Assess whether the developer has been able to focus on the right things and maximize their learning and impact.

## A view for developers

Developer Overview is not a tool for stack ranking individuals or reducing them into a single number. In fact, the view is first and foremost a tool for developers to learn and grow in their career.

Here are some questions that you might answer with this view:

* Have I been working on the things that I want to work on? Let's say I wanted to work with databases more this year. Did that actually happen?
* How can I justify getting a raise or a promotion? What were the biggest successful projects that I worked on this year that I can bring up to my manager in our performance review?
* Am I reviewing enough pull requests? If I have opened more PRs than I have reviewed, that might not be fair to my team members.
* How can I learn from my mistakes? What were some projects that didn't go so well, and what would I do differently now?
* Who did I work with the most? They are probably the best people to ask for feedback to improve.

## A view for managers

For engineering managers, this view provides a way to reduce personal bias when evaluating someone's performance. It is easy to fall into giving better ratings for people we like when you don't have the hard facts about what they worked on.

Some questions that managers might answer with this view are:

* What projects did this person work on? How much impact did they have on the project, and how well did the project go?
* Are they reviewing enough pull requests? You probably want to distribute pull request reviews evenly among the team when possible.
* Who have they worked with the most? You might want to ask for feedback from these people too to get a full picture of their performance.

## How does it work?

Developer Overview provides three views into data:

* **Activity** provides visibility into the larger projects in your issue tracker that a developer has worked on. This is good for understanding where the majority of their time has gone.
* **Focus** provides visibility into the types of work that a developer has done (by investment category). Have they spent most of their time fixing bugs or building new features? We take no stance here what is the right balance that's specific to your situation.
* **Pull requests** provides easy access to pull requests that a developer has authored and reviewed.


# Notes

You can attach freeform context information to work items like pull requests and issues with notes.

Swarmia supports annotating your work items with notes to provide extra context that might not otherwise be obvious from the data point. For example, you might look at cycle time outlier pull requests, and annotate why the outlier happened.

We will in the UI highlight data points that have notes on them:

<figure><img src="/files/IorYukMqMWOeuw9dfaS2" alt=""><figcaption><p>This PR has one note on it</p></figcaption></figure>

<figure><img src="/files/Wk77ATXUOBa7CzBsf0zA" alt=""><figcaption><p>Work items with notes are highlighted in scatter plots too</p></figcaption></figure>

## Adding notes from the UI

To add notes, simply click on a pull request or issue anywhere in the app to open its popup:

<figure><img src="/files/xL5UlnWDGnkFfRCnNTOi" alt=""><figcaption></figcaption></figure>

## Adding notes from outside of the UI

It's also possible to add notes from outside of the Swarmia UI. Currently, the only place supported is Github pull requests.

Tag the Github bot with `@swarmia <note>` and it will be added as a note to that pull request:

<figure><img src="/files/l9eF4VZkCa1nhdea3rxC" alt=""><figcaption><p>You can tag the Swarmia Github bot to easily add notes while you're working on your pull requests</p></figcaption></figure>

<figure><img src="/files/48IaDEThCnGaSkjA6Tmx" alt=""><figcaption><p>The note becomes visible in the Swarmia UI</p></figcaption></figure>

## Editing notes

Existing notes can be edited or deleted by either:

1. The author of the note
2. Any Swarmia user with the admin role


# Forecast

Predict when work will finish and how much effort is left, using a Monte Carlo simulation of your team's past effort.

A single completion date is a guess. The forecast gives you a range instead. It runs a Monte Carlo simulation over how much effort your team's past work actually took, then projects how much effort is left on a parent issue or initiative and when it's likely to be done.

You get two answers:

* **Remaining effort**, in [full-time equivalents](/definitions/developer-effort-ftes) (FTE), so you can see how big the rest of the work is.
* **Completion dates** at three confidence levels, so you can plan around how likely each date is rather than betting on one.

## Why a simulation

Real work is uneven. Some tasks take an afternoon, others drag on for weeks, and the people doing them aren't always working at full capacity. A simple "average task time × tasks left" estimate hides all of that variation and tends to be optimistic.

Instead, Swarmia looks at how much effort each piece of recent work actually took and recombines those real outcomes across thousands of simulated scenarios. Each scenario draws a different mix of fast and slow tasks, so the result is a spread of possible futures. The dates you see are read off that spread.

## Where to find it

The forecast lives on the overview of a parent issue or an initiative:

* The **Forecast remaining** panel shows the remaining effort and the projected completion date at a glance.
* The **Forecast** button opens the full view, where you can read every confidence level and adjust the assumptions behind the forecast.

<figure><img src="/files/KCbPexgHTwk3vqBDas0e" alt="Forecast remaining panel with a tooltip breaking down the optimistic, likely, and conservative estimates"><figcaption><p>The Forecast remaining panel shows the leftover effort and projected date, and breaks down the confidence levels on hover</p></figcaption></figure>

## Reading the forecast

The forecast view has two halves: the assumptions on the left and the results on the right under **Estimated completion**.

<figure><img src="/files/HhG46vHBoITEIQTTssbb" alt="The Forecast view with scope and investment inputs on the left and estimated completion dates plus the simulated distribution on the right"><figcaption><p>The Forecast view: your assumptions on the left, the estimated completion and simulated distribution on the right</p></figcaption></figure>

* **Remaining** shows the leftover effort as an FTE range, from optimistic to conservative. For example, 1.8–2.2 FTE means the rest of the work is worth roughly two months of one full-time engineer.
* **Likely completion** is the headline date, the one most scenarios land on or before.
* The three confidence levels below it show how the date shifts with certainty:

| Level            | Confidence | What it means                                                                          |
| ---------------- | ---------- | -------------------------------------------------------------------------------------- |
| **Optimistic**   | 50%        | Half of the simulated scenarios finished by this date. A best case, not a plan.        |
| **Likely**       | 80%        | Four out of five scenarios finished by this date. The date to plan around.             |
| **Conservative** | 90%        | Nine out of ten scenarios finished by this date. A safer date to commit to externally. |

Later dates carry more certainty, so the gap between optimistic and conservative tells you how predictable the work is. A wide gap means the past effort varied a lot and the finish date is hard to pin down. A narrow gap means the work has been steady.

**Scope simulation results** plots the full distribution of remaining effort, so you can see the most common outcomes and how long the tail of slower scenarios runs.

## Adjusting the forecast

The forecast starts from sensible defaults, but you can change any assumption to test a scenario. Nothing you change here is saved to the issue or initiative.

* **Scope → Remaining** is the number of open subtasks left to complete, counting the lowest-level tasks only. Override it to model adding or cutting work.
* **Investment → Contributors** is who's doing the work. Switch between **People** and **Teams** to pick individuals or whole teams. The forecast draws on these contributors' own past effort, both to size the remaining work and to pace it, so changing who's selected shifts the result even when the scope stays the same.
* **Focus** controls that pace. **Based on past activity** uses each contributor's recent monthly effort. Switch to **Custom** to set a percentage of capacity, for example 60% if the team is splitting attention with other work.
* **Advanced → Sample data** is the window of history the simulation draws from, six months by default. Widen it for a longer-running team, or narrow it if recent work is more representative of what's ahead.

On an initiative, you can select **Set as target date** to set the initiative's target to the likely completion date. This is available if your role lets you [manage initiatives](/settings/organization/managing-users-and-roles).

## What good looks like

* **Plan around the likely (80%) date, commit externally to the conservative (90%) one.** The optimistic date is a best case, useful for spotting upside but risky to promise.
* **Watch the spread, not just the date.** A wide gap between optimistic and conservative is a signal that the work is unpredictable. That's worth a conversation before it's worth a deadline.
* **Re-run it as work lands.** The forecast updates as tasks close and effort accrues, so a date that keeps slipping points to scope growth or a drop in focus, both of which you can see by adjusting the inputs.

## Requirements and limitations

* The forecast needs **recent effort history** from the selected contributors. With no history in the sample window, there's nothing to simulate and no date can be projected.
* It counts **leaf subtasks only**, the lowest-level issues with no children. Parent issues don't add to the remaining count.
* **Review-only participation isn't counted** toward the pace. A contributor who only reviews code doesn't move the burn rate.
* If the remaining effort outpaces the team's investment, the forecast shows **10+ years** rather than a date. That usually means too few contributors, too little focus, or not enough history to go on, not a literal decade.
* Completion dates assume **no weekend work**, so a date landing on a weekend moves to the following Monday.
* The forecast is available for **all types of in-progress initiatives and in-progress parent issues**.

## Frequently asked questions

### Why does the forecast change when I select different contributors?

The simulation draws on the selected contributors' own past effort, so who you pick shapes the result even when the number of subtasks stays the same. Their typical effort per task sets the size of the remaining work, and their recent monthly pace sets how quickly it gets done. Selecting more contributors, or ones who've been more active, raises the projected pace and pulls the date earlier.

### What counts as remaining work?

Open leaf subtasks, the lowest-level issues that aren't yet done. You can override the count under **Scope** to test what adding or removing work does to the forecast.


# Identify and improve delivery bottlenecks

Delivery bottlenecks slow down feedback loops, delay releases, and make work feel less predictable. They often show up as pull requests that wait too long for review, issues that stay in progress for days or weeks, large batches of code, too much work in progress, or repeated interruptions from reactive work.

Swarmia helps you identify where work slows down by combining code metrics, issue metrics, benchmarks, working agreements, notifications, and day-to-day pull request visibility. The goal is not to inspect individual engineers, but to help teams spot patterns in their workflow and improve together.

### Spot bottlenecks in your metrics

Start by looking at your team’s delivery flow. In [**Code metrics**](https://help.swarmia.com/features/metrics/code-metrics), follow pull request cycle time, batch size, review time, and the number of pull requests in progress. In [**Issue metrics**](https://help.swarmia.com/features/metrics/issue-cycle-time), look at how long issues spend in progress and whether work is waiting, blocked, or split across too many priorities. Use [**benchmarks and comparisons**](https://help.swarmia.com/guides/benchmarks-and-comparisons) as directional guidance to see which parts of the workflow may need attention, but focus first on improving from your own baseline.

### Drill into the underlying work

When you find a bottleneck, drill into the underlying work. Look for pull requests or issues that took much longer than usual, then ask what they have in common. Common causes include too much work in progress, large pull requests, slow or inconsistent reviews, unclear ownership, cross-team dependencies, manual testing or deployment steps, and reactive work taking time away from planned work.

### Set shared expectations with working agreements

Once you understand the pattern, agree on one improvement to try. For example, you might set a working agreement to keep pull requests below a certain batch size, review pull requests within a few working days, limit the number of open pull requests, or reduce issue cycle time by limiting work in progress. Team notifications and daily digests help keep these agreements visible, while personal Slack or Microsoft Teams notifications make sure pull requests do not sit waiting for review, comments, or failed checks.

### Manage day-to-day delivery with the PR inbox

Use the [**PR inbox**](https://help.swarmia.com/features/managing-pull-requests-in-progress-with-the-pull-request-view) to stay on top of day-to-day delivery. It shows what is in progress, what is waiting for review, what is ready to merge, and what may be going stale. Closing or merging old pull requests can also help the team start from a cleaner baseline before focusing on new work.

For many teams, the fastest improvements come from keeping batches smaller, reviewing code sooner, and reducing the amount of parallel work. Smaller pull requests are easier to plan, review, and deploy. Faster reviews reduce waiting time. WIP limits help engineers focus and make it easier to finish work before starting more.

### Address broader workflow constraints

If pull request flow looks healthy but delivery is still slow, look at issue cycle time and broader workflow bottlenecks. Long-running issues may point to unclear priorities, large work items, dependencies outside the team, knowledge silos, too many meetings, or manual work and toil. Discuss these patterns in retrospectives and use Swarmia’s data to decide what to improve next.

### Build a habit of continuous improvement

Delivery improvement is an ongoing process. After one bottleneck improves, keep monitoring it so the team does not slide back, then move on to the next constraint. Over time, clear visibility, shared expectations, and regular team discussions help teams deliver in smaller increments, reduce waiting, and ship valuable work more predictably.


# Understand how engineering time is spent

Engineering teams balance roadmap work, maintenance, support, incidents, technical debt, and internal improvements every day. Without visibility into where time actually goes, it becomes harder to set realistic goals and keep the team focused, and reactive work can consume more time than expected.

Swarmia helps engineering organizations understand how engineering time is spent so teams can make better prioritization decisions and align engineering effort with strategic goals.

### Start with the focus summary

A great place to start understanding how your team spends their engineering time is the [focus summary](/features/focus/focus-summary).

<figure><img src="/files/Ty0yZ1vmFnmzoHfntMdk" alt=""><figcaption></figcaption></figure>

It gives you an overview of how engineering effort is distributed across teams, projects, and investment categories over time — measured in developer effort (FTE months).

Compared to relying only on an issue tracker, the focus summary reveals where attention goes when many things are in progress at the same time.

This helps answer questions like:

* Are the projects you expect to be in focus actually getting worked on?
* How much time goes to roadmap work versus maintenance?
* Are support requests and incidents consuming increasing capacity?
* Which initiatives require the most engineering investment?

If you’re new to FTE-based reporting, see [Developer effort (FTEs)](/definitions/developer-effort-ftes).

### Understand your engineering investments

Once work is visible, you can evaluate whether engineering effort aligns with your organization’s priorities. [Investment balance](/features/focus/balance-engineering-investments) helps you categorize work according to your strategy and focus, and monitor it over time.

Many teams discover that reactive work — bugs, support, interruptions, and maintenance — gradually consumes more time than expected, making it harder to sustain strategic initiatives.

Swarmia helps you:

* Track the balance between roadmap work and KTLO (“keep the lights on”) work
* Understand how investment patterns change over time
* Compare focus areas across teams

### Understand your strategic initiatives

Some projects are more important than others. [Initiatives](/features/focus/deliver-strategic-initiatives) bring together those strategic, cross-team projects most important to your organization. These projects are often difficult to capture fully in your issue tracker because they span teams and boards.

Swarmia helps you:

* See all the work currently underway in an initiative
* Ensure that strategic projects don't lose steam and that target dates are met
* Forecast when work is done

### Understand the day-to-day

Engineering work doesn’t always happen inside planned roadmap tickets. Interruptions, reviews, production issues, and context switching often stay invisible in traditional project tracking.

[Work log](/features/focus/analyzing-the-activity-patterns-on-work-log) helps teams understand how work actually happens day to day by combining pull requests, issue activity, and collaboration patterns into a single timeline.

This makes it easier to spot patterns like:

* Excessive multitasking
* Frequent interruptions
* Teams spreading effort across too many projects
* Long-running projects losing momentum

### Understand focus during sprints

For teams using sprint-based planning, the [sprints](/features/focus/sprints) view helps visualize sprint-to-sprint performance.

You can understand:

* How much of the commitment gets completed
* How much work gets added after a sprint starts
* Whether teams can protect focus during execution

### Turn visibility into better decisions

When you know where engineering time goes, it’s easier to plan and prioritize.

Teams can protect time for important work, cut down on interruptions, keep maintenance and new work in balance, and ensure engineering effort supports business goals. This helps teams make better tradeoffs and stay on mission. That is what Swarmia's focus features are all about.


# Improve pull request flow

Get visibility into your team’s pull requests and the contributing factors behind cycle time: the number of pull requests in progress, batch size, and review time.

{% embed url="<https://www.youtube.com/watch?v=TR4Y7Uej1_0>" %}

Your ability to get code quickly to production translates to faster feedback loops, which in turn helps you build the right things faster. “Lead time for change” is one of the [DORA metrics](/definitions/dora-metrics), and it’s shown to correlate with better business performance. “Pull request cycle time” is one part of the “Lead time for change” metric, making it easier to improve and less susceptible to variations in deployment infrastructure.

The cycle time is a systemic measure that’s affected by things like:

* Code review process
* Manual testing process
* Amount of multitasking
* Dependencies
* Domain knowledge

It is not an individual productivity metric. Cycle time for your most senior developers might be higher than for your junior developers, if one is working on your most challenging migration projects and the other is making copy changes to the website.

<figure><img src="/files/Zehb0f03YiJEEC7TDs1h" alt=""><figcaption><p>Team pull request inbox</p></figcaption></figure>

## Prerequisites & Setup

Being able to improve cycle time only requires the basic Swarmia configuration:

* GitHub connected
* At least one team created

To use the Slack or Microsoft Teams notifications, you’ll also need to [connect your Slack workspace](/settings/integrations/messaging-apps/slack) or [Microsoft Teams organization](/settings/integrations/messaging-apps/microsoft-teams).

## Using Swarmia

To get a high-level overview of which teams might have a cycle time problem, start by looking at the organizational metrics.

<figure><img src="/files/MXMpq9cxS4rx5ujVYZhn" alt=""><figcaption><p>Organizational metrics</p></figcaption></figure>

To truly diagnose issues, you’ll need knowledge about the work itself. The team is best equipped to analyze its own work using one of the drill-down views.

<figure><img src="/files/YtfBjXajRw98ohlZzGeN" alt=""><figcaption><p>Cycle time insights</p></figcaption></figure>

Look at the pull requests that are taking the longest to merge, and see if you can spot a pattern. Click the pull request open to get more details, and see how much time it spent in different process stages.

When you discover an outlier, add a note on it using [Notes](/features/notes).

<figure><img src="/files/XrabJnxw4P22VNu9R6lb" alt=""><figcaption><p>Selecting a pull request in Swarmia</p></figcaption></figure>

To diagnose WIP (work in progress) or cross-team dependency issues, go to the pull requests page to see the work that’s currently in progress.

Look at the code review statistics, and see if pull requests between teams are treated differently. Use the pull requests page to see incoming review requests in a clean inbox-like view.

Try to close or merge any old stale PRs. If there are too many of them, exclude them from metrics to start from a clean slate, and try to keep it that way.

<figure><img src="/files/Zehb0f03YiJEEC7TDs1h" alt=""><figcaption></figcaption></figure>

Sometimes high cycle time may indicate a team collaboration issue, such as siloing. In Work Log, you can see all coding contributions (including pull requests, reviews, commits, and comments) grouped by project or by contributor.

<figure><img src="/files/Wf4xQCvW7Y7t8c1wuKch" alt=""><figcaption><p>Work log by issue</p></figcaption></figure>

<figure><img src="/files/7VOedhuN0lLBwop0VSZj" alt=""><figcaption><p>Work log by author</p></figcaption></figure>

See Work Log’s bottom lanes for *bugs* and *other work*. Sometimes just keeping the lights on will keep your team busy.

<figure><img src="/files/87kkJvAsSykcXxL2yHH4" alt=""><figcaption></figcaption></figure>

You can also check your [investment balance](/features/focus/balance-engineering-investments) for the amount of Keeping The Lights On (KTLO) work.

Smaller changes are easier to review and less risky. To make small changes, you might need to consider your Git branching strategy (optimally trunk-based) and enable infrastructure such as feature flags. In Swarmia, you’ll find a page dedicated to analyzing pull request batch size.

<figure><img src="/files/t3LabZvAn6rsRVo2r23K" alt=""><figcaption><p>Batch size insights in Swarmia</p></figcaption></figure>

## Taking action

One of the best ways to accelerate code to production is to create awareness of the current status of pull requests. You can do this by getting the team to adopt:

* Pull request view to see the current “inbox” of your team
* Slack or Microsoft Teams notifications for getting timely notifications of what should be done
* Digests for Slack and Microsoft Teams reminding the team about the work on a weekly or daily basis
* Working agreements for defining how you’d like to split work into small increments
  * Merge pull requests in X days
  * Review pull requests in X days
  * Limit the number of pull requests in progress to X days


# Pull request insights

Diagnose cycle time issues, decrease review time and improve pull request workflow with Swarmia's pull request insights.

Getting high-quality data about your pull request workflow is the first step to a better understanding of process changes that improve velocity and quality — and our [**pull request insights**](https://app.swarmia.com/insights/code/overview) are here to help. Here are some highlights to get started:

<figure><img src="/files/AUgKHiC5ESQ2vDZuYLrU" alt="" width="375"><figcaption></figcaption></figure>

*Cycle time average* graph (top graph) shows how long it generally takes you to close pull requests, and how the situation develops over time. If you close pull requests timely, it trends down. Pull requests left open for several days result in an upwards trend. Aiming to close all pull requests in under a week (or 1–2 days on average) is a good starting point for continuous delivery. Now let's look into what contributes to cycle time.

Cycle time is influenced by many factors. *Pull requests in progress* graph (bottom graph) gives a clue into how your ability to close pull requests is affected by the number of pull requests worked on at once by the team. Working on too many pull requests at once can result in longer delivery times, and we recommend adding a [**work in progress limit**](https://app.swarmia.com/working-agreements/921c5965-1fa0-4042-99f1-62e289f848e3) to make sure pull requests don't pile up slowing the team down.

<figure><img src="/files/5z1QXMSqYrT1cGNReWsa" alt=""><figcaption></figcaption></figure>

*Cycle time distribution chart* (on the right) shows what portion of pull requests takes longer than expected to complete, and individual pull requests are shown in the scatter plot on the left. Pull requests far above the rolling average line need special attention — it's the code that's been waiting for the longest to be delivered.

<figure><img src="/files/8tNcbiwnuDZi0f2FwzWT" alt=""><figcaption></figcaption></figure>

Filter the *pull request view* by status, repository, or author (by clicking the filters next to the team name) to identify problematic pull requests. Filters are applied to the table as well as the charts above it.

<figure><img src="/files/jkOktMMsOjveUsPAAcKd" alt=""><figcaption></figcaption></figure>

*Review time* is another important contributing factor to cycle time. Sorting the table by review time helps to identify pull requests that spent the longest in review — or were merged without review at all. The number of pull requests merged without review is reflected in the *review rate* above the chart.

Once you've identified patterns in your pull request workflow, consider discussing the following [**working agreements**](https://app.swarmia.com/working-agreements) with the team:

* Work in progress limit for pull requests (e.g. we don't leave more than 10 pull requests open at once)
* Cycle time target (e.g. closing pull requests in under 7 days)
* Review time limit (e.g. reviewing pull requests in under 48 hours)


# Reducing pull request cycle time

Get pull requests through faster with Swarmia's insights and working agreements around cycle time.

*Cycle time* is one of the key metrics to consider in an engineering team. Originally borrowed from lean manufacturing, in software development it serves as a rough measure of development speed and shows how long it takes for code to complete all stages of the software development pipeline.

### Why care about cycle time?

Measuring and improving cycle time means delivering software to end-users faster, shipping in small batches, and reducing the risk of code getting stale. Cycle time is also an important indicator of business success. In their book, Accelerate, the authors of influential [**yearly DevOps reports**](https://services.google.com/fh/files/misc/state-of-devops-2019.pdf) have found a direct connection between cycle time and innovation, competitiveness, and organization efficiency.

Lower cycle time means:

* Shipping in small batches without interruption
* Getting feedback from end users faster
* Reducing risk and overhead
* Reviewing and merging new code timely

In Swarmia we show both pull request cycle time and issue cycle time, as this is the section that developers are able to affect (in comparison to lead time for changes).

### How is pull request cycle time measured in Swarmia?

In Swarmia, pull request cycle time is the total time pull requests spend on all stages of the development pipeline. In practice, it's a sum of three components:

* **Time in progress** — from the 1st commit *to* review request or from when the pull request is opened *to* review request, whichever happens first
* **Time in review** — from review request to approval
* **Time to merge** — from approval to merge

<figure><img src="/files/8iHu0M8y7i2MTBLcFuvC" alt=""><figcaption></figcaption></figure>

In PR Inbox, cycle time is projected live for every pull request, both open and merged. For open PRs, the clock keeps running, so their cycle time grows day by day until they're merged or closed. This helps you spot aging PRs before they become a problem.

In Code Metrics (the cycle time trend), the aggregated average only includes PRs that have been closed or merged. Open PRs don't contribute to the trend. Their cycle time only appears once they finish. So closing pull requests timely will bring the trend down, while letting PRs stay open for a long time delays their impact on the metric until they finally close.

In terms of pull request cycle time, Swarmia has a few useful views for you to observe. First, the [**code insights overview page**](https://app.swarmia.com/insights/code/overview) shows you the weekly aggregate PR cycle time average over the chosen timeframe. Secondly, the [**pull request cycle time page**](https://app.swarmia.com/insights/code/cycle-times) has a scatter plot graph which helps you go deeper and identify reasons for changes in cycle time.

### What's a good cycle time?

According to the authors of Accelerate, “elite” teams reach a cycle time of less than a day, while high-performing teams deliver code in under 7 days on average.

Use [**pull request insights**](https://app.swarmia.com/insights/code/cycle-times) to look into cycle time and other pull request metrics in Swarmia.

### **What contributes to cycle time?**

Let's consider the key factors contributing to cycle time, and how you can impact them. Among others, we suggest focusing on the following:

* **Work in progress queue** Working on too many pull requests at once often correlates with longer delivery times. Use Swarmia's WIP working agreement to agree on a target with the team (e.g. up to 10 pull requests open at once) and keep track of it over time.
* **Time in progress** Shorter *in progress time* means focusing on splitting work into smaller batches that are easy to plan, review and deploy.
* **Time in review** Creating smaller pull requests that are easy to review, using code owners in Github to assign reviewers automatically once a pull request is open are some ways to lower review time.
* **Pull request size** Smaller pull requests are easier to plan, review and deploy.
* **Time to merge** Making approved pull requests a priority, agreeing on merge rituals with the team (Who has the responsibility to drive the pull request forward? Who can merge code?), and investing in production infrastructure helps to reduce waiting time between approval and merge.

### Lowering cycle time with Swarmia

#### **Start with a clean-up**

If measuring cycle time wasn't ever a priority, there are likely some very old pull requests waiting to be closed. Use Pull Request overview to identify old pull requests and decide what to do with them.

To get a more relevant view of your data, [**exclude**](/settings/organization/pull-request-data-quality) outlier pull requests from all metrics. This lets you focus on lowering cycle time for newly opened pull requests.

You can bulk exclude all pull requests that have been open for a month or longer, or archive individual ones. We recommend starting with the bulk exclusion, as you can include any excluded pull requests back into metrics later.

#### **Adopt a working agreement**

Once you've identified cycle time as an improvement area, look at the Pull Request insights together with the team:

* Decide what a realistic maximum target is (7 to 14 days is a good starting point).
* Adopt the "Merge pull requests in less than X days" working agreement in Swarmia to track progress towards the target and to receive feedback on outliers.
* To address specific issues contributing to cycle time, consider adopting a [**work in progress target**](https://app.swarmia.com/working-agreements/explore/wip-pull-requests), [**maximum batch size target**](https://app.swarmia.com/working-agreements/explore/batch-size), and an agreement measuring [**review time**](https://app.swarmia.com/working-agreements/explore/max-pull-request-review-time) specifically.

#### **Build a feedback loop**

Enable [**Swarmia's daily digest**](https://help.swarmia.com/team-notifications#daily-digest) in Slack or Microsoft Teams to get a daily reminder about pull requests not adhering to the agreement. Check [**Pull Request overview**](https://app.swarmia.com/pull-requests/our-team) regularly with the team to spot emerging coding patterns early and close pull requests before they get old and stale.


# Review code faster

Code rarely ages well, and merging doesn’t get any easier over time. Here's how Swarmia helps your team get pull requests through faster.

### **Going faster helps the team**

Pull requests stick around for many reasons. Some are just too big, or the reviewer isn’t familiar with the context or the codebase. Sometimes reviewing and merging is thwarted by poor planning or lack of infrastructure, and often it’s just a case of poor visibility into review requests. Bottlenecks abound for pull requests, one of the most common being the code review.

Reviewing code quickly as a team comes with multiple benefits. Developers expand their comfort zone, the codebase becomes more robust, there’s a more frequent sense of accomplishment, and new features can be shipped faster. No matter the reasons for stuck pull requests, reviewing code without delay is always a good idea, and it’s always a challenge you must address as a team.

By managing the amount of work in progress and code review time, teams can significantly accelerate their pull request cycle times. After getting into the habit of quick code reviews, teams can expect to close 80% of pull requests within 48 hours, and rarely have to deal with pull requests older than 14 days.

### **Check the current situation**

Lack of visibility is a common cause for stuck pull requests. Swarmia's [Pull Request view](https://app.swarmia.com/pull-requests) gives a quick overview of what’s going on, and the charts give an idea of team throughput and bottlenecks. Getting in the habit of checking the [Pull Request view](https://app.swarmia.com/pull-requests) from time to time goes a long way to ensuring that pull requests are moving.

<figure><img src="/files/tfASvaanPyjY5fcK4lvZ" alt=""><figcaption></figcaption></figure>

The above Pull Request view tells you a lot about your situation. A large number of pull requests in progress is often a sign of a problem, and being able to see pull request ages helps you to understand its magnitude. The graphs above your pull request inbox give insights about cycle time and pull request throughput trends over time.

It’s normal that pull requests sometimes sit for a day or two before merging, but if many of your pull requests are weeks old, it’s time to dive deeper.

### **Investigate throughput and trends**

Before jumping into Swarmia’s [Working Agreements](https://app.swarmia.com/working-agreements) to set throughput targets for your team, it’s worth the time to investigate past performance and estimate sustainable levels of throughput going forward.

[Flow Insights](https://app.swarmia.com/insights/flow/pull-requests) is a good way to take a look at the pull request conundrum over a longer period. By reviewing past work in progress and cycle times, you can spot trends and begin to estimate realistic targets for future throughput. Importantly, pull request review time is often a reliable leading indicator of total cycle time.

<figure><img src="/files/klnnYK9VyiQNlDOm9sRg" alt=""><figcaption></figcaption></figure>

In the above example, it looks like median review and cycle time are quite healthy, but there are plenty of outliers with high review times and cycle times. According to the *Review Times* scatter plot, a handful of pull requests have been waiting for review for quite some time, and while there are lots of pull requests assigned to other teams for review, they seem to be done quickly and are not the bottleneck. So, it looks like there are issues with code review that are worth addressing as a team!

Based on your team’s throughput over time, come up with an ambitious but realistic goal for pull request review time. Can you think of any reason why code reviews should take longer than three working days to complete? Talk it over with the team and stakeholders, and make sure to explain that reviewing code faster is a big step towards delivering features faster.

### **Zero in on code review**

For most teams we see, code review is the bottleneck where progress stalls and throughput falters, making pull request review time a reliable leading indicator of total cycle time. Improving your team’s code review practices will go a long way towards speeding up pull request cycle times and improving team dynamics as a whole.

To get started with improving your code review time, head over to [Working Agreements](https://app.swarmia.com/working-agreements) and adopt a new agreement to review pull requests within a few working days, according to the analysis you’ve just made.

<figure><img src="/files/qSg9zrZOnxoBLtBagMKY" alt=""><figcaption></figcaption></figure>

After configuring and adopting the new working agreement, outliers become clearly visible in context, exceptions from the past two weeks are spelled out, and the scatter plot highlights delays caused by cross-team collaboration.

<figure><img src="/files/29wosDmVJlrEitSLjBvD" alt=""><figcaption></figcaption></figure>

In your next retrospective, review the list of exceptions together as a team. What made these pull requests so special? Getting in the habit of analyzing exceptions in retrospectives is all but guaranteed to regularly surface actionable insights about your process and lead to real improvements.

**💁‍♀️&#x20;*****Review exceptions in retrospectives.*****&#x20;Regularly going through recent exceptions to working agreements with your team is a great way to uncover insights about what’s holding you back and to systematically improve your review habits.**

### **Increase visibility**

While it’s important to analyze the reasons behind stuck pull requests in retrospect for systemic improvement, identifying and addressing problems right away can have an immediate impact on cycle times. Swarmia’s Slack and Microsoft Teams notifications help your team preempt delays by increasing the team’s visibility into review requests, and detect problems as soon as they occur.

Encouraging team members to connect their personal Slack or Microsoft Teams accounts, as well as connecting your team’s notification channel in Swarmia, are great ways to increase visibility into review requests. When a review is requested from the team or an individual, Swarmia sends a notification either to the team’s channel or as a direct message.

<figure><img src="/files/yq0XO72F3uyaWVKUzuVV" alt=""><figcaption></figcaption></figure>

To avoid redundant notifications, the original message is simply struck through after the review is completed and the pull request is merged.

<figure><img src="/files/76hf58HDQMJ7TWhEANXx" alt=""><figcaption></figcaption></figure>

Despite increased visibility, delays in reviews are bound to happen. To catch problems as they occur, set up the daily Slack or Microsoft Teams digest for your team to understand what’s in progress and which pull requests need attention, and get timely feedback about working agreements that are slipping.

<figure><img src="/files/W6E2v5DQFtNM6n5gEAO4" alt=""><figcaption></figcaption></figure>

Exceptions in the digest are your cue to revisit the Pull Request view, check which pull requests are problematic and have a short conversation as a team about what’s actually going on. Often getting unstuck is as simple as properly assigning the task or asking a quick question!

### **Next steps**

When it looks like you’re consistently hitting your code review targets, it’s a good idea to dive deeper into the pull request cycle time, and explore issues of focus and work in progress. We recommend arranging a team discussion about limiting the amount of pull requests in progress at a given time, for which there is its own Working Agreement, as well as setting targets for pull request cycle time as a whole.

As you go on, the conversations you will have with your team about exceptions will help you surface all manner of improvements and spur you along on the path of continuous improvement. Good luck!


# Diagnosing low pull request throughput

Throughput is more difficult to improve than for example cycle time, since it reflects the team's overall situation rather than just the process.

We typically recommend teams to start with an open discussion on the topic to capture different viewpoints into the problem.

Here are some discussion starters we've learned are useful:

1. Are we using pull requests for everything? If we have a habit of pushing changes directly to the main branch, the pull request metrics are less accurate.
2. How large are the pull requests? The optimal size depends on the programming language and many other factors, but generally it's good to change fewer than a few hundred lines of code at once.
   1. What's your branching strategy? Are you targeting short-lived branches?
   2. Do you have the infrastructure for example for feature gates? It allows you to keep features hidden even if the code has already landed in the main branch.
3. Are we working on some other tasks? Multi-tasking takes a toll on development work.
4. How much time are we spending in meetings? How are they spread throughout the day?
5. How familiar are we with the codebase?
   1. If I need to touch a product area I'm not familiar with, how easy is it to find someone who knows about it?
   2. Are we actively spreading the knowledge about the codebase by working together on each feature?
6. How easy is it to write automated tests?
   1. Are we testing at the right level? How does our testing pyramid look like?
   2. Do we have all the required helpers to make it easy? For example, how easy is it to generate test data for an integration test?


# Analyzing pull request batch size

Batch size measures how much work is bundled up in a change. Swarmia offers tools for evaluating pull request batch size by looking at the total amount of changes.

There are several ways of measuring the complexity of pull requests. Analyzing the amount of changes, or the absolute size of the diff, is the most common and robust way to do this.

While there are circumstances where very large pull requests are valid, it's recommended to break down the work into smaller increments.

The main benefit of doing so is an improved flow of work. This tends to happen because the team is changing things in smaller increments, which are quicker to author and also easier to review. Reviews can be more thorough when there are fewer changes to analyze at one go, and this adds up to an increase in the quality of the code base. Furthermore, smaller changes help get the reviews more quickly than, say, for a 500+ line monster, which might be demoralizing to even start looking at.

## Reducing the number of large pull requests

There's no absolute limit to a large pull request, but what matters most is the typical batch size. We recommend keeping close attention on the number of PRs with more than 200 lines of changes.

The pull request [Batch Size Insights](https://app.swarmia.com/insights/code/batch-size) provide visibility to the typical batch size and the batch size distribution. Teams can see how many large PRs are going through the system, and analyze these more closely.

By interacting with the distribution, you can analyze a section or sections in the distribution. Doing this filters both the scatter plot and the table containing detailed pull request information to the selected bucket(s).

<figure><img src="/files/uHqkHWbgT4ICYgRQvqEa" alt=""><figcaption></figcaption></figure>

We recommend looking for patterns or similarities to help analyze what's driving a trend for a large batch size or significantly lower cycle time. You may find that certain themes of work, some repositories, or specific features often result in bigger batches or changes that take significantly more time and effort.

See also: [Diagnosing low pull request throughput](/guides/improve-pull-request-flow/diagnosing-low-pull-request-throughput)

## Excluding auto-generated files

It's important to focus on only the actual changes when analyzing pull requests. However, repositories often contain generated files, which could be related to e.g. package dependencies.

In order to provide an accurate view of the real changes, [Swarmia automatically cleans up the total change count of some commonly used generated files](/definitions/batch-size).


# Improve code quality

Build better quality products, reduce technical debt, and implement development practices that scale as your team grows

<figure><img src="/files/Pb2R3cJ0WfL44gRiBcgw" alt=""><figcaption></figcaption></figure>

Engineering teams often struggle to maintain high software quality. Poor quality leads to customer dissatisfaction, increased operational overhead, and a constant drain on developer time spent fixing issues rather than building new customer value.

While individual teams may operate effectively, broader systemic weaknesses such as gaps in testing, ineffective code review practices, and unreliable code release pipeline can lead to recurring quality problems. Without clear visibility into these quality issues, it can be difficult to take targeted actions that meaningfully improve the situation.

## Prerequisites & Setup

Swarmia uses data from your issue tracker to understand which projects you’re working on: configure the [Jira integration](https://help.swarmia.com/getting-started/integrations/jira) or the [Linear integration](https://help.swarmia.com/getting-started/integrations/linear).

You'll also need to set up [investment categories](/features/focus/balance-engineering-investments) and define how [change failure rate](/definitions/dora-metrics/change-failure-rate) is calculated.

## Using Swarmia

A comprehensive approach to the quality problem includes analyzing deployment stability, work allocation, bug management, and development practices to identify quality improvement opportunities.

Start by examining your deployment stability metrics to understand your baseline quality performance.

### Change failure rate

The [change failure rate](/definitions/dora-metrics/change-failure-rate) tells what percentage of deployments result in failures, degraded service, or require immediate fixes. It's an indicator of your deployment process maturity and code quality.

Look for patterns in when failures occur:

* Are failures clustered around certain teams, projects, or time periods?
* Do failures correlate with deployment frequency or batch size?
* Are there specific types of changes that consistently cause problems?

### Mean time to recovery (MTTR)

[Mean time to recovery](/definitions/dora-metrics/mean-time-to-recovery) (MTTR) measures how quickly your team can restore service when issues occur. This reflects both your incident response processes and your system's observability. Use this metric to identify:

* Teams that struggle with incident response
* Systems that are difficult to debug or fix
* Process improvements needed in your incident management (issues not being detected quickly)

### Bugs

[Bug cycle times](https://app.swarmia.com/metrics/issues/flow?issueFilter=%7B%22type%22%3A%22IssueFilter%22%2C%22version%22%3A2%2C%22condition%22%3A%7B%22type%22%3A%22SwarmiaIssueType%22%2C%22in%22%3A%5B%22Bug%22%5D%7D%7D) reveal how effectively your team manages defects. Bug throughput also tells which teams might be having the most work with just maintaining the product. Filter by priority levels (P0, P1, etc.) to understand how critical issues are handled differently from minor bugs. Key questions to explore:

* Are high-priority bugs resolved quickly enough?
* Are there patterns in what types of bugs take the longest to fix? Do bug cycle times vary significantly between teams or projects?

The proportion of work going into bug fixes versus feature development indicates whether quality issues are consuming your team's capacity. High proportions of reactive work (KTLO) might signal deeper quality problems.

<figure><img src="/files/7Fpj5dX9lLS4wJQxQXUm" alt=""><figcaption></figcaption></figure>

### Investment balance

Look at your [investment balance](/features/focus/balance-engineering-investments) over time:

* Are you spending more time on bug fixes than planned feature work?
* Do certain teams struggle more to keep the lights on?
* What kind of patterns can you find when you drill down to the work? Are certain parts of your codebase generating more bugs than others?

<figure><img src="/files/nAQwTxNXwvBgrghmZ1Xz" alt=""><figcaption></figcaption></figure>

### Batch size

Smaller pull requests are easier to review thoroughly, leading to better quality. Large batches increase the likelihood that defects slip through code review.

Monitor your [pull request batch sizes ](/definitions/batch-size)alongside quality metrics:

* Do larger pull requests correlate with higher change failure rates?
* Are teams with smaller batch sizes experiencing fewer quality issues?
* Is there adequate review time for the changes being made?

<figure><img src="/files/JHr3Y98TB0dK42BIoGzw" alt=""><figcaption></figcaption></figure>

### Surveys

While metrics tell you part of the story, surveys reveal the underlying practices and team sentiment that drive quality. Developer perceptions of quality practices often predict future metric trends.

Swarmia's [developer surveys](/features/run-developer-experience-surveys) include the following questions about quality:

* Our automated tests catch issues reliably.
* Our code reviews adhere to high standards.
* Our technical debt is well under control.
* Our practices steer toward building secure solutions.
* The on-call load in my team is reasonable.

Survey responses can highlight disconnects between metrics and team experience. For example, a team might have low change failure rates but report poor test reliability, suggesting they're catching issues through manual processes rather than automation.

<figure><img src="/files/uRR0uutXXtAjSbMp1Dx2" alt=""><figcaption></figcaption></figure>

## Taking action

Combine survey insights with metrics to identify improvement opportunities. Common good practices include:

* Require code reviews for all changes and prefer smaller PRs to ensure quality reviews
* Allocate dedicated time for technical debt reduction
* Post-incident reviews to learn from failures and share learnings across teams
* Implement automated testing that runs on every pull request
* Automatic monitoring to detect issues quickly after deployments


# Improve your team's focus

{% embed url="<https://www.youtube.com/watch?v=ow0acM--NqM>" %}

Engineering teams have a big responsibility of balancing multiple priorities. They have roadmap commitments, production incidents, internal improvements, and other types of work competing for their attention.

Many teams end up choosing priorities accidentally since, historically, there was no feedback loop. Common issues include:

* Multi-tasking too much
* Developers have their preferred types of work without aligning with the team's needs
* Changing priorities when the previous project is 90% done

These issues weaken the team’s ability to deliver stories and epics. A great team finishes what they start.

### Prerequisites & Setup

Swarmia uses data from your issue tracker to understand which projects you’re working on: configure the [Jira integration](/settings/integrations/issue-trackers/jira) or the [Linear integration](/settings/integrations/issue-trackers/linear).

Your team will need to [link pull requests to issues](https://help.swarmia.com/how-do-i-link-pull-requests-to-issues-in-practice) using one of the supported mechanisms.

### Using Swarmia

To get a sense of your team’s ability to deliver stories and epics, start from *issue insights*:

<figure><img src="/files/zYIbI7OaVFwndiIDvXNL" alt=""><figcaption></figcaption></figure>

Every team splits work differently, so there’s no universal rule for issue cycle times. Ask yourself: Does this cycle time allow us to reflect regularly and course-correct?

It’s common to have rules like “epics shouldn’t take more than 1-3 months and stories shouldn’t take more than 1-2 weeks.” This makes sense because a common failure pattern is to start a project based on false assumptions and then keep grinding with no end in sight.

In *focus summary*, you can analyze how much effort each team spends across all projects:

<figure><img src="/files/mf0imz9iEqv2H19Xmi3a" alt=""><figcaption></figcaption></figure>

Another way to look at your long-term ability to deliver is by using *high-level work log*.

<figure><img src="/files/GquIYojrohUDqzuBu9Js" alt=""><figcaption><p>High-level work log</p></figcaption></figure>

<figure><img src="/files/Vk3Ux4P5CBRYuKF4a0jC" alt=""><figcaption><p>Healthy staircase pattern vs. scattered activity. On the left you can see a team that works on one thing at the time, and then moves on to the next one. On the right you can see a team that starts a lot of projects, but doesn’t finish them.</p></figcaption></figure>

If you consider this from your customer’s perspective (”How often am I getting some valuable updates in the product?”), the team on the left delivers new increments every week. The team on the right has many things in progress, but they might not have anything to release in a long time.

To really address the issue, you’ll need to zoom in. This requires an understanding of the work itself, so it’s best done by the team itself. This is a very common discussion in a team retrospective.

<figure><img src="/files/Wf4xQCvW7Y7t8c1wuKch" alt=""><figcaption><p>Work log grouped by issue</p></figcaption></figure>

Work log shows the last two weeks of work at the detailed level. You can identify patterns like:

* Days with no activity: did we shift our focus to one of the other lanes, or did we hit a blocker?
* Solo work: if only one person works on a feature, it’s more difficult to get proper code reviews done, and the work progresses more slowly.
* High levels of reactive work: while taking ownership of the codebase is important, sometimes this signals too broad a scope for the team or a lack of clarity with the feature work.
* Complex sub-tasks: did one of the sub-tasks take so long that the whole project got delayed?

On each page, you can select an individual issue to analyze it in more detail:

<figure><img src="/files/m8cI0KdLG5sUdUOP0uRt" alt=""><figcaption><p>Issue overview</p></figcaption></figure>

### Taking action

Setting a Work In Progress (WIP) limit is often considered the most important process improvement. This practice, which originated from Lean and Kanban, is well-researched.

The logic is that when the team has limited “slots” of work they can take, they are forced to make decisions. If something is blocking our work, we must unblock it rather than work on something else. Similarly, teams will be able to better manage external stakeholders, when they can let them know they can’t pick up additional work just yet.

In Swarmia, you can create WIP limits for different types of work as Working Agreements:

* Limit work in progress to 2 stories
* Limit work in progress to 1 epic
* Limit work in progress to 10 pull requests

<figure><img src="/files/j0CEakXjbr8mXpbtNv1V" alt=""><figcaption><p>WIP limit working agreement</p></figcaption></figure>

In addition to the WIP limits, you can have other related Working Agreements:

* Avoid working alone on stories/epics
* Close stories in less than 14 days

Once you’ve decided how you want to work, the most important thing is to follow through. Agree with your team to start every retrospective by looking at Swarmia data together. This allows you to ground the discussions in facts and often surfaces new perspectives.

### Roll-out strategy

1. Select a handful of teams for a pilot and coordinate with their team lead. Make sure that the setup is done correctly.
2. Have leadership go through the issue cycle times for different teams to see where we currently are.
3. Facilitate a retrospective with each team. Come up with a prepared list of potential root causes, but be open to the experiences the team can bring.
4. After seeing some changes with one of the teams, use that as a case study when rolling out Swarmia to a broader set of teams. This allows you to speak using your organization’s language, rather than discussing productivity in a more generic sense.

### Further reading

* Model for [measuring engineering effort](/definitions/developer-effort-ftes) in Swarmia


# Optimizing issue cycle time

Practical tips and best practices for improving your focus and structuring work to reduce issue cycle times.

## Why should you care about issue cycle time?

As the complexity of a software organization and codebase increases, the teams in the organization face new challenges. Teams find themselves in an environment of team and system dependencies, and an increasing number of problems competing for their attention, including legacy systems and technical debt.

If the teams keep on doing what they've been doing, their existing work structures (for example Epics, Stories and Tasks) end up taking much longer than what they used to. As a result, the teams become slower to deliver software to the end-users and to react to new knowledge or customer feedback.

To reverse this trend, teams need to start measuring cycle time with an aim to decrease it. Retrospectives and working agreements are both great tools for turning cycle time insights into systematic action, like limiting work in progress.

These actions should be accompanied by structuring and breaking down the work with a goal of optimizing for cycle time and team collaboration.

## **Defining issue cycle time**

The cycle time of any software work is the amount of time from the start of development work until the end result reaches the customer. For issues, the most understandable way to measure this is to look at the time it stays **In Progress**, based on the issue tracker status. In practice, the time spent in progress can often be split into multiple steps (e.g. a separate step for any time that an issue spends in review) – in which case you want to look at the combined time spent in these statuses (refer to [these instructions](/settings/integrations/issue-trackers/jira/jira-setup#review-status-mapping-to-improve-data-quality) to configure this on Swarmia).

Since the progression of issues is not always linear, it is important to be able to differentiate between the time the issue has been actively worked on, and the time between the first and last activity on the issue. **There are valid reasons for pausing work** on an issue – perhaps there's a critical bug in production, or perhaps the team had to revisit some assumptions about the problem and redesign the solution – **but it's important to know when this happening.**

Swarmia automatically calculates key properties and metrics (such as [active time](/definitions/defining-issue-lifecycle-and-cycle-time#active-days), [lifetime](/definitions/defining-issue-lifecycle-and-cycle-time#lifetime) and [flow efficiency](/definitions/defining-issue-lifecycle-and-cycle-time#flow-efficiency)) for each issue to allow investigating how they went and what could have been done better.

## Are you able to focus on the important things?

In software teams the issues that are visible in your project management software almost never tell the full story about what teams are actually working on. There are always other priorities taking time away from completing your planned roadmap work. It's not possible (nor wise) to eliminate distractions completely, but it's important to understand the effect of context switching on the cycle time of your high-priority items.

### **Analyze the flow of work**

It can be easy to get lost in the sea of problems and day-to-day work, especially without a proper way to measure what kind of work a team is spending their time on.

Swarmia's Work Log view is a good place to start understanding the full breadth of work in progress. You'll also get a view on work you *think* is in progress but doesn't have any real activity in a separate section.

<figure><img src="/files/ZdlOjGjArzwXmQdMojbE" alt=""><figcaption></figcaption></figure>

Clicking on any issue to open the activity popup will reveal its flow efficiency – a lean metric telling you the proportion of days you have actively worked on the issue during its lifetime. **If the issue has low flow efficiency and you did not work on it the whole time this often indicates having too much work in progress simultaneously.** This symptom is also visualized on the work log as an absence of regular day-to-day activity on stories in progress.

### **Introduce work in progress limits**

If it looks like you are working on too many things at once, hindering the progress of your top priorities, **consider adopting a working agreement limiting the work in progress**. This way you'll stay on top of your work in progress and can act fast if you are drifting towards working on too many things at once. A good rule of thumb for the target number of stories in progress at once is ***Math.floor(number of devs / 2)***.

You can set working agreement targets for the amount of issues in progress (eg. "No more than three stories in progress at once"). [Learn more](https://github.com/swarmia/knowledge-base/blob/main/improve-team-focus/broken-reference/README.md) about working agreements.

## Are you structuring work for success?

When work slows down, the effect is usually most obvious with the larger units of work. When stories start to take up to a month and epics more than a few months, the team can usually feel that things start to feel slow. Decreasing cycle time at this level can have a significant impact not only on the team's velocity but also how rewarding and fluent the work feels. So how do you improve?

### **Work as a team**

**The first step is simple: plan your work for at least two developers.** One could argue that how you split the work doesn't matter, because the same work is going to get done anyway. However, there are two main reasons why it does:

* **How you split your work affects collaboration.** If your smallest increment of work takes 2 weeks from one developer, it means they are unlikely to collaborate with others over those two weeks. Developers sometimes prefer this due to fewer distractions, but the downside is that the team shares less information, ends up creating worse plans, and takes less interest in their teammates' work.
* **The completion of work marks a natural time for re-evaluating a plan.** If the team works on a feature for several months, chances are that some new information is not applied in the plan. Since software is often built with a large amount of uncertainty, it's critical that teams are able to apply learning early and regularly.

There are many other benefits that the teams gain by structuring their work in a way that enables collaboration. For instance, this often leads in reduced time-to-market for new products or features, resulting in more engagement with the customers and ultimately a better product. The developers are happier when they're collaborating and getting better support (e.g. getting better code reviews from their peers working on the same topic).

You can measure and improve your ability to work as a team on issues with Swarmia. This can be done by adopting a [working agreement](https://app.swarmia.com/working-agreements/) for avoiding solo work. [Learn more](https://help.swarmia.com/about-working-agreements) about working agreements.

### **"But we're more effective when working alone!"**

When everyone is working on their own project, work might feel efficient due to not having to coordinate anything with others. However, building a great product and team is a long-term effort, and the benefits far outweigh the costs in the long run, for the team and developers alike.

* **Structuring work with developer collaboration in mind forces you to be more thorough in the planning process.** This can helps clarify the context for the team and reduce unknowns before the implementation.
* **Tough problems become easier when you don't have to work on them alone.** You're going to have an easier time sparring, rubber-ducking, and getting your code reviewed, all of which likely make your work flow better and reduce moments of frustration.
* **Too many competing priorities can lead developers and teams to work on simple, reactive tasks.** These are easier to complete, but time spent on them might not maximize the impact of the team. It's often better to focus attention on properly solving few problems that really matter, rather than struggling to solve too many problems at once.

### **Minimize scope**

When the work in progress seems to not hinder completing your projects and they still seem to take too long to complete, you may need to look elsewhere for solutions. Another typical challenge to overcome is that a **team is trying to solve too large of a problem at once**. This is why you should critically evaluate the total scope of the issues.

For instance, a team might have structured the work in a way that would have created customer value and been able to learn more, before completing the whole original scope. The power of small stories to deliver more value for customers is well researched and there are [good strategies out there to slice your stories](https://medium.com/agilegreat/story-slicing-216af738ef4c) to optimize your issue sizes.

### **Evaluate your planning skills**

There is much more to planning than just sheer scope of the issues. It is rare that upfront planning manages to account for all the tasks that end up going into an issue. This is why being aware of how the scope of the issue developed over time is important.

If you already know how much extra work you'll add on average (eg. 20% more tasks), you can **take the scope creep into account when starting to plan the issue** (for our example, this might mean three more tasks to complete, taking two extra days). You can also learn about **certain types of tasks that tend to be always added to the scope after starting**, and gradually increase the quality of planning.

As a side effect, you'll also become better at estimating how long the work will take to complete (which might help when making prioritization calls, deciding what to communicate to a stakeholder, or serve as a hint to split the work in smaller increments).

It is also common that challenges with scoping extend to the sub-tasks of the issue. There are often a couple of outlier tasks that took longest to complete for some reason. **Identifying long running tasks and thinking about if they could have been split somehow will also positively contribute to the quality of planning future issues.**


# Benchmarks & comparisons

Compare your engineering metrics to Swarmia benchmarks, and analyze how different teams compare against your organization's average.

Understanding whether your team’s performance is on track isn’t always straightforward. Are your pull request cycle times good enough? Should you be concerned about your change failure rate? And which teams might need extra support?

Swarmia provides benchmarks for the most important engineering metrics, along with tools to compare teams within your organization.

## **Why benchmarks matter**

Swarmia benchmarks help you identify improvement areas by giving you a proven point of reference. Instead of guessing what “good” looks like, you can see how your metrics compare to industry-validated performance levels.

[Benchmarks](https://www.swarmia.com/blog/engineering-benchmarks/) are most useful when you treat them as **directional guidance**, not targets to optimize blindly. They help you:

* Spot the parts of the workflow that are holding teams back
* Prioritize improvement efforts
* Create a shared understanding of what healthy engineering performance looks like

## **Why team-to-team comparisons matter**

Comparing teams within your organization often reveals more actionable insights than looking at benchmarks alone.

High-performing teams show what’s *already possible* in your own context. When some teams consistently perform better than others, improving the organization’s overall performance usually means helping struggling teams adopt similar ways of working.

To improve performance across the organization:

* Focus on **closing the gap between the best and worst performing teams**
* Look for differences in processes, tooling, ownership, or how work is broken down
* Use strong teams as learning examples — not as pressure mechanisms

The goal isn’t to rank teams, but to understand where support, coaching, or structural changes will have the biggest impact. [Swarmia’s working agreements](https://help.swarmia.com/continuous-improvement/working-agreements) can also help teams adopt proven practices and build better habits, once you’ve identified where improvement is needed.

## **How to use benchmarks and comparisons in Swarmia**

When viewing metrics in Swarmia, click the **Previous period** button above the table to select from three options:

* **Previous period (default).** See how metrics have changed over time and whether your improvement efforts are working.
* **Organization.** Compare individual teams against your organization’s baseline to identify outliers, improvement opportunities, and teams that may need extra support.
* **Swarmia benchmark.** See how your organization and teams compare to industry standards based on proven benchmarks.

<figure><img src="/files/YR23gf7iXhXjmKWQAvWA" alt=""><figcaption><p>Select from the different comparison options. Previous period is the default.</p></figcaption></figure>

When using Swarmia benchmarks, you’ll see a color-coded label — **great**, **good**, or **attention** — that indicates how your performance compares to benchmark ranges. These labels help you quickly spot which metrics are at a healthy level and where you should consider digging deeper.

For organization comparisons, you’ll see the difference displayed next to each metric. This makes it easy to spot which teams are ahead or behind the org average.

Swarmia benchmarks are available for **code metrics** and **DORA metrics,** while organization comparisons work across all normalized code, DORA, and issue metrics.

| Metric                  | Great                                  | Good                           | Needs attention                          |
| ----------------------- | -------------------------------------- | ------------------------------ | ---------------------------------------- |
| Pull request cycle time | < 24 hours                             | < 5 days                       | ≥ 5 days                                 |
| Review rate             | ≥ 90%                                  | ≥ 80%                          | < 80%                                    |
| Time to first review    | ≤ 4 hours                              | ≤ 24 hours                     | < 24 hours                               |
| Time to merge           | ≤ 4 hours                              | ≤ 24 hours                     | < 24 hours                               |
| Batch size              | < 200 lines                            | < 500 lines                    | ≥ 500 lines                              |
| Deployment frequency    | <p>≥ 10 per week<br>(Continuously)</p> | <p>≥ 5 per week<br>(Daily)</p> | <p>< 5 per week<br>(Less than daily)</p> |
| Change lead time        | < 24 hours                             | < 5 days                       | ≥ 5 days                                 |
| Time to deploy          | < 15 mins                              | < 60 mins                      | ≥ 60 mins                                |
| Change failure rate     | < 5%                                   | < 15%                          | ≥ 15%                                    |
| Mean time to recovery   | < 1 hour                               | < 3 hours                      | ≥ 3 hours                                |


# Retrospectives with Swarmia

How to run great retrospectives with Swarmia.

## What makes a good **retrospective?**

Swarmia is all about enabling a data-driven continuous improvement cycle in software development teams. As the purpose of retrospectives is to facilitate continuous improvement in a team setting, using Swarmia in retrospectives can help you get there. Great retrospectives have three things in common: they are blameless, fact-based, and actionable.

**Blameless**

One of the worst things to happen in retrospectives is that it becomes a blame game, having an overall negative effect on teamwork. This is why it is important to keep a blameless mindset and focus on improving team dynamics in retrospectives. A long-running task is not someone's fault, but the result of the team organizing their work in a certain way.

**Fact-based**

Having a shared fact base when conducting retrospectives helps you identify objectively what went well and what we could still improve as a team. However, many teams are not used to full transparency of data. It can be useful to remind the team that looking at the data allows us to have a more directed conversation about things to improve. Looking at the data feels even less appealing if it seems to be incorrect. It's good to highlight the elements that contribute to the data quality: practices using the issue tracker, linking of Pull Requests to issues, etc.

**Actionable**

The last piece to crack in great retrospectives is to make them actionable. We have experienced that teams often struggle to turn discussions in team retrospectives into concrete action. Having the right tools available can make the difference between action and inaction.

**Swarmia is here to help you conduct great retrospectives, whether it comes to preparing, conducting, or turning them into concrete action:**

## **Before the retrospective**

Explore your team's data on Swarmia to prepare for retrospectives by discovering insights and validating hypotheses on what seems to work and where you could improve based on data.

Check the [Work Log](https://app.swarmia.com/work) view to identify if there are signs of working alone, siloed work, days without progress, or too much reactive work. More information on how to diagnose patterns from the work log [here](https://help.swarmia.com/diagnosing-common-issues-with-work-log).

Use the [Insights](https://app.swarmia.com/insights/flow/pull-requests) view to identify PRs, Tasks, Stories or Epics that took a long time to complete. When you click a dot in the Cycle Time graph, you can dig deeper to what actually happened with the feature each week.

## **During the retrospective**

After a good preparation, you can focus on a well-informed discussion, which should result in concrete actions agreed upon as a team. Swarmia has built-in [Working Agreements](https://app.swarmia.com/working-agreements) that can be set up based on actions agreed upon during retrospective.

Pull Request flow is easier to fix than Tasks or Epics, and thus it can be a good starting point for the discussion. It's good to dig deeper into the outliers. Was the scope of this PR too large, and could we have split it in other ways? Was it difficult to get a review? Was it clear what was supposed to be done here?

With tasks/issues, the change requires a bit more effort. Developers often like working on their own thing, as they don't have to coordinate much. Changing the behavior requires several things:

1. limiting Work In Progress
2. multiple people working on the same task
3. better planning of the sub-tasks
4. making sure that sub-tasks are small enough

## **After the retrospective**

If the team decides during retrospective to clean up old Pull Requests and set a Working Agreement for Pull Request age and review times, you can expect to see results in a week (or just in time for your next retrospective). Enabling [team notifications](https://app.swarmia.com/settings/team/notifications) makes use of Working Agreements even easier.

Deciding to strive for better planning will likely take a couple of iterations, as it is hard to get right at the first try. Thus, in future retrospectives, it's useful to discuss individual tasks and how well they went.

## Read more on our blog

* [Reduce bias in retrospectives with better data](https://www.swarmia.com/blog/data-driven-retrospectives-stop-fake-improvements/)
* [How to run developer survey retrospectives in your team](https://www.swarmia.com/blog/developer-survey-retrospectives/)


# Improve developer experience

Spot what's slowing your engineers down — flaky CI, slow feedback loops, unclear priorities, or tooling pain — and fix it.

Developer experience is about whether engineers can do their best work every day. When they spend their time fighting slow pipelines, unclear priorities, or constant context switching, productivity and motivation suffer. The challenge is spotting where friction comes from — before frustration turns into attrition.

Swarmia gives you the data to see how engineers are spending their time, and whether the conditions for focused, effective work are in place.

## **Start with CI visibility**

Slow or unreliable pipelines are a major source of frustration, yet most CI providers offer little visibility into performance trends. Swarmia surfaces [runtime trends and failure rates](https://help.swarmia.com/features/metrics/get-visibility-into-your-ci-pipeline) across your repositories and workflows — so you can spot slowdowns, identify flaky pipelines, and drill into individual jobs to diagnose issues.

## **PR feedback loop**

Use [code metrics](https://help.swarmia.com/features/metrics/code-metrics) to understand whether engineers are getting timely feedback on their work. Long review wait times, PRs stuck in progress, or late-arriving reviews are signs the feedback loop is broken — and that engineers may be losing context or momentum while they wait.

## **Listen to engineers directly**

Developer experience [surveys](https://help.swarmia.com/features/run-developer-experience-surveys/managing-surveys) give you a structured way to collect signal on clarity, empowerment, and satisfaction — going beyond what metrics alone can tell you. Engineers can flag issues with tooling, technical debt, test coverage, and on-call load: things that slow them down every day. Surveys also help you tell apart systemic problems from team-specific ones.

## **Make all work visible**

Maintaining focus and limiting work in progress is often the best starting point for improving developer experience. Use the [work log](https://help.swarmia.com/features/focus/analyzing-the-activity-patterns-on-work-log) to see a complete picture of the team's daily work — combining Git and issue tracker data — so you can spot harmful patterns like too much reactive work, people working alone on projects, or initiatives that stall.

For a deeper view, [issue metrics](https://help.swarmia.com/features/metrics/issue-cycle-time) show how work in progress and issue cycle time have evolved over time. Pay attention to flow efficiency — the share of days an issue was actively worked on during its lifetime. Below 70% is worth investigating; above 95% is considered great. It's one of the clearest signals of whether your team finishes work before starting the next thing.

## **Set shared expectations**

Once you've identified friction points, use [working agreements](https://help.swarmia.com/features/working-agreements) to set shared standards around things like review turnaround times or limits on issues in progress. These make expectations visible and help teams stay accountable without constant management overhead.

Teams on Slack can receive a daily digest to stay aware of how well they're keeping to their agreements.

With clear data and a habit of listening to your engineers, you can move from reacting to individual complaints to systematically improving the conditions for great work.


# Understand the impact of AI tools

Combine developer experience surveys, adoption metrics, and usage patterns to understand how AI coding tools play into your software organization's productivity.

Tools like GitHub Copilot, Cursor, Claude Code, and other AI coding tools are changing how engineers write and review code. Many teams see real productivity gains, but they also ask an important question: How do we measure the impact?

It's a natural question. Engineering leaders want evidence that their investments are paying off. Yet, [there's no single measure of developer productivity](https://queue.acm.org/detail.cfm?id=3454124), so don't expect one number to tell you the impact of AI tools. Be wary of claims like *"this tool makes your developers 55% more productive"* or *"GenAI gives you annualized savings of $475,728"*, since they're usually based on narrow definitions, broad assumptions, or flawed statistics.

Here's why measuring the productivity impact of AI tools isn't straightforward.

* Many teams lack a clear baseline to compare against.
* Engineers use a fragmented mix of tools, and it's hard to track them all.
* Gains in one metric can unintentionally hurt others.
* Early adopters tend to be high performers, skewing results.
* Overreliance and inadequate reviews can reduce code understanding and increase tech debt.
* There isn't one metric that can tell the full story.

You can still build a useful picture of how AI coding tools affect your organization. This guide explains what to measure, where the data has limitations, and what to do with the results.

## Using Swarmia

### Track AI tool adoption and licenses

Use [AI adoption](/features/ai-tools/ai-adoption) to see how many people have GitHub Copilot, Cursor, or Claude Code enabled, how many actively use them, and where you may have idle licenses.

<figure><img src="/files/6FdoulJKyd4ZsAwYxu4R" alt=""><figcaption></figcaption></figure>

### Study AI tool activity patterns

Use the activity breakdowns to understand how people use AI tools in practice: which features they adopt, how usage develops over time, and where teams may need more support.

Read more:

* [GitHub Copilot activity](/features/ai-tools/github-copilot-activity)
* [Cursor activity](/features/ai-tools/cursor-activity)
* [Claude Code activity](/features/ai-tools/claude-code-activity)

<figure><img src="/files/FQlfo6qtWyAO06Jz7d0V" alt=""><figcaption></figcaption></figure>

### Understand how AI impacts developer productivity

Use [AI impact: Code](/features/ai-tools/ai-impact-code) to compare AI-assisted and non-AI-assisted pull requests across throughput, cycle time, review time, and batch size. The page helps you understand where AI changes the flow of work and where you may need to look deeper.

<figure><img src="/files/hzVF4XCWZlFXhRa7tEAU" alt=""><figcaption></figcaption></figure>

### See what AI tool usage is worth

Impact is only half of the equation — the other half is what the usage costs. Use [AI cost](/features/ai-tools/ai-cost) to see the token value of your GitHub Copilot, Cursor, and Claude Code usage, broken down by team, by person, and by the work your teams deliver. Spot where AI spend is concentrated, compare it against the adoption and impact signals above, and see which issues and initiatives the spend actually went to.

### Weigh the cost of AI tools against the output

Sooner or later, someone will ask what the AI spend is buying. Use [AI impact: ROI](/features/ai-tools/ai-impact-roi) to put cost and output side by side: the [token value](/features/ai-tools/ai-cost#token-value) of your AI tools plus the estimated cost of engineering time, against the stories, pull requests, and code your teams ship.

### Analyze AI cloud agents' work

Use [Cloud agents](/features/ai-tools/cloud-agents) to see how AI agents that create pull requests end-to-end are contributing across your organization. Track merged and closed agent PRs, the share of work done entirely by agents, batch size, and team-level adoption.

<figure><img src="/files/SBIDeyJLkhk7dtz10Xsc" alt=""><figcaption></figcaption></figure>

### Track review agent coverage

Use [Review agents](/features/ai-tools/review-agents) to understand which AI agents review your pull requests, how much of your code they cover, and how many findings they leave per PR.

<figure><img src="/files/RBUwqS1nbvMDiZvn5qBr" alt=""><figcaption></figcaption></figure>

### Capture developer sentiment with surveys and retrospectives

AI tools affect more than code generation. They can change discovery, review, testing, documentation, and knowledge sharing. To understand those changes, ask engineers directly.

Developer experience [surveys](/features/run-developer-experience-surveys) help you collect feedback on AI tool usage, perceived speed, quality, and friction. Use retrospectives to discuss the patterns and agree on what to change next.

<figure><img src="/files/jjgfSArJ8vkBXE5V4dgS" alt=""><figcaption></figcaption></figure>

### Understand collaboration patterns

Use the [work log](/features/focus/analyzing-the-activity-patterns-on-work-log) to see how AI tools affect collaboration and work distribution. Watch for changes in how much work happens alone, how often people collaborate on the same issues, and whether knowledge is spreading across the team.

If AI-assisted work creates new silos, use the data as a starting point for team discussions and working agreements.

### Track quality signals

AI tools can speed up code changes, but faster output doesn't automatically mean better outcomes. Use [investment balance](/features/focus/balance-engineering-investments) to monitor the share of maintenance work, and use [DORA metrics](/features/metrics/track-dora-metrics) to track change failure rate and mean time to recovery.

These signals help you spot whether AI-assisted work is creating hidden quality costs, such as more rework, incidents, or technical debt.

## Taking action

### Spreading best practices

Allow teams to find their own path to effective AI tool usage. Some engineers and tasks will benefit more than others, and that's okay.

* Make progress visible while emphasizing learning rather than comparison.
* Spot early adopters who can share practical examples.
* Collect successes, failures, tips, and observations in a shared document, wiki, or Slack channel.
* Set aside time to experiment with AI tools.
* Reassess your approach as AI capabilities evolve.

### Finding adoption bottlenecks

Invest in overcoming setup hurdles and make it easy to get started.

* Identify teams with low AI assistant usage or unused licenses, and find out what's blocking adoption.
* Improve codebase documentation so AI agents can understand your system.
* Configure good defaults for AI tools in your development environments.

### Agreeing on ways of working

New tools can create unintended side effects. Spot and address them early, before they become real problems.

* Establish clear guidelines for reviewing AI-generated code.
* Create policies for using AI tools with sensitive code.
* If you notice knowledge silos, [set up a working agreement](/features/working-agreements) to avoid working alone on issues.
* If AI tool usage results in overly large pull requests, [set up a working agreement](/features/working-agreements) to limit batch size.
* Discuss the topic in retrospectives. See our [guide on running survey retrospectives](https://www.swarmia.com/blog/developer-survey-retrospectives/).
* Focus on team-level improvements rather than individual performance.

## Further reading

Swarmia blog:

* [Measuring the productivity impact of AI coding tools: A practical guide for engineering leaders](https://www.swarmia.com/blog/productivity-impact-of-ai-coding-tools/) by Otto Hilska, Founder & CEO · Jun 16, 2026
* [Five levels of AI coding agent autonomy, and why higher isn't always better](https://www.swarmia.com/blog/five-levels-ai-agent-autonomy/) by Miikka Holkeri, Product Manager · Mar 19, 2026
* [A staged approach to AI adoption for engineering teams](https://www.swarmia.com/blog/staged-approach-AI-adoption-for-engineering) by Rebecca Murphey, Field CTO · Dec 5, 2025
* [What the 2025 DORA report tells us about AI readiness](https://www.swarmia.com/blog/dora-2025-report-ai-readiness/) by Rebecca Murphey, Field CTO · Oct 22, 2025
* [Small teams, big bets: Lessons from three Nordic AI startups](https://www.swarmia.com/blog/small-teams-big-bets/) by Erin Backlund, Content Marketing Manager · Oct 13, 2025
* [Code faster, ship ... the same?](https://www.swarmia.com/blog/code-faster-ship-the-same/) by Rebecca Murphey, Field CTO · Aug 20, 2025
* [Measuring AI impact like it's 1995](https://www.swarmia.com/blog/measuring-ai-impact-like-1995/) by Rebecca Murphey, Field CTO · Aug 5, 2025


# Use Swarmia in meetings and team rituals

Swarmia works best when it's part of the meetings your team already runs — not a separate dashboard to check occasionally. Teams that improve the most bring data into conversations they're already having, rather than adding new ones.

## Retrospectives

Retrospectives are the highest-leverage entry point for Swarmia data. The best ones share three qualities: blameless, fact-based, and actionable.

**Blameless:** A long-running task or slow PR isn't someone's fault — it reflects how the team organized its work. Keep the focus on process, not people.

**Fact-based:** A shared fact base helps the team identify what went well and what could improve. Data makes the conversation more focused and harder to dismiss on gut feel alone.

**Actionable:** Teams often struggle to turn retrospective discussions into change. Having the right data and tools available makes the difference between a good conversation and an actual improvement.

### **Before the retrospective**

Check [cycle time](https://help.swarmia.com/features/metrics/code-metrics) trends, [working agreement](https://help.swarmia.com/continuous-improvement/working-agreements) performance, and the [work log](https://help.swarmia.com/use-cases/improve-your-teams-focus/analyzing-the-activity-patterns-on-work-log) for signs of siloed work, days without progress, or too much reactive work. Pick one or two specific data points to bring into the room — a PR that sat open for nine days, a sprint where WIP crept up, a team member carrying most of the review load.

### **During the retrospective**

Use data to open the discussion rather than asking how the sprint felt. Dig into outliers — was that PR too large in scope? Was it hard to get a review? The data doesn't replace the conversation; it gives it a starting point that's harder to dismiss. End with a concrete working agreement — something like "PRs reviewed within 24 hours" or "no PR open longer than 7 days."

### **After the retrospective**

The daily [team notifications](https://help.swarmia.com/settings/team/team-notifications) digest keeps agreements visible and surfaces slippage before the next meeting. If the team set a PR age or review time agreement, expect to see results within a week.

### Read more

* [How to run developer survey retrospectives in your team](https://www.swarmia.com/blog/developer-survey-retrospectives/)
* [Reduce bias in retrospectives with better data](https://www.swarmia.com/blog/data-driven-retrospectives-stop-fake-improvements/)
* [How we run retrospectives in Swarmia](https://www.swarmia.com/blog/how-we-use-swarmia-at-swarmia/#running-retrospectives)

## 1-on-1s

1-on-1s get more concrete when you have data to open with. The [developer overview](https://help.swarmia.com/features/coach-software-developers) gives managers a view into individual work patterns, contribution history, and focus areas. This data is also visible to the engineer — so the conversation is based on shared information, not a hidden report. The goal is to ask questions, not make judgments; the engineer provides the context.

Look beyond individual output too: who this person collaborated with, how their work fit into the team's delivery, what types of tasks they worked on, and how their time split across new features, improvements, and maintenance. That paints a fuller picture than any single metric.

Instead of "how's it going?", you can ask:

* "Your PRs have been sitting in review for a few days — is something blocking you?"
* "You've been spread across three initiatives this sprint — is the context switching manageable?"
* "Your work log shows a lot of maintenance work this month — is that what you expected?"

## Standups

Standups stay focused on problem-solving when managers review the daily [team notifications](https://help.swarmia.com/continuous-improvement/team-notifications) digest beforehand. It surfaces stuck PRs and at-risk agreements before they need to be raised in the meeting — shifting the standup from status-sharing to unblocking work.

## Director and leadership check-ins

Get a clear picture of engineering progress without attending standups or reading status reports. The key questions at this level are:

* Are our cross-team initiatives on track?
* Where is engineering effort actually going?
* Is maintenance work crowding out new product work?
* Is the organization getting more effective over time?

The right views for answering these are [initiative tracking](https://help.swarmia.com/use-cases/deliver-strategic-initiatives) and [investment balance](https://help.swarmia.com/use-cases/balance-engineering-investments) — more useful than asking each EM for a status update. Focus on "are things improving over time?" rather than "which team is fastest this week?" — trend data matters more than snapshots.


# Drive continuous improvement

Learn how to use surveys, signals, and working agreements to build a continuous improvement practice your team can own.

Continuous improvement works best when teams can drive it themselves, rather than routing everything through leadership. Surveys, signals, notifications, and working agreements are the tools for that. Leaders should make sure their teams know how to use them — and have the mandate to do so.

The process follows a cycle: make work visible, spot patterns, take action.

<figure><img src="/files/6ZAxd0M5H9F7RHNqwSHk" alt=""><figcaption></figcaption></figure>

## **Make work visible**

[Developer surveys](https://help.swarmia.com/features/run-developer-experience-surveys) give your team a structured way to surface friction that doesn't show up in metrics — unclear processes, lack of autonomy, poor tooling. Twice a year is a common cadence, but you set it. Results help you spot when something is off and inform which working agreements to introduce or adjust.

Pair surveys with [investment distribution](https://help.swarmia.com/features/focus/balance-engineering-investments) to see how much time goes to KTLO — bugs, incidents, and maintenance. A healthy target is under 30%. If it's consistently higher, that's worth addressing.

## **Spot patterns**

Before setting up any agreements, check what Swarmia's [signals](https://www.swarmia.com/product/signals/) are already telling you. Signals proactively surface patterns in your team's work — too much work in progress, stale pull requests, an unexpected spike in cycle time — without you having to go looking. For each signal, Swarmia explains what happened, why it matters, and suggests next steps, such as adopting a working agreement to prevent the issue from recurring. Benchmarks help you understand whether what you're seeing is normal or an outlier compared to similar teams.

## **Take action**

Clear norms around pull request hygiene and work in progress protect engineers from the most common sources of friction. Limiting batch size and the number of open pull requests keeps work focused and reduces context switching. Shorter cycle times and review times help changes move to production without sitting idle.

Enabling an agreement in Swarmia is just the starting point — real change requires team commitment. Discuss it with your team first: agree on what you're trying to improve and why. Start with one or two [agreements](https://help.swarmia.com/features/working-agreements) so the team can build new habits before adding more.

Each working agreement can have a team [notification](https://help.swarmia.com/settings/team/team-notifications) attached. Exceptions — a pull request that exceeds the batch size limit, or a review that's taken too long — surface automatically in your team's daily digest.

## **Treat it as an ongoing practice**

When you run your next survey, check whether changes to working agreements have had an effect. Improved results mean you're on the right track. If they didn't change, that's an equally useful signal — and a prompt to revisit and adjust.


# Developer effort (FTEs)

Learn how developer effort is measured in Swarmia

Swarmia measures developer effort in FTEs (full-time equivalents) to help you understand how your team's time and effort are being spent across different projects and initiatives. This core metric helps teams use Swarmia to [balance engineering investments](/features/focus/balance-engineering-investments) or [improve team focus](/guides/improve-your-teams-focus).

### How is effort measured in Swarmia?

FTEs reflect the number of hours worked by all employees in an organization. This means that each full-time developer is allocated one FTE per month. Swarmia considers GitHub activities to distribute this monthly effort across the issues and pull requests the developer has worked on, including *commits created*, *pull requests opened*, *pull request reviews*, and *comments*.

In addition to the aforementioned Git activities, we create a comparable event for every day that an issue is set to in progress and assigned to a developer. This helps allocate effort to work that doesn't have direct code contribution.

Activities are weighted differently, with pull requests and commits counted more heavily than reviews and comments.

<figure><img src="/files/dz2t3XFjRuxkRFYilZsU" alt=""><figcaption></figcaption></figure>

We calculate the sum of these data points for a given month and then normalize it for each developer. Normalizing means we take into account different coding and working styles. In practice, this means a developer can have a maximum of 1 FTE in a month, which is distributed between all issues and pull requests the developer has worked on during the month.

We adjust the allocated FTE for extended periods of inactivity and, if your HR system is connected with Swarmia, for logged time off periods.

<figure><img src="/files/RXRX06WulS8mC4XSsTVh" alt=""><figcaption></figcaption></figure>

Here’s an illustrative example of two developers and what their monthly calculations may look like.

<figure><img src="/files/vPiZxIncRofMPTOXOmL3" alt=""><figcaption></figcaption></figure>

There are several ways to improve the accuracy of effort calculation:

### Part-time employees

If your organization considers 160 hours a full-time work month, an employee working 160 hours per month would have an FTE of 1.0. In contrast, a part-time employee working only 80 hours per month would have an FTE of 0.5, indicating that their hours worked are equivalent to half of a full-time employee's hours.

You can [adjust each contributor's default FTE value in settings](https://app.swarmia.com/settings/contributors).

### Occasional contributors

Contributors with fewer than 10 activities per month are excluded. This accounts for occasional contributors in non-developer roles.

### Bots

All bots and events related to bot-authored pull requests are excluded. This also involved reviewing pull requests authored by bots.

### Vacations, sick leaves, and time off

Swarmia supports multiple ways to account for vacations, sick leave, and time off.

If [HR system is connected to Swarmia](/settings/integrations/hr-systems), then vacations, sick leaves, and time off are taken into account:

* Each author's FTE is adjusted based on their available working days in the month.
* Time-offs can be specified in either days or hours:
  * When specified in days, each day counts as a full day off
  * When specified in hours, any partial day off (including half-days) is counted as a full day off
* For example, if there are 20 working days in a month and a developer has 15 work days off, their total FTE would be 0.25 (calculated as (20 - 15) / 20).
* Weekends within the time off periods are skipped.
* Public holidays are not currently considered in the calculations.

If your **HR system cannot be connected**, the time off data can also be imported via CSV files.

As an additional safeguard, Swarmia automatically reduces available FTE when contributors are inactive for extended periods, treating it similarly to time off. If someone has no activity for more than 7 days (5 business days), that period is deducted from their monthly FTE allocation.

### Other considerations

* Only contributors with a linked GitHub user account are considered. You can [review your contributors in the app settings](https://app.swarmia.com/settings/contributors?teamId=4d9361ab-3217-4690-957e-ca69abe9ca07).
* The current month's effort is adjusted. For example, if today is the 15th day, Swarmia attributes only 0.5 FTE for the current month.
* Effort data refreshes daily when looking at the past two months and weekly for older periods.
* Only commits that belong to a pull request are taken into account. For more information see [Why is my commit not visible in Swarmia?](/definitions/frequently-asked-questions/why-is-my-commit-not-visible-in-swarmia)

## Daily effort model (beta)

We're testing an improved way of calculating effort that measures each working day on its own and adds the days up across the month. It's available in beta to a limited set of organizations. [Read more about the daily effort model](/definitions/developer-effort-ftes/daily-effort-model).

## Frequently asked questions

### When does code activity become visible in Swarmia?

Swarmia can only capture code activity once a pull or merge request exists in GitHub or GitLab. Pushed commits on a branch with no open PR aren't tracked, and work that lives entirely on a developer's machine — commits that never reach GitHub or GitLab — can't count toward the 10-activity threshold or FTE attribution either. The model intentionally excludes pre-PR commits to avoid noise from rebases and temporary commits that may not represent real work.

A developer's work becomes visible in Swarmia through any of the following:

* **Opening a draft PR.** This is the earliest point at which commits become visible, and the PR open event itself counts as activity.
* **Opening a PR.** The PR open event counts, and all commits on the branch become visible at the same time.
* **Pushing additional commits to an open PR.**
* **Leaving or receiving code review comments.**
* **Approving or requesting changes on a PR.**
* **Merging a PR.**

Issue-tracker work also counts: each day an issue is assigned to a developer and set to in progress generates a comparable event.

For more on commit visibility, see [*Why is my commit not visible in Swarmia?*](/definitions/frequently-asked-questions/why-is-my-commit-not-visible-in-swarmia).

### Why is a developer's FTE lower than expected?

A few common reasons:

* **Their commits never reached GitHub or GitLab.** Local commits that were never pushed aren't visible to Swarmia.
* **Their commits are on a branch with no open PR.** Opening a draft PR is the fastest way to get earlier visibility.
* **They're below the 10-activity threshold for the month.** Swarmia excludes contributors with fewer than 10 code or issue-tracker events per month to filter out occasional contributors in non-engineering roles.
* **They don't have a linked GitHub or GitLab user account in Swarmia.** You can [review your contributors in settings](https://app.swarmia.com/settings/contributors).
* **They've been inactive or on extended leave.** Swarmia automatically reduces available FTE after more than 5 business days of inactivity. Time-off data further adjusts the allocation, whether it comes from your [HR system](/settings/integrations/hr-systems), a [CSV upload](/settings/integrations/hr-systems/upload-time-off-data-via-csv), or the [Time offs API](/settings/integrations/swarmia-apis/time-off-api).


# Daily effort model (beta)

A beta of an improved way Swarmia calculates developer effort, measured day by day.

{% hint style="info" %}
This is a beta feature that we're rolling out gradually. It changes how developer effort is calculated, so the numbers it produces can differ from the [current effort model](/definitions/developer-effort-ftes). It isn't available to everyone yet. Reach out to us if you'd like early access.
{% endhint %}

Swarmia is rolling out a new way of calculating [developer effort](/definitions/developer-effort-ftes) by moving the calculation from a monthly to a daily basis. On the current monthly model, a single busy stretch of just a few days can define a large share of the whole month. The new daily model calculates effort one working day at a time. Every working day counts equally, no matter how much activity happened on it, so a single busy day can't dominate the month.

{% columns %}
{% column %}

<figure><img src="/files/ZJJ9Gr3RYHpW6cOd8SLE" alt="Monthly model"><figcaption><p>Monthly model</p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/UlPMCPIscFhCHykLeyc7" alt="Daily model"><figcaption><p>Daily model</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

The new model is also more flexible. The current model only calculates across a whole month, so a calendar month is the smallest period it can report on. The new daily model produces a value for each working day, so you can look at effort by day or by week, not just by month.

We keep refining the effort model based on the data we gather and real usage, making the model more accurate and easier to understand. The new daily model is part of that work.

## How it compares to the current model

|                                                         | Current effort model                                            | Daily effort model (beta)                           |
| ------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------- |
| How effort is calculated                                | From a whole month's activity in one calculation                | Each working day separately, then added together    |
| Inactivity                                              | Only stretches longer than 5 business days are deducted         | Every working day without activity lowers effort    |
| Minimum activity                                        | Contributors with fewer than 10 activities a month are excluded | No minimum, even a single event counts              |
| Contributors with only issue-tracker activity (no code) | Excluded, below the minimum                                     | Receive effort from their assigned in-progress days |
| Activity on pull requests not linked to an issue        | Counted at half weight                                          | Counted at full weight                              |
| Assigned in-progress issues                             | Counted                                                         | Counted, with more weight                           |
| Time-off adjustments and current-month proration        | Applied                                                         | Applied, unchanged                                  |

Two of these changes pull in opposite directions. Dropping the half-weight penalty on unlinked pull requests raises that code work, while giving assigned in-progress issue days more weight raises issue-tracker work. The two roughly cancel out, so the balance between code and issue-tracker work stays close to the current model.


# DORA & deployment metrics


# Change lead time

Change lead time measures the full lifecycle of a pull request from the first commit to deployment.

## Summary

Change lead time is one of the DORA metrics and a key deployment insight found in Swarmia. It measures the time it takes for pull requests to go from the first commit to deployment and helps you identify wait times and bottlenecks in your development process.

[Pull request cycle time](https://help.swarmia.com/pull-request-cycle-time), on the other hand, excludes the last part of the lifecycle, time to deploy, and includes only the time from the first commit to pull request merge.

Despite being related, it makes the most sense to look at pull request cycle time and deployment metrics like change lead time separately. Slow time to deploy might mask the improvements you're making in the rest of your development process.

Using two separate metrics also ensures that missing lifecycle data doesn't skew the metrics. Pull request cycle time can be calculated for all pull requests, whereas change lead time is only calculated for pull requests that belong to applications that have deployments configured in Swarmia.

If a deployment includes multiple pull requests, change lead time is calculated for each pull request. If the same pull request is deployed to multiple environments, change lead time is calculated for each deployment.

## Examples

### **Example 1**

If you have three deployments that took 2 days, 3 days, and 1.5 days from the first commit to deployment, your Change lead time would be 2.17 days.

### **Example 2**

You have two deployments to different environments, each with the same two pull requests:

* Deployment to **staging**:
  * PR **#123**
  * PR **#456**
* Deployment to **production**:
  * PR **#123**
  * PR **#456**

This will be interpreted as four *changes*, each with a Change lead time:

1. From the first commit in PR **#123** to deployment to **staging**
2. From the first commit in PR **#456** to deployment to **staging**
3. From the first commit in PR **#123** to deployment to **production**
4. From the first commit in PR **#456** to deployment to **production**

If you're viewing just these two deployments in [Deployments](https://app.swarmia.com/infrastructure/deployments), the change lead time you'll see will be the average of these four *changes*. In practice, however, we suggest filtering only the most appropriate environment for your analysis.

{% hint style="info" %}
When looking at DORA metrics for a team, they're calculated based on all the deployments that include the team's PRs. If those deployments contain PRs from other teams, that can skew your team's change lead time. Read more on [how deployments are attributed to teams](/features/metrics/track-dora-metrics#how-deployments-are-attributed-to-teams)
{% endhint %}

## Why it matters

Change lead time is an indicator of how quickly you can ship new things to production. High change lead time can indicate too large batch sizes, slow code review/QA, or long CI/CD wait times.

## Benchmarks

* **Great**: < 24 hours
* **Good**: < 5 working days
* **Needs attention**: > 5 working days

## How to use it

Measure change lead time in combination with other deployment and DORA metrics to ensure a healthy balance of speed vs stability in your delivery.

### Setup

Change lead time is not available when using [merged pull requests](/settings/organization/configuring-deployments-in-swarmia/generate-deployments-from-merged-pull-requests) as the deployment source. For more information, see [Deployment settings](/settings/organization/configuring-deployments-in-swarmia).

## Where to find it

You can find change lead time (as well as the other DORA metrics) under [Infrastructure → Deployments](https://app.swarmia.com/infrastructure/deployments).


# Time to deploy

Time to deploy is the average time between a pull request merge and deployment.

## Summary

Time to deploy is one of the [DORA metrics](/definitions/dora-metrics), key to understanding the health of a team’s deployment infrastructure. Measures the time it takes from pull request merge to deployment. Part of [change lead time](/definitions/dora-metrics/change-lead-time).

## Example

If you merge a pull request at 2:10pm and it's deployed by 2:34pm, the time to deploy is 24 minutes.

## Why it matters

Time to deploy helps measure how long it takes to deploy a release into a development, testing, or production environment. Measuring this metric can help improve deployment and delivery methods, processes, and tools.

Useful for understanding how much delay your current deployment process is causing in your deployment process.

## Benchmarks

* **Great:** < 15 minutes
* **Good:** < 60 minutes
* **Needs attention:** ≥ 60 minutes

## How to use it

If you have a high time to deploy or have seen a recent increase, having a discussion with your team to understand the root cause behind this can help unlock key areas for improvement in your delivery.

{% hint style="warning" %}
Time to deploy is not available when using [merged pull requests](/settings/organization/configuring-deployments-in-swarmia/generate-deployments-from-merged-pull-requests) as the deployment source. For more information, see [Deployment settings](/settings/organization/configuring-deployments-in-swarmia).
{% endhint %}

### Where to find it

You can find time to deploy (as well as the other DORA metrics) under Metrics → DORA

## Frequently asked questions

### Why is my time to deploy 0 or missing?

The most common reasons are:

1. **You're using** [**merged pull requests**](/settings/organization/configuring-deployments-in-swarmia/generate-deployments-from-merged-pull-requests) **as the deployment source.** This is because we only know when the PR was merged, but we don't get any signal when it is in production. If you want to track time to deploy, you need to use another deployment source.
2. **The deployment doesn't have** [**associated pull requests**](/features/metrics/track-dora-metrics/how-swarmia-links-prs-to-deployments)**.**
3. **The deployment is a redeployment.** If a deployment has the same hash as the previous one, we label it as a "redeployment" and exclude it from metrics. This is usually a symptom of you accidentally sending the same deployment more than once.
4. **The deployment is reported to have happened before the associated PR merges.** This means the time to deploy would be negative, which we treat as 0.


# Deployment frequency

Deployment frequency is calculated by looking at the total number of deployments that happened in a given time period.

## Summary

Deployment frequency is one of the DORA metrics. It's the average number of deployments per week, over a given timeframe. It measures a team’s capability to move fast in practical terms: how long it takes to change something in production.

In Swarmia, we take the average of this number in a given time period and show the average number of deployments per day as the deployment frequency.

## Example

Between Monday and Friday, there were 25 deployments. That gives us a deployment frequency of 25, and an average deployment frequency of 5 deployments per day.

## Why it matters

Deployments are what makes work visible to the users, or in other words, what makes it possible for your work to deliver a business impact.

According to the authors of Accelerate, elite teams are able to deploy new code on-demand or multiple times per day, and the release frequency of high-performing teams is between once a day and once a week.

## Benchmarks

* **Great:** Continuously ( ≥ 10 deployments per week)
* **Good:** Daily ( ≥ 5 deployments per week)
* **Needs attention:** Less than daily ( < 5 deployments per week)

## How to use it

Monitoring your deployment frequency and tracking increases or decreases can help indicate certain issues in your system or process. For example, a low deployment frequency can indicate working with large batches or signal other problems, such as poor deployment infrastructure or lack of reliable automated tests.

## Where to find it

You can find deployment frequency (as well as the other DORA metrics) under Infrastructure.


# Mean time to recovery

Mean time to recovery represents the average time between a failing deployment and a deployment that is marked as a fix.

## Summary

Mean time to recovery (MTTR) is one of the DORA metrics, key to understanding your deployment health. This specific metric helps teams understand how quickly they're able to resolve issues.

In Swarmia, a fixing deployment is a deployment that has `fixesVersion` attribute specified.

## Example

If a deployment failed at 12pm on a Tuesday, and then a fix was deployed at 5pm that same day, the **time to recover** would be 5 hours.

**Mean time to recovery** looks at all the detected TTRs in a give time frame and calculates the average.

## Why it matters

Low MTTR is key for an excellent customer experience, because it indicates minimal downtime or other critical issues in the product.

## Benchmarks

* **Great:** < 60 minutes
* **Good:** < 3 hours
* **Needs attention:** ≥ 3 hours

## How to use it

Time to recovery (TTR) can be determined for each failure as the time between the original deploy and the fix for the problem. TTR can be used to understand the impact of each change failure (how long did the problem last, and what was its impact to the customer).

## Where to find it

You can find mean time to recovery (as well as the other DORA metrics) under Metrics → DORA.


# Change failure rate

Change failure rate is the ratio of failed deployments to all deployments.

## Summary

Change failure rate is one of the DORA metrics and a key deployment health metric in Swarmia. The exact definition of a *change failure* is up to you. As a rule of thumb, it should be an incident that must be **remedied immediately** instead of waiting until the next regular deployment. If a deployment introduces a bug that doesn't need an immediate reaction, it probably shouldn't be defined as a change failure. Failed deployments (ie, when a deployment doesn't reach production) are not change failures either, at least as long as they don't cause a production incident.

Swarmia uses deployments as the basis for change failures. Deploys that fix other deploys (eg, [revert, rollback, hotfix](/features/metrics/track-dora-metrics/automatic-change-failure-detection)) mark the original deployment as a failure.

Change failure rate = change failures / total number of deployments

## Example

If you completed 20 deploys in a week, but 5 of those led to a change failure, you would have a change failure rate of 25%.

## Why it matters

A high change failure rate can indicate either an issue in your quality or deployment systems that needs to be improved.

## Benchmarks

* **Great:** < 5%
* **Good:** < 15%
* **Needs attention:** ≥ 15%

## How to use it

If you see an increase in your change failure rate, you might want to dig into the root cause with your team to help alleviate any issues in delivery.

## Where to find it

You can find the change failure rate (as well as the other DORA metrics) under [Metrics / DORA](https://app.swarmia.com/metrics/dora) or [Infrastructure / Deployments](https://app.swarmia.com/infrastructure/deployments).


# Throughput

Throughput is defined as the number of pull requests you get through as a team over a selected period of time.

### Example

If your team closed 4 pull requests on Monday, 2 on Tuesday, 6 on Wednesday, 0 on Thursday, and 8 on Friday, you would then see an average throughput of 4 pull requests a day for that week.

### Why it matters

Throughput allows you to see the amount of work that is completed during a given time frame. A substantial increase in throughput means your teams are shipping more code.

### How to use it

When looking at the throughput chart, the colors on the stacked bars represent the status of the pull requests opened on that specific day. We recommend focusing most on the yellow part. Seeing a lot of yellow in the past would indicate that on some days, we open a lot of pull requests but are just unable to get them in. In that case, it might make sense to focus on getting the old pull requests merged or closed before taking on more work.

### Where to find it

You can find throughput in two places within Swarmia:

* Pull Requests page
* Insights → Code → Overview


# Normalized throughput

Normalizing issue or pull request throughput by active full-time equivalent developers helps make teams and time periods more comparable.

Your team's capacity is always in flux. People switching teams, sick leave, and holidays all affect what your team can realistically deliver. This makes it difficult to compare productivity across different time periods, let alone across different teams.

**Normalized throughput** accounts for this by dividing completed work by the average number of active full-time equivalent (FTE) developers during a given timeframe. The result is a fairer, more consistent measure of team output.

Normalizing works with both completed issues (epics, stories, tasks) and merged pull requests. When comparing across teams, story-based metrics are most meaningful when teams share a common definition of a story.

### How it's calculated

**Normalized throughput = Completed stories (or PRs) ÷ Average active FTE**

**Example:** Looking at August through October, Team A completed 15 stories. The team has 5 developers, but 2 were fully out for the entirety of August. Averaged across the three-month period, this works out to 4.33 active FTE. Their normalized throughput is **15 ÷ 4.33 = 3.5 stories per FTE**.

### Why it matters

Team size on paper rarely reflects who's actually available to work. Normalized throughput accounts for real capacity (not just headcount), so comparisons across time periods and teams are actually meaningful.


# Batch size

Batch size measures how much work is bundled up in a change. Swarmia offers tools for evaluating pull request batch size by looking at the total number of changes in a single pull request.

## Definition

Batch size is calculated by the lines of code changed (lines added + lines removed) in a given pull request.

### Excluding auto-generated files

Repositories often contain generated files, which could be related to e.g. package dependencies. In order to provide an accurate view of the real changes, Swarmia automatically cleans up the total change count of some commonly used generated files.

You can configure these exclusions in [Settings > Pull requests > File exclusions](https://app.swarmia.com/settings/pull-requests/file-exclusions). Swarmia provides an extensive set of default rules to filter out most common generated files.

## Example

A pull request with 541 lines added and 215 lines removed (<mark style="color:green;">**+541**</mark> <mark style="color:red;">**-215**</mark>) has a batch size of **756**.

## Why it matters

Splitting work into small increments is a great way to improve delivery. Small pull requests are easier to plan and review, and less risky to deploy.

Read more in [Analyzing pull request batch size](/guides/improve-pull-request-flow/analyzing-pull-request-batch-size)

## Batch size benchmarks

* **Great:** < 200 lines
* **Good:** < 500 lines
* **Needs attention:** ≥ 500 lines

## How to use it

In Swarmia, the chart that shows the pull request size vs cycle time shows a set of pull requests in the selected time frame and charts them based on their individual cycle time and the total number of lines of code changed in the pull request. This chart allows you to see correlations between the size of a pull request and its cycle time.

<figure><img src="/files/X00vFxBfiGHF86woQyvv" alt=""><figcaption><p>Pull request size vs. cycle time plot in Swarmia</p></figcaption></figure>

Seeing the distribution of larger batch sizes and higher cycle times can indicate that your team needs to focus on delivering smaller batch sizes. This change can improve not only your cycle time but also your quality.

See also [Analyzing pull request batch size](/guides/improve-pull-request-flow/analyzing-pull-request-batch-size)

## Where to find it

You can find batch size metrics under [Insights → Code → Batch size](https://app.swarmia.com/insights/code/batch-size).


# Issue cycle time

Issues progress through various stages of completeness during their lifetime. Swarmia automatically calculates key properties and metrics for each issue.

## Issue status

Every team has slightly different conventions for how they use their issue tracker. Swarmia allows you to smooth out these differences through the [status mapping configuration](https://app.swarmia.com/settings/issue-trackers) so that every issue always has one of the following statuses: **To Do**, **In Progress**, or **Done / Won't Do**. This helps make the status of work comparable across different teams in the same organization.

The progression of issues through these statuses may not always be linear - someone might start working on a bug, only to realize they're out of their depth, and leave it for someone else. In this case, the status of the issue might've gone from **To Do** to **In Progress**, and then back again to **To Do**.

## Cycle time

**The cycle time of any work is the amount of time it has spent in the In Progress status, according to your issue tracker.**

Most often, this is simply the time between starting the work (status becomes **In Progress**) and finishing it (status becomes **Done**).

More complex status histories are also accounted for. For example, if you work on an issue for 1 week, but then your priorities change, and that work is postponed for 3 months. You then start working on it again and finish it after 1 week. With this history, the issue will have a cycle time of 2 weeks, not 3½ months, as long as the issue was moved out of the **In Progress** status for the 3-month break.

You can see when each issue went into and out of the **In Progress** status from the Issue Activity Popup (accessible by clicking on any issue key found on Swarmia).

<figure><img src="/files/Z1oXkhgf3t0jmw1IJTQZ" alt=""><figcaption><p>The activity pane shows when an issue transferred into in progress with the "Start" and "End" labels.</p></figcaption></figure>

### **Incomplete cycle times**

Swarmia also calculates incomplete cycle times for issues that are not yet **Done**. Such incomplete cycle times are clearly indicated in the UI and don't contribute to aggregate metrics such as your team's average cycle time.

### **Undefined cycle times**

If an issue moves directly from **To Do** to **Done** status, its cycle time is not defined. This may happen when someone completed their entire work on an issue without ever updating the issue tracker, and the status of the issue is later corrected.

Such undefined cycle times do not reflect reality, and also do not contribute to aggregate metrics such as your team's average cycle time.

### **Off-hours handling**

Swarmia doesn't differentiate between work time and off-time in cycle time calculations. That is, weekends count as cycle time, as do non-business hours of the day.

This may seem unintuitive, or even unfair at first, but consider the following:

* Many teams are distributed, and work may happen at various time zones
* Even co-located teams have members with different work habits: someone shows up at 7 AM, someone squeezes in a bit of work time after 9 PM after putting the kids to bed
* Different countries have different national holidays
* Teams have off-sites and trainings which are not holidays, but not regular work time either

Attempting to take all of this into account would result in a number that's too complex to understand, not comparable across teams.


# Flow efficiency

The flow efficiency of an issue is the percentage of days when the issue was actively worked on compared to its whole lifetime.

Flow efficiency measures the share of active days during the lifetime of an issue. Flow efficiency calculation considers only the business days within the lifetime.

This number helps you quantify focus: for a focused team, making steady progress towards completing the issue, the number will be close to 100%. On the other hand, for a team trying to complete too many work items at once, the number will be significantly lower. Increasing your flow efficiency helps you deliver value earlier and eliminate waste.

## Related metrics

#### Lifetime

The **lifetime** of an issue is the amount of time between its first and last activity, according to merged data from your issue tracker and your version control system.

#### Active days

The **active days** of an issue are the number of days on which the issue has had activity. Issue activity includes all [effort](/definitions/developer-effort-ftes)-generating events tied to the issue, such as commits, pull requests, reviews, and issue-in-progress events, which capture when an issue status is in progress and assigned to an individual.

Flow efficiency excludes weekends from the efficiency calculation.

{% hint style="info" %}
April 16, 2026 – The definition of flow efficiency was changed to include issue-in-progress events. In addition, initiatives and issues were updated to work identically.
{% endhint %}

## Example

If an issue from your issue tracker was opened on May 1st and completed on June 6th, we would first calculate that it had a lifetime of 36 calendar days. However, for the purpose of flow efficiency, we consider only business days (weekdays, excluding weekends). Suppose there are 26 business days in that timeframe. Then, we look at how many of those days had recorded activity—either from child issue movement or GitHub activity—to determine the number of active days.

Let’s say there were 10 active business days. The flow efficiency would then be calculated as:

> (10 active days / 26 business days) × 100 = 38%

## **Flow efficiency excludes weekends**

In contrast to cycle time, flow efficiency accounts for weekends. That is, if your issue lifetime is from Monday to the Friday of the next week, and there is version control activity on each weekday, the issue's flow efficiency will be 100%, even if there is a weekend in between.

This special handling of off-hours is so you have an intuitive target to aim for: less than 100% to avoid spreading your focus too thin; more than 100% to ensure your pace is sustainable.

## Why it matters

Low flow efficiency also indicates problems with focus and context switching, which can negatively impact developer experience. This also means you likely could have shipped sooner, and delivered value to your users more quickly.

## How to use it

If you notice an issue has a flow efficiency of less than 80%, have a discussion with your team about what caused that. Was it because there were too many other work items in progress? Was the initial piece of work poorly defined, leading to bottlenecks and scope creep? Depending on the answer, you can then take steps to improve in future cycles. There could also be an opportunity here to adopt a working agreement for your team to help drive higher flow efficiency.

## Where to find it

You can find flow efficiency (and other flow metrics) by opening an issue popup anywhere in Swarmia where you see the name of an issue.


# Scope creep

Scope creep measures the amount of work added to an issue while it was in progress.

### Summary

Scope creep is measured by the amount of child issues created after an issue has first moved to an 'in progress' status. Scope creep is calculated as the ratio of these created issues and the original issues in the story.

### Example

A story that had 8 issues when started and 12 issues when completed has a scope creep of (12-8)/8 = 50%

### Why it matters

Scope creep is an indicator of planning quality. Some amount of scope creep is to be expected, but a high scope creep starts to indicate a problem with the planning process.

### How to use it

Look for issues with unusual amounts of scope creep (significant outliers) to start discussions while the issue is still fresh in memory, and analyze the subtasks using the issue popup. Was this expected or something that could have been prevented? Is there something that the team can learn from this? Which subtasks were added after starting, or which of them took the longest?

Also, be on the lookout for consistently high scope creep (at least 50% on average): this might indicate a more systemic problem with the planning process. Perhaps you need to put more emphasis into story planning to avoid the same surprises in scope. Are you consistently forgetting some types of tasks, like documentation or instrumentation? Planning templates can solve some of these problems.

### Where to find it

You can find scope creep by clicking open an issue popup anywhere in Swarmia where you see the name of an issue.


# Definitions FAQ


# How do you treat weekends in metrics?

In most metrics weekends are included as is. For example when we're talking about a cycle time of a pull request, 14 days means two full calendar weeks.

This is a trade-off with the numbers being understandable and reflective of calendar time, while helping you drive improvement when the team is already doing great. There are other holidays and out-of-office days anyways included in these numbers, so we felt that just excluding weekends now would give you a false sense of accuracy.

Over time the numbers will even out.

We have an exception with the review times, since it's one of the more action-oriented metrics and there's a related Working Agreement. The review time excludes weekends so that the team can focus on getting a quick turnaround time.


# Tracking squashed commits

GitHub allows you to "squash" commits before merging a pull request. Swarmia supports this workflow.

It's possible to [squash commits](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#merge-message-for-a-squash-merge) when merging a pull request to keep the commit history clean – your individual commits will be replaced with one commit for the whole pull request. It makes it slightly easier to use commands like *git blame* to see which feature contributed to a change, but on the other hand it loses some detail about why a specific change was made. It's mostly a matter of personal preference, and we see teams deciding either way.

Squashing commits might cause issues with some other analytics tools because you're losing some detail from the history of a pull request, as it now looks like it was a single commit. In other tools this might mess up calculating things like cycle times.

Swarmia will keep the history available in the context of the pull request. This way we'll report cycle time correctly, and you'll see the detailed work in views like Work Log.


# How do merge queues affect my metrics?

GitHub supports merging pull requests using a merge queue. This doesn't affect the definitions of cycle time or DORA metrics.

## Pull request cycle time

In regular trunk-based development, the [“Time to merge” component of pull request cycle time](/features/metrics/pull-request-cycle-time) stops once the PR is merged. This can be thought of as “concluding” the work on that PR.

Using [merge queues](https://github.blog/2023-07-12-github-merge-queue-is-generally-available/), engineers often conclude their work on the pull request by adding it to the merge queue, from which it eventually gets merged to the main branch. However, before the PR passes all the checks required by the merge queue, and is actually merged, Swarmia will keep counting time towards the “Time to merge” of that PR.

This ensures that, when looking for bottlenecks in your pull request cycle times, a congested merge queue will be correctly visible as the thing you should focus on to reduce cycle time.

Also, if a PR is bounced back from the merge queue due to CI failures, its “Time to merge” will continue until the problem is corrected, and the pull request is merged to the main branch. This helps you notice if many of your PRs tend to bounce back from the CI, and are then forgotten about.

## DORA metrics

The above applies equally to [DORA metrics](https://help.swarmia.com/deployment-insights), where pull request cycle times are involved. Specifically, your "Time to deploy" will only start counting after a pull request has successfully exited your merge queue, and has been merged to your main branch.


# Why is my commit not visible in Swarmia?

We include only commits from pull requests. Check that the pull request is visible in Swarmia.

## If the commit belongs to a pull request

Check that the pull request is visible in Swarmia:

* [The repository](https://app.swarmia.com/settings/repositories) is synced to Swarmia
* The pull request is not [excluded](https://app.swarmia.com/settings/pull-requests)
* The pull request is assigned to the [correct team](https://app.swarmia.com/settings/team/pull-requests)

## If the commit doesn't belong to a pull request

We include only commits from pull requests.

The primary reason for this behavior is to avoid cluttering the [work log](/features/focus/analyzing-the-activity-patterns-on-work-log) with commits that may not represent "real work". Workflows involving rebasing can create numerous duplicate or temporary commits, and including them would make the worklog noisy and could misrepresent development activity. Swarmia's model assumes that development work is captured through pull requests.

As a result, daily commits made to a feature branch will remain invisible in Swarmia until a PR is created.

The only exception is the "[avoid pushing directly to the default branch](https://app.swarmia.com/working-agreements/explore/no-direct-pushes-to-main-branch)" working agreement, which follows commits pushed directly to the default branch of each repository.

{% hint style="info" %}
Tip: If you'd like to get faster visibility into commits, you can create draft pull requests for your work in progress.
{% endhint %}


# What happens when people switch teams or leave?

Swarmia tracks the historical team memberships of contributors over time. Contributions made for one team will stay correctly attributed, even if their author later switches teams or leaves.

In any organization, people switching teams or leaving the company is a common occurrence. Swarmia is designed to handle these changes automatically to ensure your engineering metrics remain accurate and reflect the reality of who did the work, and when.

## How it works: Automatic backdating with a smart heuristic

To keep your data accurate, Swarmia uses a smart heuristic to manage historical team memberships. Here’s how it works in different scenarios:

#### Joining the company

When a new person joins your organization and is added to a team in Swarmia, their membership is backdated. This ensures that any work they possibly did before being formally added to the team in Swarmia is correctly attributed to them and their new team.

<figure><img src="/files/NhVBMvLQWla1wjvdDuKs" alt=""><figcaption><p>New person joining the organization and team without any existing contributions</p></figcaption></figure>

<figure><img src="/files/0xw7V3nkZuoWbp04Pbtv" alt=""><figcaption><p>A person joining a team later is correctly attributed all work they did previously</p></figcaption></figure>

#### Switching teams

When a person moves from one team to another, Swarmia detects this change. The new team membership is backdated to the point when they left the previous team. This correctly attributes work done during the transition period to the new team, preventing data gaps.

We consider 10-day window detecting team switches, up to 7 days gap and up to 3 days overlap.

<figure><img src="/files/6E1TeBFNsGosW9McEuP5" alt=""><figcaption><p>Persons membership ended in Team A and joined Team B within 7 days is considered a valid team switch. The gap between is not attributed to either of the team.</p></figcaption></figure>

<figure><img src="/files/TNj2lUeESloWRcCuYVB0" alt=""><figcaption><p>Membership in Team A ended under 3 days, the work done during the overlap is attributed to both teams.</p></figcaption></figure>

<figure><img src="/files/KgCTgefThEfZ1Ect8h1b" alt=""><figcaption><p>The gap between team switch was too long (over 7 days), Team B does also get attributed for the historical work.<br>Team A only gets attributed the work until the membership ended.</p></figcaption></figure>

#### Joining additional team

If a person is added to a new team without leaving another (e.g., joining a "Staff Engineers" team), the new membership is simply backdated. Their historical and present work will be attributed to both teams.

<figure><img src="/files/3Rf8qoxWfBc41HyitKbw" alt=""><figcaption><p>Person joined Staff Engineers team without leaving Team A gets their work attributed to both teams</p></figcaption></figure>

#### Leaving the company

When a person leaves the organization and is removed from their teams (e.g., by being removed from the GitHub organization), their team memberships in Swarmia are correctly ended. Their historical contributions remain attributed to the teams they were part of when the work was done.

<figure><img src="/files/kfkLR8UhVA8LdAwUJLD7" alt=""><figcaption><p>Persons contributions remain attributed to the team(s) they were part of</p></figcaption></figure>

## Team hierarchies

This tracking applies to memberships of contributors, but **does not** extend to team hierarchies. That is, if you move a team to another parent team, the past contributions of that team will move with it.

**Example:** Your team `A` belongs to a parent team `Analytics`, but is later moved to the parent team `DevOps`:

<figure><img src="/files/GKALfS9zD9wGpw9gc9Au" alt=""><figcaption></figcaption></figure>

After the change, if you look at (for instance) the cycle time metrics of the `DevOps` team, you'll see the historical contributions of team `A` as part of it, even though `A` was part of `Analytics` at the time the contributions were made.

This is by design: we consider teams a fundamental unit of the organization, and thus consider their past contributions as being forever theirs. But during reorgs, teams might get shuffled around to different groupings. We consider the metrics of those groups to be the metrics of the teams they're *presently composed of*. Any alternative to this would leave you with team selectors full of teams that no longer exist.

## Deleting teams

If a team is deleted from Swarmia, it also disappears from any metric views where it was shown. By extension, this means their past contributions disappear from any parent teams the team belonged to.

**Example:** Your team `A` belongs to the parent team `Analytics`, but `A` is disbanded and deleted from Swarmia. Its members are assigned to other teams.

After the change, if you look at (for instance) the cycle time metrics of the `Analytics` team, the historical contributions of members of `A` are no longer included (unless the same contributors also belonged to another child team of `Analytics` which was *not deleted*).

This is intentional: including those past contributions would cause inconsistencies between the summary metrics of `Analytics`, and its constituent child teams. For instance, you might see the team `Analytics` having merged 2000 pull requests over the past 6 months, but when you drill in to see the metrics of its child teams, there are none.

## Correct offboarding

The recommended practice is to remove the person from your GitHub organization. This will automatically end their team memberships in Swarmia while preserving their historical data. You should not delete the author's profile from Swarmia, as this will permanently remove their data.

## Exceptions

During a transitional period, some views do not yet take historical team memberships into account, such as the investment balance, focus summary, and AI adoption.


# How do I configure Swarmia if I use the Gitflow branching strategy?

[Gitflow](https://nvie.com/posts/a-successful-git-branching-model/) is a branching model often used with scheduled release cycles to define a set of features as a release. Work is done in *feature* branches that are reviewed and merged to the *develop* branch when they are ready for production. To release a collection of features, the develop branch is merged to the *main* branch.

Because each change is merged twice (first from the feature to develop, and then to main), we need to account for that to avoid double-counting and get accurate [pull request cycle times](/features/metrics/pull-request-cycle-time) and [change lead times](/definitions/dora-metrics/change-lead-time).

## Excluding pull requests from *develop* to *main*

Since the pull requests from develop to main represent releases instead of feature work and often tend to be open for extended periods, we recommend [excluding them from your metrics](/settings/organization/pull-request-data-quality). You can simply set up an exclusion rule based on the develop branch name. (The branch name condition considers the head branch, i.e., the branch you're merging into the base branch.)

<figure><img src="/files/vDBt9N43FXRlMjubc4IH" alt=""><figcaption></figcaption></figure>

Now, your pull request metrics represent the work in feature branches, considering the [pull request cycle time](/features/metrics/pull-request-cycle-time) until changes are merged into the develop branch, i.e., reviewed and ready for production.

## Deployment metrics

In addition to knowing how long it took for you to get the feature branch merged, it's also important to know the [change lead time](/definitions/dora-metrics/change-lead-time), i.e., the time it took from starting to work on the feature branch all the way until it was deployed to production.

Whenever there's a new deployment, [Swarmia automatically finds](/features/metrics/track-dora-metrics/how-swarmia-links-prs-to-deployments) the pull requests that were merged since the previous deployment, considering the pull request exclusions you configured in the previous step. That means you can see all the feature branch PRs included in each deployment.

The release PR (deploy → main) is excluded from the metrics, but you can see it under "Show excluded pull requests" in the deployment popup.

<figure><img src="/files/FogSFjz9UiHV9SYAmZxV" alt=""><figcaption></figcaption></figure>


# Settings overview

The article provides an overview of settings to ensure your data is accurate in Swarmia and links you to further reading and the related settings in the Swramia app.

Data quality is crucial for building trust in engineering intelligence tools and ensuring sound decision-making. Teams often work differently—using Scrum, Kanban, or other practices—which can lead to inconsistencies. Issues like mismatched user identities, inconsistent issue tracking, or conflicting label usage can impact data reliability. That’s why we prioritize accurate and transparent data by showing what's behind each metric, automating the setup whenever possible, and offering tools to close any quality gaps that might remain.

## Organization settings

At the Swarmia organization level, you integrate your tools, configure global settings, and organize your contributors into Swarmia teams. At the team level, you ensure the right issues and pull requests are assigned to teams.

* [**Creating teams**](/settings/organization/managing-teams)**.** To see your data in Swarmia, you need to organize contributors into teams. You can sync teams from GitHub, use Swarmia API, or create teams manually. [Teams & members settings](https://app.swarmia.com/settings/teams).
* [**Contributors**](/settings/organization/contributors)**.** Ensure work items are assigned to the right people. Swarmia automatically merges the identities across the systems contributors interact with. Make manual adjustments as needed. [Contributor settings.](https://app.swarmia.com/settings/contributors)
* [**Issues: projects, types, statuses**](/settings/integrations/issue-trackers)**.** Select projects to sync. Swarmia maps issue types and statuses automatically and you can make adjustments if needed. [Issue tracker settings](https://app.swarmia.com/settings/issue-trackers).
* [**Pull request exclusions**](/settings/organization/pull-request-data-quality#pull-request-exclusions-at-the-organization-level)**.** By default, pull requests from all synced repositories are visible in the Swarmia metrics. Create filters to exclude specific pull requests automatically. [Pull request settings](https://app.swarmia.com/settings/pull-requests).
* [**Investment categories**](/settings/organization/investment-balance)**.** Use Swarmia default settings or define rules on how to group pull requests and issues into investment categories. [Investment category settings](https://app.swarmia.com/settings/investment-categories).
* [**Deployments**](/settings/organization/configuring-deployments-in-swarmia)**.** Configure deployments to track DORA metrics. Swarmia supports multiple setup options to match your needs. [Deployments settings](https://app.swarmia.com/settings/deployments).

## Team settings

Once the organization-level settings are ready, you and the teams can proceed with team-level settings to ensure the right issues and pull requests are assigned to each team.

* [**Mapping issues to teams**](/settings/integrations/issue-trackers/jira/jira-setup#map-issues-to-teams)**.** Assign issues to teams to make them visible in Swarmia. Swarmia automatically suggests a project for each team. If multiple teams use the same project, you can assign the issues with, e.g., labels or custom fields. [Team issue settings](https://app.swarmia.com/settings/team/issues).
* [**Team PR exclusions**](/settings/team/team-pr-exclusions)**.** By default, Swarmia associates everyone's pull requests with all the teams they belong to. You can create rules to exclude specific pull requests from your team. [Team PR exclusions](https://app.swarmia.com/settings/team/pull-requests).
* [**Team notifications.**](/settings/team/team-notifications) Slack and Microsoft Teams notifications make work visible and provide a feedback loop to stick to working agreements to create lasting habits. [Team notifications settings](https://app.swarmia.com/settings/team/notifications).
* [**Inviting team members**](/settings/organization/inviting-team-members)**.** Invite team members to collaborate in Swarmia and enable their personal notifications. [Swarmia home.](https://app.swarmia.com/)
* [**Linking pull requests to issues**](/settings/organization/linking-pull-requests-to-issues)**.** Swarmia automatically links pull requests to issues and offers ways to do it manually when a PR contains too little information to automatically link. [Pull request inbox](https://app.swarmia.com/pull-requests/).
* [**Improving categorization rate**](/settings/organization/investment-balance#improving-categorization-rate)**.** A high categorization rate (more than 80% of work categorized) is essential to have good visibility into where engineering time goes. You can find the items the categorization rules didn't catch and assign the right category in the [Investment balance](https://app.swarmia.com/investment).
* [**Configuring sprints**](/settings/team/sprints)**.** Swarmia automatically selects a Jira board that has Sprints and enables sprint activity tracking. You can change the board in [Team issue settings](https://app.swarmia.com/settings/team/issues).


# Team settings

Configure Swarmia and get up and running with your team

By integrating with your issue tracker and version control, we reveal hidden patterns about your focus and workflow to help you work better together. This guide helps your team get started with Swarmia.

## In a nutshell

Setting up is easy but requires some thinking and discussion as a team to ensure that your data is correct and that nobody gets caught by surprise.

Here are the steps in a nutshell, and the expected results:

* Configure your team memberships on Swarmia → [Contributor Settings](https://app.swarmia.com/settings/contributors) should show all your team members, and nobody else
* Map the issues the team owns → [Flow Insights](https://app.swarmia.com/insights/flow) and [Work Log](https://app.swarmia.com/work) will show data for the issues that belong to the team
* Schedule a daily digest → The team will receive a daily summary of their work in the chosen Slack or Microsoft Teams channel, at the chosen time
* Invite your team to Swarmia → [Contributor Settings](https://app.swarmia.com/settings/contributors) will show a Swarmia check mark under your team members’ names as they join

Now, let’s walk through the steps in a bit more detail.

## Set up team memberships

To get good data from Swarmia, it’s crucial to get your team memberships right. Among other things, Pull Requests are assigned to teams based on what teams their creators and reviewers belong to, which lets teams see all Pull Requests that are relevant to them in a simple real-time dashboard.

See [this guide](https://help.swarmia.com/creating-and-managing-teams) to configure team memberships.

<figure><img src="/files/9gQyJM7qb3bEwNJLFAzG" alt=""><figcaption><p>The Pull Requests view is a dashboard for the team</p></figcaption></figure>

{% hint style="info" %}
**Configure CODEOWNERS on GitHub**

We love it when teams take shared responsibility for their codebase, and when everyone has the opportunity to review each other’s contributions. A great way to do this automatically is by defining a team as the code owner in GitHub.

[Check the GitHub doc about code owners here](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners).
{% endhint %}

When your GitHub setup is right, this should be reflected in [Contributor settings](https://app.swarmia.com/settings/contributors). Check that all your team members, and only your team members, are displayed when you select your team from the dropdown menu. Also check that there are no duplicate identities. If there are duplicates, you can merge them by ticking their boxes and hitting the Merge button.

## Map issues that belong to the team

Your issue tracker tells you what was planned or expected, while your version control tells you what actually happened. Swarmia helps you connect the dots by linking Pull Requests to issues, and visualizing the relationship between the two on a timeline we call [Work Log](https://app.swarmia.com/work).

In order to take benefit of this feature, you'll need to [connect and configure](/settings/integrations/issue-trackers/jira) the Jira integration. If this has already been done for the organization, you only need to [map the team ownership](https://help.swarmia.com/jira-issue-mapping#team-ownership) to tell which issues interest your team.

<figure><img src="/files/eVgKqv8kcO3TsD9ACu0i" alt=""><figcaption><p>Work Log connects issues from your tracker with activity from your version control</p></figcaption></figure>

## Connect to Slack or Microsoft Teams

Lots of apps are competing for your attention on both Slack and Microsoft Teams, and we don’t blame teams who banish noisy apps to their own channels never to look at them again. We hate spam as much as you do, so in addition to judicious notifications when an action is expected, Swarmia sends exactly one message to the team per day.

{% hint style="info" %}
**Remember to talk with the team**

Don’t forget to talk with your team and get everyone’s opinion before setting up the daily digest. Sudden broadcasts about all the work that’s going on can feel disruptive if they start arriving on the team’s channel without explanation.
{% endhint %}

The daily digest is a summary of relevant Pull Requests, issues and Working Agreements. Use it as a conversation starter for your daily standup, or just a reminder to help you keep track of open topics and stick to new Working Agreements.

![The daily digest is a summary of relevant topics for the team](https://help.swarmia.com/hubfs/slack_digest_2-png.png)

To set up the daily digest on Slack or Microsoft Teams for your team, go to [Settings → Team → Notifications](https://app.swarmia.com/settings/team/notifications), select your team, and schedule the digest. If you’re doing daily standup meetings with the team, try scheduling the digest to a few minutes before the meeting.

## Invite team members

It’s not necessary for developers to start using yet another web app that disrupts their workflow. Most day-to-day interaction with Swarmia such as staying on top of Pull Requests and Working Agreements happens over Slack or Microsoft Teams. However, to get personal notifications when something is expected of you, you need to create a personal Swarmia account and connect it to Slack or Microsoft Teams.

![Swarmia sends you direct messages on Slack and Microsoft Teams only if something is expected of you](https://help.swarmia.com/hubfs/swarmia_dms-png.png)

To invite your team members, just copy the invitation link either from the [front page of Swarmia](https://app.swarmia.com/) or from the [Contributors page](https://app.swarmia.com/settings/contributors) and share it with your team. If they have access to your GitHub organization, the link lets them access the tool and create an account.

If some team members already have accounts but have not connected Slack or Microsoft Teams, they can do so by navigating to [Manage notifications](https://app.swarmia.com/notifications) under your profile picture and clicking on **Slack** or **Microsoft Teams**.

## Continuous improvement with Swarmia

### **Managing pull requests**

Lack of visibility is a common reason why Pull Requests are stuck in a queue or just forgotten. The first thing we recommend is to start regularly checking the [Pull Requests view](https://app.swarmia.com/pull-requests), where it’s easy to spot problematic Pull Requests and get a clear picture of the team’s throughput. Going a bit further, it’s a great idea to get into the habit of quick code reviews with a [Working Agreement](https://app.swarmia.com/working-agreements). You can read more about reviewing Pull Requests faster with Swarmia [in our case study](https://help.swarmia.com/review-code-faster).

In the Pull Requests view, you can also manually link Pull Requests to issues. Linking Pull Requests to issues is another habit worth getting into, as it enables Swarmia to reveal hidden patterns about your focus and workflow in Work Log.

{% hint style="info" %}
**Linking Pull Requests to issues**

You don’t need to visit Swarmia to link Pull Requests to issues. It’s enough to include the issue key in the Pull Request title (e.g. Foobar \[DEV-123]) or start the GitHub Branch name with the issue key (e.g. DEV-123-foobar). And if you merge an unlinked Pull Request, Swarmia will send you a message on Slack where you can select an issue from a dropdown.
{% endhint %}

### **Retrospectives with Swarmia**

Getting into the habit of discussing [Pull Requests](https://app.swarmia.com/pull-requests) and analyzing why some get stuck is a great way to embark on the journey of continuous improvement. Systematically analyzing exceptions to Pull Requests and other Working Agreements will reveal new areas of improvement that you can address as a team.

Are you working on too many things at once? Are you working and learning effectively as a team? As long as you’re linking Pull Requests to issues, reviewing the [Work Log](https://app.swarmia.com/work) in retrospective meetings will reveal any issues with focus, siloing and flow that you may be experiencing, [among other important patterns](https://help.swarmia.com/diagnosing-common-issues-with-work-log).

Are your builds fast and reliable so developers can create small Pull Requests that are easy to review and merge with confidence? [Continuous Integration Insights](https://app.swarmia.com/insights/quality/ci) will help you understand and prioritize possible issues with the build pipeline.

{% hint style="info" %}
**Make it a habit**

To drive continuous improvement systematically as a team, consider getting into the habit of analyzing [exceptions to Working Agreements](https://help.swarmia.com/about-working-agreements) and [patterns in Work Log](https://help.swarmia.com/diagnosing-common-issues-with-work-log) in your team retrospective meetings.
{% endhint %}

### **Get in touch**

Do you have any questions or comments about using Swarmia? Is something missing, or can we do something differently to better support your team? Don’t hesitate to reach out on the in app chat or Slack, or just email us at <hello@swarmia.com>.


# Team


# Team PR exclusions

By default, Swarmia associates everyone's pull requests with all the Swarmia teams they belong to. You can create rules to exclude specific pull requests from the team.

[Swarmia pull request team settings](https://app.swarmia.com/settings/team/pull-requests)

<figure><img src="/files/wrAjhckaasCY8IGQnqju" alt=""><figcaption></figcaption></figure>

You can also manually exclude any individual pull request from your metrics, for example, if you spot an old pull request that won't be worked on and don't want to include it in the metrics.

<figure><img src="/files/EA0GCPniZ3ihdddbIpte" alt=""><figcaption><p>Manual exclusion of individual pull requests</p></figcaption></figure>

The pull request details pop-up shows if the pull request has been automatically excluded.

<figure><img src="/files/SJt9TK7SQD8al2Fj8ZFV" alt=""><figcaption></figcaption></figure>


# Issue ownership

## What is it?

In Swarmia, you can assign issue ownership to a specific team using issue ownership mapping. When looking at a specific team across various views, such as focus summary and investment balance, you'll see a yellow icon indicating issues the team contributed to but doesn't own. You can also toggle "Show only issues owned by team" to hide these cross-team contributions. Work log, on the other hand, shows only issues owned by the team.

## Map issues to teams

When you create a new team, Swarmia automatically suggests a project to map to it. If you have a setup where multiple teams use the same issue tracker project, you can assign the right issues to Swarmia teams based on, e.g., labels or custom fields. Assigning issue ownership for teams is an essential step, as only then will the Jira issues and related data be visible in Swarmia.

[Swarmia issues team settings](https://app.swarmia.com/settings/team/issues)

<figure><img src="/files/SIkRFi0DpYSqQG5hNfvU" alt=""><figcaption><p>A project-based issue ownership assignment</p></figcaption></figure>


# Team notifications

Teams can configure review reminders and regular digests to be sent to their specified Slack or Microsoft Teams channel. These notifications improve the team's understanding of their work and process and provide feedback loops to stick to their working agreements and create lasting habits.

<figure><img src="/files/zaSRPRFB8qdOAO41CH3z" alt=""><figcaption></figcaption></figure>

## Daily digest

Sent to your team's channel once a day by default, Swarmia's daily digest shows pull requests, issues, and working agreements that require your team's action, keeping the noise level to a minimum.

Navigate to [Settings → Team → Notifications](https://app.swarmia.com/settings/team/notifications) to set up reminder for your team's channel.

<figure><img src="/files/X5kA5SqTrU4vCYQdwvk7" alt=""><figcaption></figcaption></figure>

You can choose the types of information to include in the digest:

* **Pull requests in review, in progress, and merged*****:*** PRs waiting for review and ready to merge are highlighted separately. PRs owned by other teams are not included, even if a review has been requested from your team.
* **Issues completed and in progress**
  * [Jira](/settings/integrations/issue-trackers/jira): includes stories and tasks
  * [Linear](/settings/integrations/issue-trackers/linear): includes issues
* **Working agreements: summary and exceptions:** This is the most convenient way to keep track how you're doing with your [working agreements](https://github.com/swarmia/knowledge-base/blob/main/notifications/broken-reference/README.md).
* **Live surveys**: List all live [surveys](/features/run-developer-experience-surveys) with responses pending from your team.

## Issue summaries

Issue summaries let teams celebrate success when they complete work. They also help teams improve the quality of plannings and retrospectives.

When complete a larger issue (epics or stories), you'll get a notification to your team's Slack or Microsoft Teams channel.

### **What's included in the summary?**

* **Issue cycle time**. If you have a working agreement around cycle time, the summary includes a comparison against your target.
* **Scope creep:** child issues added while the issue was in progress.
* **Child issue that took longest to complete**, and **avg. completion time**
* **Contributions:** people who have linked coding contributors to the issue

<figure><img src="https://d33wubrfki0l68.cloudfront.net/eb1f3eafef1a18ae4d28cd46025a5b42d72f2fb2/0ca9c/static/c3c57372bd876db95df85917dbbe1b8e/d376b/issue-summaries.png" alt=""><figcaption></figcaption></figure>

### **Enabling issue summaries**

Go to [Settings → Team → Notifications](https://app.swarmia.com/settings/team/notifications), select your team and make sure you have the right Slack or Microsoft Teams channel selected. We recommend using your team's main channel for issue summaries and other important, infrequent Swarmia updates.

### Team review reminders

If your team has a practice of requesting reviews from your GitHub team rather than some specific contributor, the team review reminders is a perfect tool to make sure that the reviews are getting noticed and merged.

By enabling this feature for your team in Swarmia, you'll get notified in the selected channel whenever a review is request from your GitHub team. When someone picks up and completes the review the notification in the channel is crossed over.


# Sprint configuration

To view Jira data in Swarmia, you must first assign the appropriate Jira board to your team.

When you [configure Jira issue ownership mappings](https://github.com/swarmia/knowledge-base/blob/main/getting-started/configuration/broken-reference/README.md), Swarmia will automatically select a board that has Sprints and enable sprint activity tracking.

If your board is not automatically selected or you need to change the board for your team, you can go to [Team issue settings](https://app.swarmia.com/settings/team/issues), click "Track sprint activity" and select the correct Jira board for your team.

<figure><img src="/files/m3jyP85lq54v7qWeNvIq" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="success" %}
After configuring the Sprint, you can now go to [Swarmia sprints](https://app.swarmia.com/sprints) and read further at:

* [Sprints](/features/focus/sprints)
  {% endhint %}

#### Private Jira boards

If your Jira board is private, Swarmia cannot access sprint data from it. Private boards will be indicated with a lock icon (🔒) in the board selector.

To use a private board with Swarmia change the board's permissions in Jira to allow organization-wide access.

### Troubleshooting

If you can't find the board in the selection list, make sure your Jira board filter has organization-wide permissions, allowing the Swarmia app to sync your board.

Please reach out to us at <hello@swarmia.com> if you experience any issues with the sprint configuration.


# Organization


# Creating & managing teams

To see your data in Swarmia, you need to organize contributors into teams. You can use three methods to create your teams:

* Create a new team manually in
* Import teams from GitHub
* Import teams with [CSV](/settings/organization/managing-teams/csv-team-import)
* Integrate with [Swarmia Teams API](/settings/integrations/swarmia-apis/team-management)

Navigate to [team settings](https://app.swarmia.com/settings/teams) to get started.

<figure><img src="/files/r8cjlFNhz7whP49A7Bj9" alt=""><figcaption></figcaption></figure>

## **Defining team members**

You can add three kinds of members to teams:

1. GitHub users
   1. You can search and add individual GitHub users to teams in Swarmia.
   2. By default, the search only returns users who currently belong to your GitHub organization. If you need to add users outside of your GitHub organization (e.g., contractors) or historical users (e.g., previous employees), you can find them by searching with their exact GitHub username.
2. GitHub teams
   1. You can add GitHub teams as team members to keep your teams up-to-date with GitHub
3. Contributors not belonging to your GitHub organization
   1. In certain situations, like when working with contractors, it can be beneficial to be able to add contributors from outside of your company's GitHub organization to your Swarmia Teams.
   2. To do this, you must type in their exact GitHub username into the search field.
   3. This adds their contributions to your team's metrics in Swarmia, but they will still not have access to your Swarmia instance without access to your GitHub organization.

Importing teams in Bulk from GitHub allows you to select multiple GitHub teams and to quickly create new Swarmia teams from those. After you have imported the team, the team memberships are kept in sync with the GitHub teams. When importing teams, we show you which teams are already imported and which teams you can still select to import.

## Setting up hierarchies

Creating the team hierarchy is simple and easy within Swarmia.

1. Ensure that you have created the 'Parent' team(s) in your team structure.
   1. This parent team will inherit the membership of the later assigned subteams, but in order to first establish the parent team, you will need to add at least one member.
2. Create desired subteams, and map them to the appropriate Parent Team.
   1. Depending on your organizational structure, you might need to repeat the same process multiple times (for different levels of your organization).

You don't need to create a team to resemble your entire engineering organization. You can automatically use the organization level, even if you don't create any hierarchy of teams.

### **Teams with subteams**

* For the most part, teams with subteams work just like other Swarmia teams. **No additional configuration is required.**
  * For teams with subteams, the work shown everywhere across Swarmia is defined as a combination of their subteams’ work.
  * You can add working agreements and enable notifications for teams on all levels.
  * You can add direct members or GitHub teams or to any team, even if the team has subteams.

### **Limitations**

* **Each team can only have one parent team.** This means you can't use team hierarchy to map a matrix organization structure. Please contact Swarmia support via the in-app chat if you would have a need for such a configuration.
* If you convert a team to a parent team, it loses any filters around team ownership it previously had — they will be inherited from the subteams instead.

## Assigning Team admins

You can assign one or more team admins for each team to delete the Swarmia configuration while controlling who can edit memberships and configure team settings. Team admin is an optional selection. [Read more about roles and permissions](/settings/organization/managing-users-and-roles).

<figure><img src="/files/TF6ymX0D099dsS0LRe6C" alt=""><figcaption><p>Assign team admins by editing a team.</p></figcaption></figure>

## Refining team ownership

Teams are important for managing which pull requests (PRs) and issues are included in the data for different Swarmia features, from insights to working agreements. You'll want to ensure that the Pull Request and Issue Ownership of your team is correct to ensure the most accurate metrics. Selecting Slack or Microsoft Teams channels enables team notifications and daily digest.

1. Team Pull Request Ownership
   1. By default, we include any PRs created by anyone in the team. You can configure PR ownership rules for teams to adjust which work is included by navigating to the [Team Pull Request page.](https://app.swarmia.com/settings/team/pull-requests)
2. Team Issue Ownership
   1. To unlock Issue data in Swarmia in the Work Log view and Flow Insights, you will first need to assign Team Issue Ownership in [Settings → Team → Issues](https://app.swarmia.com/settings/team/issues).
   2. Once a team has been properly mapped, they will show up as 'assigned' in the Team Management page.
3. Team notification channel
   1. Select a Slack or Microsoft Teams channel to receive team notifications and daily digest. Configure the channel in [Settings → Team → Notifications](https://app.swarmia.com/settings/team/notifications)

Right after you have created the team, Swarmia suggests the right issue tracker project and notification channel for the team. You can confirm, override or skip the selection.


# CSV team import

You can create and update Swarmia teams and memberships in bulk using a CSV file. This is especially useful if you're new to Swarmia and haven't configured your teams yet, or if you already maintain team memberships in a spreadsheet.

### Who is this for?

CSV import is a good fit for organizations that:

* Don't yet have Swarmia teams configured
* Don't have up-to-date GitHub teams or another data source that can be synced via the team API
* Already maintain team memberships in a spreadsheet or can easily export teams as a CSV

### How to get started

Navigate to [Settings → Teams & members](https://app.swarmia.com/settings/teams), click **Create teams**, and select **Create or edit teams with CSV**.

***

### Initial import

Use this flow when setting up teams in Swarmia for the first time.

1. Download the CSV template from Swarmia
2. Fill in your team details
   * teamKey
   * teamName
   * parentTeamKey (optional)
   * memberEmail
   * memberName
3. Upload the CSV to Swarmia
4. Review the proposed changes and confirm

You can create empty teams, for example, parents, by leaving the memberEmail and memberName columns empty. The UI highlights any errors with instructions on how to fix.

<figure><img src="/files/xkSiBh97sePv1zjtE1wE" alt=""><figcaption><p>Example of the initial import file.</p></figcaption></figure>

***

### Updating existing teams

Use this flow to add members, rename teams, or adjust the hierarchy for teams already in Swarmia.

1. Export your current teams and memberships as a CSV from Swarmia
2. Edit the file — add or update teams and remove memberships as needed
3. Upload the updated CSV to Swarmia
4. Review the proposed changes and confirm

You can remove members from teams by typing `TRUE` in the remove column. Teams cannot be removed via the import, but you can do it in the UI.

If you export teams that were created with another method, the teamKey and parentTeamKey columns show the existing Swarmia team ID.

The updates apply only to teams included in the file. Any other existing teams won't be affected by the import.

<figure><img src="/files/3pCuyo5ILm78wMlM9LyP" alt=""><figcaption><p>Example of updating existing teams. Type <code>TRUE</code> in the remove column to remove members from a team.</p></figcaption></figure>

***

### GitHub teams

The CSV import supports two additional columns — githubTeamId and githubTeamName — for assigning/removing GitHub teams as team members. The export automatically includes these columns when any team currently has a GitHub team member.

***

After a CSV import, you can continue making changes to your teams directly in the Swarmia UI.


# Contributors

A Swarmia contributor combines the identities from all the different systems an individual contributor interacts with. By combining the right identities, you ensure work items are assigned to the right people. The identities include email addresses, user IDs, and other information from the connected tools. Swarmia automatically detects identities across the different tools and merges them. You can review contributors and manually merge and unmerge identities as needed.

<figure><img src="/files/6U585kw6NA4lzAmJ1Q1P" alt=""><figcaption></figcaption></figure>

## Bots

Swarmia detects bot accounts automatically, based on the account type in GitHub and on common naming patterns: a `[bot]` suffix in the username, names starting or ending with `bot` or `ci`, known accounts like `github-actions` and `dependabot`, and GitHub's no-reply bot email addresses. Contributors identified as bots show a 🤖 **Bot** badge in the contributor list.

{% hint style="info" %}
Automatic detection only covers GitHub accounts. On [GitLab](/settings/integrations/code-hosting-platforms/gitlab), mark bots yourself.
{% endhint %}

{% hint style="info" %}
Detection of some known bots relies on GitHub.com account IDs, which don't match on [GitHub Enterprise Server](/settings/integrations/code-hosting-platforms/github/github-enterprise-server). On self-hosted GitHub, expect to mark more accounts manually.
{% endhint %}

You can also mark any contributor as a bot yourself.

### Marking a contributor as a bot

Marking contributors as bots requires the [organization admin or editor role](/settings/organization/managing-users-and-roles).

1. Open [Contributors](https://app.swarmia.com/settings/contributors).
2. Select one contributor. The **Bot** toggle appears in the panel on the right, above the merge options. It's only available when exactly one contributor is selected.
3. Turn the toggle on.

Turn the toggle off to treat the contributor as a person again.

The default view on the Contributors page hides bots. To find them, switch the view to **All contributors** or use **More filters** and check **Bot**.

<figure><img src="/files/p0lZ9AgN3O01l9c7CjOr" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
You can't effectively toggle automatically detected bots off, since Swarmia toggles them back on in the next sync if they still match the detection patterns. (Automatic detection only toggles the bot selection on, never off.)
{% endhint %}

### What changes when a contributor is a bot

* **Pull requests.** Bot-created pull requests move to the **Bots** tab on the Pull requests page and are left out of the **From others** tab.
* **Review metrics.** Reviews and comments from bots don't count toward review metrics, and a bot's review doesn't stop the clock on [time to review](/features/metrics/pull-request-cycle-time/time-to-review). Bots don't show up as reviewers or as authors in review reports. ([Review agents](/features/ai-tools/review-agents) have their dedicated metrics in Swarmia.)
* **Code metrics.** Commits from bots are excluded from commit counts and contributor counts.
* **Developer effort.** Bots and the work related to bot-authored pull requests are excluded from [developer effort (FTEs)](/definitions/developer-effort-ftes), and you can't set an FTE value for a bot.
* **Notifications.** You don't get [personal notifications](/settings/personal/notifications) about pull request comments from bots unless you turn them on, and [team notifications](/settings/team/team-notifications) about review requests from bots are off by default. Direct messages about review requests from bots are never sent.
* **Surveys.** Bots aren't included in [developer experience surveys](/features/run-developer-experience-surveys).

Marking a contributor as a bot applies to historical data too, not just new work. Review-related metrics update once Swarmia has reprocessed the affected pull requests.

{% hint style="warning" %}
If you mark a contributor as a bot and later change your mind, their historical developer effort figures aren't recalculated automatically. Email <hello@swarmia.com> and we'll rebuild them for you.
{% endhint %}

### What doesn't change

* **Billing.** Bots don't change your subscription or your contributor count.
* **Overall pull request metrics.** Marking a contributor as a bot doesn't take their pull requests out of your metrics. Bot-authored pull requests still count toward metrics like cycle time, throughput, and batch size. Only the review parts of those metrics ignore bots. To keep pull requests out of metrics entirely, use [pull request exclusion rules](/settings/organization/pull-request-data-quality).
* **AI tools.** The bot mark is separate from [AI tool detection](/features/ai-tools/ai-tool-detection-and-filters). Most AI coding agents are detected as bots and as AI tools, and changing the bot mark doesn't change how their work is attributed to an AI tool.

{% hint style="info" %}
**Bots on teams**

A pull request belongs to a team when its author is a member of that team, and bots can be team members like anyone else. If you add a bot to a team, [its pull requests show up in that team's metrics](/settings/team/team-pr-exclusions) even though it's marked as a bot. Most bots aren't on any team, which is why their pull requests usually don't appear in team views.
{% endhint %}


# Roles and permissions

Overview of Swarmia access control.

## Managing access

* **GitHub.** If you're using GitHub to manage access, all members of your GitHub organization can access Swarmia with their GitHub login.
* **Okta, Google, and Microsoft Entra SSO.** With [Okta](/settings/integrations/authentication/okta-single-sign-on), [Google](/settings/integrations/authentication/google-single-sign-on), and [Microsoft Entra](/settings/integrations/authentication/microsoft-entra-id-single-sign-on) single-sign-on, you can control which users or groups have access to Swarmia.

## Roles and permissions

Swarmia supports role-based access control with the following roles and permissions:

* **Organization admin** has full access to Swarmia and can configure all settings. The first user in your organization (who connected Swarmia to GitHub) has organization admin rights and can assign additional organization admins.
* **Editor** can access everything, except the most sensitive organization settings, software capitalization, and creating developer experience surveys. The editor role is a popular choice among startups that don't require granular permissions and want all users to be able to edit most of the settings.
* **Viewer** cannot edit organization or team settings, and they don't have access to software capitalization or the ability to create developer experience surveys or initiatives. For Swarmia organizations created after October 17th, 2025, the viewer role is the default for new users, and it can be changed to editor or organization admin.
* **Team admin** can access team configuration and settings for a specific team and its sub-teams, and they can assign more admins to their team(s). A user can have the team admin role for one or more teams. Using the team admin role is recommended for organizations that want more control over who can access Swarmia settings, while delegating team configuration to specific people. Team admins are not counted as team members unless directly added as a member.

Each Swarmia user has one organization-wide role (organization admin, editor, or viewer), and in addition, they can have a team admin role for one or more teams.

The table lists all Swarmia permissions that vary by role. If an object is not listed in the table, all roles have full access to it.

<table><thead><tr><th width="217.6953125">Object</th><th>Org admin</th><th>Editor</th><th>Viewer</th><th>Team admin</th></tr></thead><tbody><tr><td>User roles</td><td>Edit</td><td>View</td><td>View</td><td></td></tr><tr><td><a href="/pages/sMjEDF8vqQ5QgFwtRVHT">Subscription</a></td><td>Edit</td><td>View</td><td>View</td><td></td></tr><tr><td><a href="/pages/ApCGSHS2U1sSkpeYe1RD">Integrations</a></td><td>Edit</td><td>View</td><td>View</td><td></td></tr><tr><td><a href="/pages/66nTFbifLcvFyyeCuLhy">Org pull request filters</a></td><td>Edit</td><td>View</td><td>View</td><td></td></tr><tr><td><a href="/pages/t4zEhjikSdJNsXCvtd9b">Investment breakdowns</a></td><td>Edit</td><td>View</td><td>View</td><td></td></tr><tr><td><a href="/pages/990098KkDPpIsg9Ot1gA">Prod. environment filters and hot fit detection</a></td><td>Edit</td><td>View</td><td>View</td><td></td></tr><tr><td><a href="/pages/990098KkDPpIsg9Ot1gA">Deployment applications</a></td><td>Edit</td><td>Edit</td><td>View</td><td></td></tr><tr><td><a href="/pages/1BVALEOOXJFVrPYMwXfQ">Contributor merge</a></td><td>Edit</td><td>Edit</td><td>View</td><td></td></tr><tr><td><a href="/pages/zqmx0CrRpxAACwAnxbUT">Initiatives</a></td><td>Edit</td><td>Edit</td><td>View</td><td></td></tr><tr><td><a href="https://app.swarmia.com/settings/api-tokens">API tokens</a></td><td>Edit</td><td></td><td></td><td></td></tr><tr><td><a href="/pages/TwZ7VqQYzN0bhyf157yE">Survey creation</a></td><td>Edit</td><td></td><td></td><td></td></tr><tr><td><a href="/pages/bTfrQzGuMOvISxNGzaAN">Software capitalization</a></td><td>Edit</td><td></td><td></td><td></td></tr><tr><td><a href="/pages/nyDtkR1LxIo9bxQvkBMo">WBSO timesheet approval</a></td><td>Edit</td><td></td><td></td><td>Edit</td></tr><tr><td><a href="/pages/YhND7p39vpY9bwYSqnnN">Team management</a></td><td>Edit</td><td>Edit</td><td>View</td><td>Edit</td></tr><tr><td><a href="/pages/66nTFbifLcvFyyeCuLhy">Team pull request filters</a></td><td>Edit</td><td>Edit</td><td>View</td><td>Edit</td></tr><tr><td><a href="/pages/d69GUZwKAgxcWzPNhJAY">Team issue mappings</a></td><td>Edit</td><td>Edit</td><td>View</td><td>Edit</td></tr><tr><td><a href="/pages/zq7VoHUgnIW70TemWBIE">Team notifications</a></td><td>Edit</td><td>Edit</td><td>View</td><td>Edit</td></tr><tr><td><a href="/pages/FpxYpZtIsQGt4IWJAfXn">Working agreements</a></td><td>Edit</td><td>Edit</td><td>View</td><td>Edit</td></tr></tbody></table>

### Assigning roles

#### Organization-wide roles

Organization-wide roles (organization admin, editor, and viewer) are managed in [Role settings](https://app.swarmia.com/settings/roles). You can filter users by their role, view the role of each user, and change those individually or in bulk by selecting one or more users. An empty role ('None' in the filter) indicates that the contributor has not signed up to Swarmia or been assigned a role. Assigning roles to contributors who are not yet Swarmia users gives them broader access (e.g., organization admin) when they sign up.

You can change the default role for new users in your organization by clicking the **Set default role** button and selecting a role.

<figure><img src="/files/UNXmgshplHZQff1awVAr" alt=""><figcaption><p>Select one or more contributors to assign roles.</p></figcaption></figure>

#### Team admins

Team admins are assigned in [team settings](https://app.swarmia.com/settings/teams) by creating or editing a team. Team admin is an optional setting, and you can assign one or more admins per team. The team settings page lists admins for each team and allows you to identify teams without one.

<figure><img src="/files/TF6ymX0D099dsS0LRe6C" alt=""><figcaption><p>Assign team admins by editing a team.</p></figcaption></figure>

{% hint style="info" %}
**What do I do when my organization has no admins?**

Your Swarmia account can have no organization admin if all users who had admin rights in Swarmia are removed from your GitHub organization. In this case, email us at [hello@swarmia.com, ](mailto:hello@swarmia.com)and we will help you move forward.
{% endhint %}


# Inviting team members

Invite members with by sharing a link or via Slack.

You can invite team members to Swarmia with an invitation link or via Slack. Both options are available on the home page and team settings under the **Invite members** button.

* **Invitation link** and email template.
* **Slack invite** enables Swarmia's personal GitHub-Slack notifications, providing a quick way to onboard your team to Swarmia. Admins can invite anyone in the organization, while others can invite their own team members. The option is available once your Slack workspace is connected with Swarmia.

All members of your GitHub organization can sign up to Swarmia, or you can control access with [Google, Microsoft, or Okta SSO](/settings/integrations/authentication).

<figure><img src="/files/BIiHIQKBASYDvNh63hc1" alt=""><figcaption></figcaption></figure>


# Investment categories

Everything you need to know about setting up your Investment Balance and configuring your organization's categories.

{% hint style="info" %}
There's a lot going on all the time in most organizations. But are you spending your time on things that matter? Swarmia's Investment Balance helps you find out.
{% endhint %}

### How it works

The Investment Balance shows activity on pull requests and issues grouped by the configured investment categories **and includes both completed issues and merged pull requests.** Over a longer period of time, we've seen that these activities are a reliable proxy for understanding development time.

#### **Multiple investment breakdowns**

You can configure more than one way to break down your work into distinct sets of categories.

The primary breakdown is meant for the most important categorization you want to track company-wide, is visible everywhere in Swarmia, and has a bunch of tools to help you increase data quality.

You can create additional breakdowns that are available on the Investment Balance view and as filters in other views. Reorder breakdowns using drag-and-drop. To set a primary breakdown, place it first.

#### **Activities shown in the report are based on the team members**

If your team members have contributed towards issues belonging to other teams, those issues will also show up. Think of this as not a bug, but a feature: the team is investing its time somewhere, and the report shows you where that investment goes, even if it's not for the things you might've expected.

#### **How work is grouped by category**

We start by looking at all contributions by all team members of the selected team, then determine the investment category based on the rules you've set up.

Then work is grouped by investment category. (These categories are mutually exclusive and collectively exhaustive within any single breakdown.)

If multiple tasks belong to a bigger project, **it's possible to have different investment categories assigned to each task and the project as a whole**. In this case, we'll show each task in its respective category of work.

Each issue or pull request can link only to one category. All work not linked to a category will show up as *uncategorized* for the primary breakdown, or the similar last catch-all category for additional breakdowns.

In other words, categories are *mutually exclusive* and *collectively exhaustive***.**

#### **Determining the category**

The logic for determining an issue’s category works in the following order:

1. Setting the category for the issue manually takes precedence over everything else. (*Manual override*)
2. If the issue matches one or more category filters, it will be linked to the top most matching category. You can re-order the categories in settings.
3. If the issue is a child of another issue (parent) that either matches with category filters or is manually categorized, it will inherit from the parent issue. The inheritance works several steps down the issue hierarchy.
4. If there are no category matches, the issue will show up as *uncategorized*.

For instance, if we have the following issue hierarchy with issues uncategorized, with the exception of one bug that matches the filters for KTLO:

<figure><img src="/files/PtXFrqs3n8vSF88zgVgS" alt="Swarmia - Bug assigned investment category" width="267"><figcaption></figcaption></figure>

If the top epic would then be categorized as *New Things*, all the uncategorized children of the epic would also get categorized as *New Things*. Bug 1 (and any children it might have) would not be automatically categorized as *New Things* (as it matches step 2 in the logic).

<figure><img src="/files/po2MbEckSpqBeuVfNdYl" alt="Swarmia - Manually assigned investment category" width="266"><figcaption></figcaption></figure>

Automated filters can be configured in a way that makes an issue match multiple categories. In this case, we'll assign it the first category that matches. You can [**re-order categories in settings**](https://app.swarmia.com/settings/investment-categories) to influence that.

If there are no investment category matches of any kind, the issue is considered *uncategorized.*

The logic for determining a pull request's category is similar:

1. Linking PRs to categories takes precedence over everything else.
2. If the PR is linked to an issue that's categorized, the PR is assigned the same category.
3. If the PR matches one or more investment category filters, it will be linked to the first matching category.
4. If there are no category matches, it will show up as *uncategorized*.

### Configuring your investment categories

You can configure a set of Investment Categories for you organization in the [**Organizational Settings.**](https://app.swarmia.com/settings/investment-categories) There are different ways to think of investment categories. Many of our customers use primarily the [**Balance Framework by Dropbox**](https://medium.com/engineering-operations/a-framework-for-balancing-and-budgeting-engineering-resourcing-d0cce0e6911c) for balancing engineering investments. Additional approaches to grouping work include:

* Company initiatives
* Product focus areas
* R\&D Capitalization / R\&D expenditure
* Releases, or a company level roadmap (e.g. "Q3")

#### **Setting up your filters**

Using our automated filters, you can assign work to categories based on certain criteria.

We support a variety of filter options for both Pull Request data and Issue data.

Your filter might be as simple as this:

<figure><img src="/files/ylBnAxlV0O6O83MvbJ0Q" alt="Swarmia - Investment categorization filter" width="563"><figcaption></figcaption></figure>

But reality is often a bit messier. In a large organization, each team might have their own little quirks in how they track their work. For instance, let's say most teams use Epics and Stories for Roadmap work... but some also use specific labels for that purpose, and one team stubbornly wants to use their custom Jira issue type.

No problem:

<figure><img src="/files/8xZycvZgGYThjQYWgBXf" alt="Swarmia - Investment categorization filter advanced" width="563"><figcaption></figcaption></figure>

#### **Categorizing work items one by one**

In addition to being able to categorize work items with automated filters, it is possible to directly choose the category of an issue or pull request for the primary investment breakdown. To do that, select an individual work item in one of the many views in Swarmia, then click on Categorize in the popup if the issue is uncategorized or the issue type dropdown if it is currently categorized, then select the desired category.

<figure><img src="/files/ZhVjX5x0oiBpO5ojbjxE" alt="Swarmia - Investment categorization override" width="563"><figcaption></figcaption></figure>

#### Improving categorization rate

A high categorization rate (more than 80% of work categorized) is essential to have good visibility into where engineering time goes. The investment balance view highlights the uncategorized work and makes it easy to assign the right categories for the remaining items.

<figure><img src="/files/vfFQByddrxWckGjwfJUH" alt=""><figcaption><p>Assigning the right investment category to uncategorized items</p></figcaption></figure>

### Best practices

1. **Sort at the highest level available**\
   Use labels or custom fields at the Epic level to quickly categorize work. Child issues and work will inherit the parent's category.
2. **Create catch rules**\
   Sometimes it's easier to create rules to remove certain data points. E.g. capture reactive work by using a rule like 'Jira type is Bugs, Defect'
3. **Start simple**\
   If you don't have the practice of doing this today, start by simplifying the categorization and rules to build the practice over time. If you have an existing way of thinking about this, start there.
4. **Improve over time**\
   Swarmia has tools to help build the practice over time. These include working agreements to help teams link pull requests to issues and tools to help group Uncategorized work.

<table><thead><tr><th width="380.30859375">Visualization</th><th>Example</th></tr></thead><tbody><tr><td><img src="/files/C9rrnvG9dt4dbG9Jx7WT" alt="" data-size="original"></td><td>No categorization applied yet — all work items are uncategorized.</td></tr><tr><td><img src="/files/e8zaijVBnMDJZfOqL6AK" alt=""></td><td>Items labeled <strong>Feature</strong> are categorized as “New things.” This label is applied at the Epic level, and the categorization is inherited by all child Stories, Tasks, and PRs.</td></tr><tr><td><img src="/files/1u65g145tOWGUBnQksBw" alt=""></td><td>Items with the Jira type <strong>Bug</strong> are categorized as “KTLO.” This overrides the inherited “New things” categorization from the parent and reclassifies them under KTLO instead.</td></tr><tr><td><img src="/files/cm31DzDHjer8q8mvTCPH" alt=""></td><td>Items owned by the <strong>Platform team</strong> are categorized as “Productivity.” This categorization is based on team ownership, not labels or issue types.</td></tr></tbody></table>


# Automatic categorization

Automatic investment balance categorization works to catch issues that slip your rules or to categorize entire breakdowns without rules.

### What is automatic categorization?

AI categorization works alongside your existing rule-based categorization system and applies to issues that are [mapped in Swarmia](/settings/integrations/issue-trackers/jira/jira-setup#map-issue-types-and-statuses). When you toggle it on for a breakdown, Swarmia first applies any categorization rules you've defined. Then, for any issues that remain uncategorized, AI analyzes each issue's description, linked issues, and other metadata to determine the most suitable category based on your category descriptions.

#### What level does AI categorization apply to?

AI categorizes only the highest-level issues in your hierarchy:

* Issues with no parent (top-level)
* Epics

Child issues (for example, Stories, Tasks, and Sub-tasks) are not categorized directly by AI. Instead, they inherit their category from the nearest categorized parent, following the standard precedence\
and inheritance rules. If a child issue matches a category rule or is manually categorized, that takes precedence over inheritance.

To use AI categorization, you'll need to add descriptions to your investment categories. The more detailed and clear your descriptions, the better the results. [See our writing guide.](#writing-good-category-descriptions)

<figure><img src="/files/qk4eoNdXCn16wTuBDAgz" alt=""><figcaption></figcaption></figure>

Once enabled, you can review how issues have been categorized in the categorization view to ensure they've been assigned correctly. You'll see an icon (✨) next to the category to indicate it has been categorized by AI, and you can hover to review the reasoning.

### How to get started

You can find the toggle to enable automatic categorization for an investment balance breakdown in the breakdown settings, between your defined categories and the **Everything else** category.

<figure><img src="/files/0Hz0CnxQHtPcZ5dlu7ML" alt=""><figcaption></figcaption></figure>

### Writing good category descriptions

Descriptions matter for the accuracy of the automatic categorization, so it's beneficial to spend some time thinking about good descriptions.

#### Why descriptions matter

Category descriptions serve two audiences. The first sentence should be written for people reading your categories. The remaining content serves as a prompt for the AI categorization system to determine where work items belong.

Previously, category descriptions were written for internal team members who already understood your context. For AI categorization, you need to be more explicit about your company and development work.

Think of it like onboarding a new employee: provide enough context so they can make quick, accurate decisions. This approach improves both AI accuracy and internal clarity.

#### Writing effective descriptions

Start by observing how your team writes issues. Pay attention to naming conventions and what information is typically included. Use these patterns when writing your category descriptions.

For the AI portion, include decision-making guidance such as:

* Positive and negative examples
* Relevant keywords
* Specific instructions on edge cases

This additional context helps the AI understand not just what the category is, but how to identify work that belongs in it.




---

[Next Page](/llms-full.txt/1)