Allocation Guide: Refining Your Workstreams

Last updated: October 27, 2026

Refining maps Span's AI workstreams to your own project list, one refinement period at a time. This guide walks through periods, cohorts, projects, mappings, and coverage.

Why it matters

Workstreams show where effort went in Span's words. Refining translates that into the projects your leadership and finance team already plan with.

  • For engineering leaders: report effort per roadmap project, per team, quarter over quarter.

  • For finance: mapped projects can drive cost capitalization when you classify work by refined workstreams, and they're required if managers approve effort each cycle.

How it works

Refining uses four building blocks:

  • Refinement period: a dated window, up to 100 days, such as one quarter. Periods follow each other with no gaps or overlaps.

  • Cohorts: groups of people you map separately, built from managers, teams, or individual people. Each person belongs to one cohort per period.

  • Projects: your roadmap items. Projects can have sub-projects. Span also includes an Other project for work that fits nowhere else.

  • Mappings: links from a workstream to a project, for one cohort. A mapping can cover the whole workstream or only specific issues and pull requests.

A period is In Progress while you work on it, Completed once you finalize it, or Discarded if you abandon it. Completed periods are locked: cohorts, projects, and mappings can no longer be edited.

Setup

You need the Manage Investment permission. It applies to the whole organization and can't be limited to certain cohorts.

Step 1: Create a refinement period

  1. Open Insights → Allocation → Workstreams and click Refine.

  2. On Refinement Periods, start a new period and pick its dates.

  3. The start date must be in the past, the end date must be after the start, and the period can't be longer than 100 days.

  4. If you've had a period before, the new one must start right where the last one ended. Only one period can be in progress at a time.

Step 2: Set up cohorts

  1. Open Cohorts setup in the period.

  2. Add a cohort, name it, and pick members by Managers (their reports), Teams, or People.

  3. Or use Set all Cohorts and choose By Manager or By Team to create them in one step, then adjust.

  4. Check Unassigned people. Anyone listed there is outside every cohort, so their work isn't mapped to any project. Add them to a cohort or leave them out on purpose.

Step 3: Define projects

  1. Click Add project and enter a name and optional description. Add sub-projects under a parent.

  2. To load many at once, choose Upload from CSV. Click Download sample CSV for the format: projects need name and description columns, and can have children. Get current projects downloads your existing list so you can edit and re-upload it.

Step 4: Map workstreams to projects

  1. Open Map Projects and pick a cohort. You map each cohort on its own.

  2. Select one or more workstreams and click Associate to project to map the whole workstream (a general mapping).

  3. To send only certain work to a project, add a rule-targeted mapping with specific issues or pull requests. The rest of the workstream ("All remaining work in the workstream") follows its general mapping.

  4. Save. The coverage numbers update.

Step 5: Complete the period

Save or discard any unsaved mapping changes, then complete the period. After that, nothing in it can be edited. Start the next period from the date this one ended.

Things to know

  • Only leaf projects take mappings. A project with sub-projects can't have workstreams mapped to it directly.

  • A project's parent can't change. To move a project, create a new one under the right parent, remap, then remove the old one.

  • Projects with mappings can't be removed. Clear or reassign the mapped workstreams first.

  • One cohort per person. Saving fails if the same person is a member of two cohorts. Cohort names must be unique and not blank.

  • Sub-workstreams inherit. A sub-workstream with no mapping of its own follows its parent's mapping.

  • Mapping status. Each workstream shows Mapped, Partially mapped, or Not mapped, so you can filter to what's left.

  • Rename workstreams outside refinement. Edit a workstream's name on the Workstreams page; the new name shows in later periods.

  • Restructures mid-period. Cohorts are a snapshot. For a small change, keep going and reflect the new structure next period. For a big one, discard the period and start again with new cohorts.

Worked example: coverage

The Platform cohort has 120 FTE-days in the period. You map workstreams holding 90 of them to projects, including the Other project. FTE Coverage is 90 / 120 = 75%. The remaining 30 FTE-days sit in workstreams that are still Not mapped. Map the largest of those first to raise coverage fastest.

Error messages you may see

  • "The new refinement period overlaps with the last refinement period" or "has to start exactly after the previous one ends": set the start date to the previous period's end.

  • "Member person IDs ... are duplicated": remove the person from all but one cohort.

  • "... cannot be moved to a different parent": create a new project under the right parent instead.

  • "Cannot remove ... because it has workstream mappings": clear or reassign those mappings first.

Related articles

Workstreams: AI-Powered Allocation

Understanding FTE Days in the Workstreams Report

Introduction to Cost Capitalization

Need help?

Contact your Span account team or reach out to support@span.app.