Allocation Guide: Refining Your Workstreams

Span's Allocation feature helps you answer critical questions about your engineering organization:

• 💰 Where is our engineering capacity actually going?

• 📊 How much effort is each strategic initiative receiving?

• 🎯 Are we investing in alignment with our roadmap?

• 📈 How has our allocation changed over time?

The allocation system connects AI-detected engineering work (workstreams) to your business initiatives (projects), giving you visibility into resource distribution and enabling data-driven planning.

What You'll Achieve

By the end of this guide, you'll be able to:

• ✅ Create allocation tracking periods

• ✅ Organize your team into meaningful cohorts

• ✅ Define your project portfolio

• ✅ Map engineering work to business initiatives

• ✅ Track allocation coverage and trends

• ✅ Generate allocation reports for leadership

Key Concepts

🗓 Refinement Periods

Time-bounded windows for allocation planning and analysis. Think of them as "snapshots" that capture how your team's effort was allocated during a specific timeframe.

Example: "Q1 2024 Allocation" (Jan 1 - Mar 31, 2024)

👥 Cohorts

Team groupings that you define for allocation tracking. Cohorts let you slice allocation by manager, team, or custom groupings.

Examples:

• By manager: "Backend Team (John Smith)", "Frontend Team (Jane Doe)"

• By team: "Platform Team", "Product Team", "Infrastructure Team"

• By specialty: "Mobile Engineers", "Data Engineers"

🎯 Projects (Roadmap Items)

Strategic initiatives or features that represent your business priorities. These are what you want to understand allocation across.

Examples:

• "New User Authentication System"

• "Mobile App Redesign"

• "Performance Optimization Initiative"

• "Technical Debt Reduction"

🔗 Mappings

Connections between workstreams and projects that show where engineering effort is being spent.

Example: The "API Development" workstream maps to the "New User Authentication System" project.

Getting Started Workflow

Here's the complete journey from start to finish:

1. Create Refinement Period → 2. Setup Cohorts → 3. Define Projects → 4. Map Workstreams → 5. Analyze & Report

Estimated Time: 1-2 hours for your first allocation setup

Refinement Periods

What They Are

Refinement periods are the foundation of allocation tracking. Each period represents a specific timeframe during which you'll capture how your engineering capacity was distributed across projects.

Creating Your First Refinement Period

Step-by-Step:

1. Navigate to Investment → Allocation → Refinement

2. Click "Start New Refinement Period"

3. Select Date Range:

   • Start Date: Must be in the past (not future)

   • End Date: Must be after start date

   • Maximum Duration: 100 days

   • ⚠ Important: Each period must start exactly where the previous period ended (no gaps allowed)

4. Click "Create"

💡 Recommended Timeframes:

• Quarterly: 90 days aligned with business quarters (recommended)

• Monthly: 30 days for more frequent tracking

• Sprint-based: 2-4 weeks aligned with agile sprints

• Custom: Any duration up to 100 days

Understanding Period Status

Managing Periods

To Discard a Period (if you need to start over):

1. Open the period

2. Click Actions → "Discard Period"

3. Confirm

4. Create a new period

⚠ Important Rules:

• Cannot overlap periods

• Cannot have gaps between periods

• Cannot edit completed periods

• First period can start at any past date

• Subsequent periods must be contiguous

Setting Up Cohorts

What Cohorts Do

Cohorts let you track allocation by team segment. They answer questions like:

• "How is Jane's team allocating their time?"

• "What is the Platform team working on?"

• "Where is our backend engineering capacity going?"

Cohort Configuration Options

You have three ways to define cohort membership:

Option 1: By Managers 👔

Best for: Manager-based allocation visibility

• Select one or more engineering managers

• Automatically includes all their direct reports

• Updates dynamically as reporting structure changes

Example: "Backend Team" cohort includes all direct reports of John Smith

Option 2: By Teams/Groups 🏢

Best for: Organizational structure alignment

• Select one or more teams from your org chart

• Includes all members of those teams

• Aligns with existing team boundaries

Example: "Platform" cohort includes everyone on the Platform Engineering team

Option 3: By People 👤

Best for: Custom groupings

• Manually select specific individuals

• Full control over membership

• Useful for cross-functional squads or special projects

Example: "Mobile Squad" cohort with iOS and Android engineers from different teams

Creating Cohorts

Method A: Manual Setup (Full Control)

1. Start with your refinement period created

2. Navigate to the Setup tab

3. Click "Add Cohort"

4. Configure:

   • Cohort Name: Give it a descriptive name (must be unique)

   • Selection Type: Choose Managers, Groups, or People

   • Select Members: Pick the relevant managers/groups/people

   • Optional Supervisors: Add supervisors for this cohort (optional)

5. Click "Save"

6. Repeat for each cohort you need

Method B: Quick Setup (Automated)

1. Click "Set all Cohorts" dropdown

2. Choose one:

   • "By Manager": Automatically creates one cohort per engineering manager

   • "By Team": Automatically creates one cohort per organizational team

3. Review the generated cohorts

4. Adjust names or membership as needed

5. Click "Save"

💡 Tip: Quick setup is great for your first time. You can always refine later!

Cohort Rules & Constraints

✅ Allowed:

• Multiple cohorts per refinement period

• Same person as supervisor in multiple cohorts

• Empty supervisors (not required)

❌ Not Allowed:

• Same person as member in multiple cohorts (each person can only be in ONE cohort)

• Duplicate cohort names within a period

• Blank cohort names

Validation: Unassigned People

After creating cohorts, check the "Unassigned People" section at the bottom of the Setup tab.

• 🟢 Empty list: Perfect! Everyone is assigned to a cohort.

• 🟡 Names appear: These people aren't in any cohort. Either:

  • Add them to an appropriate cohort, OR

  • Intentionally exclude them (e.g., contractors, recent hires without work history)

⚠ Important: Work by unassigned people won't appear in allocation reports!

Example Cohort Structures

Scenario 1: Manager-Based Allocation

✓ Backend Team (Manager: John Smith)
✓ Frontend Team (Manager: Jane Doe)
✓ Mobile Team (Manager: Alex Johnson)
✓ DevOps Team (Manager: Sam Lee)

Scenario 2: Team-Based Allocation

✓ Platform Engineering
✓ Product Engineering
✓ Infrastructure
✓ Data Engineering

Scenario 3: Hybrid Approach

✓ iOS Squad (Custom: 5 specific iOS engineers)
✓ Android Squad (Custom: 4 specific Android engineers)
✓ Backend Teams (All backend managers combined)
✓ Platform Teams (Platform team + DevOps team)

Defining Projects

What Projects Represent

Projects are your strategic initiatives—the features, systems, and work products that your business cares about. They answer the question: "What are we building and why?"

Project Hierarchy

Projects support multi-level hierarchies for organization:

📁 Authentication Redesign (Parent)
  ├─ 📄 Frontend Components (Child - Mappable)
  ├─ 📄 Backend Services (Child - Mappable)
  └─ 📄 Mobile Integration (Child - Mappable)

Key Rule: Only leaf projects (those without children) can have workstreams mapped to them.

Creating Projects

Method A: Manual Creation

1. Navigate to the Projects tab in your refinement period

2. Click "Add project"

3. Enter project details:

   • Name (required): Clear, descriptive name

   • Description (optional): Context for stakeholders

4. To add sub-projects:

   • Click the "+" button next to a parent project

   • Enter sub-project details

   • Repeat for multiple children

5. Click "Save Projects"

Example:

Name: "User Authentication Redesign"
Description: "Complete overhaul of authentication system with OAuth2, SSO, and MFA support. Target: Q1 2024 launch."

Method B: Bulk Import (CSV)

Best for: Large project portfolios or existing roadmap data

1. Click "Load from CSV"

2. Prepare CSV with these columns:

   • name: Project name (required)

   • description: Project description (optional)

   • parent_name: Parent project name for hierarchies (optional)

   • order: Display order number (optional)

Example CSV:

name,description,parent_name,order
Authentication Redesign,Complete auth system overhaul,,1
Frontend Components,React login/signup flows,Authentication Redesign,1
Backend Services,OAuth2 and SSO implementation,Authentication Redesign,2
Mobile Integration,iOS and Android auth flows,Authentication Redesign,3
Performance Optimization,Site speed improvements,,2

3. Upload the CSV file

4. Review imported projects

5. Click "Save"

Special Project: "Other"

The system automatically includes an "Other" project as a catch-all for:

• Ad-hoc work

• Maintenance tasks

• Exploratory work

• Unplanned initiatives

💡 Tip: It's okay to have work in "Other"—typically 10-20% of engineering effort is miscellaneous!

Project Management

Editing Projects:

• Can change name and description anytime

• Can add or remove children

• Cannot change parent after creation (parent relationship is immutable)

Deleting Projects:

• Can delete projects that have no workstream mappings

• Must unmap workstreams first before deleting

Organizing Projects:

• Use order field to control display sequence

• Group related projects together with parent-child relationships

• Keep hierarchy depth reasonable (2-3 levels max recommended)

Project Naming Best Practices

✅ Good Project Names:

• "Mobile App Redesign - iOS"

• "Customer Dashboard v2.0"

• "Payment Gateway Integration"

• "Technical Debt: Database Performance"

❌ Avoid:

• "Work" (too generic)

• "Stuff" (not descriptive)

• "John's Project" (not sustainable)

• "TBD" (define before mapping)

Example Project Structures

Product-Focused Portfolio:

✓ New User Dashboard
✓ Advanced Reporting Features
✓ Mobile App Enhancements
  ├─ Push Notifications
  ├─ Offline Mode
  └─ UI Refresh
✓ API v2.0 Migration
✓ Other

Platform-Focused Portfolio:

✓ Infrastructure Modernization
  ├─ Kubernetes Migration
  ├─ CI/CD Pipeline Improvements
  └─ Monitoring & Alerting
✓ Developer Experience
  ├─ Internal Tooling
  └─ Documentation
✓ Security & Compliance
✓ Performance Optimization
✓ Other

Mapping Workstreams to Projects

What Mapping Does

Mapping connects actual engineering work (workstreams detected by AI) to business initiatives (your defined projects). This is where allocation becomes visible.

Before Mapping: You see workstreams like "Backend API Work" with 45 FTE days
After Mapping: You see "Backend API Work → User Authentication Project" = 45 FTE days allocated

The Mapping Interface

The mapping UI has three key panels:

┌─────────────────────────────────────────────────┐
│  Cohort: Platform Team          Coverage: 67%   │
├──────────────┬──────────────────┬───────────────┤
│  Projects    │  Workstreams     │  Detail View  │
│  (Left)      │  (Center)        │  (Right)      │
│              │                  │               │
│ □ Auth       │ ☑ Backend API    │ Backend API   │
│ □ Mobile     │ □ Frontend UI    │ 45 FTE Days   │
│ □ Perf Opt   │ □ Mobile Dev     │               │
│              │                  │ Map to:       │
│              │                  │ • Auth ←      │
│              │                  │ • Mobile      │
└──────────────┴──────────────────┴───────────────┘

Step-by-Step Mapping Workflow

1. Select Cohort

   • Use dropdown at top to choose which cohort to map

   • You'll map each cohort independently

2. Browse Workstreams (Center Panel)

   • See all workstreams for selected cohort

   • Expand to view sub-workstreams

   • Status indicators show mapping state:

     • 🟢 Complete: Fully mapped

     • 🟡 Partial: Some work mapped, some unmapped

     • 🟣 Indirect: Mapped through children

     • ⚪ Not Mapped: No allocation

3. Click a Workstream

   • Detail panel opens on right

   • Shows:

     • Total FTE days

     • Current mappings (if any)

     • Available projects to map to

     • Option to add mapping rules

4. Map to a Project

   • Option A: Click a project name to map entire workstream

   • Option B: Add rules (see below) for partial mapping

5. Save Mappings

   • Click "Save" button to persist changes

   • Coverage percentage updates automatically

6. Repeat for all workstreams and cohorts

Mapping Types

Type 1: General Mappings (Complete)

What: Map an entire workstream to a single project
When: The workstream clearly belongs to one initiative
How: Simply click the project name

Example:

Workstream: "OAuth Implementation"
Project: "Authentication Redesign"
Mapping: 100% of workstream → Project

Type 2: Split Mappings (Partial)

What: Map a workstream to multiple projects
When: Work spans multiple initiatives
How: Click multiple project names

Example:

Workstream: "API Development"
Mappings:
  • 60% → "Authentication Redesign"
  • 40% → "Mobile App Integration"

Type 3: Rule-Based Mappings (Precise)

What: Map specific issues or PRs to projects
When: Need fine-grained control
How: Add mapping rules with specific work item IDs

Example:

Workstream: "Frontend Development"
Rules:
  • Issues #123, #124, #125 → "User Dashboard"
  • PR #456, #457 → "Reporting Features"
  • (Remaining work) → "Other"

Adding Mapping Rules

Rules let you precisely control which work items count toward which projects.

Steps to Add Rules:

1. Click workstream in center panel

2. Click "Add Rules" in detail panel

3. Choose rule type:

   • Issue Asset IDs: Map specific issues

   • Pull Request Asset IDs: Map specific PRs

4. Select work items:

   • Browse or search issues/PRs

   • Select checkboxes for items to include

   • Click "Add to Rule"

5. Assign to Project:

   • Click project name

   • Rule is created

6. Repeat for additional rules

7. Click "Save"

Rule Types:

Conflict Resolution

Scenario: You try to add a general mapping, but rules already exist

System Response:

• ⚠ "This workstream already has rule-based mappings. Adding a general mapping will replace them."

Your Options:

1. Cancel: Keep existing rules

2. Confirm: Replace rules with general mapping

Rule: You cannot have both general mappings AND rules on the same workstream. Choose one approach.

Understanding Mapping Status

Workstreams show visual indicators of mapping state:

💡 Goal: Aim for as many green indicators as possible (high coverage).

Mapping Validation

The system prevents invalid mappings:

❌ Cannot Map:

• Non-leaf projects (only leaf projects can have mappings)

• Same workstream to same project twice (duplicates)

• Rules when general mapping exists (conflict)

• General mapping when rules exist (conflict)

✅ Can Map:

• Multiple projects to same workstream (split allocation)

• Same project to multiple workstreams (consolidation)

• Mix of general and rule-based across different workstreams

• Update/change mappings anytime during "In Progress" periods

Understanding Coverage

What Coverage Measures

Allocation Coverage = Percentage of engineering effort that has been mapped to known projects.

Formula:

Coverage % = (Mapped FTE Days / Total FTE Days) × 100

Example:

Total Effort: 100 FTE days
Mapped: 85 FTE days
Coverage: 85%

Coverage Levels

Coverage Metrics

The system tracks coverage at multiple levels:

Cohort-Level Metrics

Shown in the mapping interface header:

Platform Team
├─ Total FTE Days: 120
├─ Mapped FTE Days: 90
├─ Coverage: 75%
├─ Total Workstreams: 15
└─ Mapped Workstreams: 12 (80%)

Project-Level Metrics

Shown in project details:

Authentication Redesign
├─ Mapped FTE Days: 45
├─ Mapped Workstreams: 5
└─ Contributing Cohorts: 3

Organization-Level Metrics

Aggregate view across all cohorts:

Q1 2024 Allocation
├─ Total Organizational Effort: 500 FTE days
├─ Mapped: 425 FTE days (85%)
├─ By Project:
│   ├─ Auth Redesign: 120 FTE days (24%)
│   ├─ Mobile App: 95 FTE days (19%)
│   ├─ Performance: 80 FTE days (16%)
│   └─ Other: 130 FTE days (26%)
└─ Unmapped: 75 FTE days (15%)

Improving Coverage

Strategy 1: Define Missing Projects

If you see significant unmapped work:

1. Review unmapped workstreams

2. Identify common themes

3. Create projects for major initiatives

4. Map workstreams to new projects

Strategy 2: Use "Other" Project

For miscellaneous work that doesn't fit existing projects:

1. Map to the "Other" project

2. Acceptable for 10-20% of effort

3. Review "Other" periodically for patterns

Strategy 3: Refine Workstream Mappings

Some workstreams might actually belong to existing projects:

1. Review workstream details

2. Check recent issues and PRs

3. Determine correct project

4. Create mapping

Strategy 4: Accept Some Unallocated Work

Not all work needs to be allocated:

• Exploratory work

• Learning and development

• Very minor tasks

• Typically <10% is acceptable

Coverage Reports

Access detailed coverage data via:

In-App Reports:

• Cohort summary view

• Project detail pages

• Allocation trends over time

• Exportable CSV reports

API Access:

GET /api/v1/investment/ai-workstreams/refinement/{periodId}/coverage

Best Practices

Planning Phase

1. Align With Business Planning

• Time refinement periods with strategic planning cycles (quarters, releases)

• Involve product/engineering leadership in project definition

• Ensure projects match roadmap priorities

2. Define Cohorts Thoughtfully

• Choose cohort structure that matches how you make decisions

• Manager-based: Good for people management

• Team-based: Good for organizational visibility

• Consider creating 5-10 cohorts (not too few, not too many)

3. Start Simple

• First time? Use quick setup ("Set all Cohorts by Manager")

• Define 10-15 core projects initially

• Expand sophistication over time

4. Communicate

• Inform teams about allocation tracking

• Explain why it matters

• Set expectations for coverage goals

Execution Phase

5. Be Comprehensive

• Aim for 70-80%+ coverage

• Define projects for all major initiatives

• Use "Other" for miscellaneous work (<20%)

6. Map Iteratively

• Start with largest workstreams (most FTE days)

• Map obvious connections first

• Refine details later

7. Use Rules Judiciously

• General mappings work for most cases

• Use rules only when precision is critical

• Rules add maintenance overhead

8. Regular Updates

• Update mappings as priorities shift

• Review coverage weekly during refinement period

• Adjust cohorts if team structure changes

Analysis Phase

9. Track Coverage Trends

• Monitor coverage % over time

• Investigate significant drops

• Celebrate improvements

10. Compare Periods

• How did allocation shift quarter over quarter?

• Which projects grew/shrank?

• Are investments aligned with strategy?

11. Validate Data

• Spot-check mappings against actual work

• Ask teams if allocation matches their perception

• Refine definitions based on feedback

12. Share Insights

• Create executive summaries

• Highlight key findings

• Use data to drive conversations

Maintenance Phase

13. Complete Periods Promptly

• Mark periods as complete when finalized

• Locks data for historical accuracy

• Enables period-over-period comparisons

14. Learn and Iterate

• What worked well? What didn't?

• How can next period be better?

• Document lessons learned

15. Automate Where Possible

• Use quick setup for cohorts

• Bulk import projects from roadmap tools

• Export reports for distribution

Common Scenarios

Scenario 1: First-Time Setup

Goal: Get allocation tracking running for the first time

Steps:

1. ✅ Create Q1 refinement period (3 months)

2. ✅ Use "Set all Cohorts by Manager" quick setup

3. ✅ Define 10-12 core projects based on current roadmap

4. ✅ Map top 5 workstreams (by FTE days) to projects

5. ✅ Aim for 60-70% coverage initially

6. ✅ Review with leadership

7. ✅ Refine based on feedback

Time Investment: 2-3 hours

Scenario 2: Quarterly Allocation

Goal: Track allocation every quarter

Steps:

1. ✅ Complete previous quarter's refinement period

2. ✅ Create new refinement period (start = previous end date)

3. ✅ Copy cohorts from previous quarter (or adjust for team changes)

4. ✅ Update projects (add new initiatives, remove completed ones)

5. ✅ Map workstreams to current projects

6. ✅ Aim for 75-85% coverage

7. ✅ Generate quarter-over-quarter comparison report

8. ✅ Share with stakeholders

Time Investment: 1-2 hours

Scenario 3: Mid-Quarter Reallocation

Goal: Team priorities shifted, need to remap

Steps:

1. ✅ Open current refinement period (must be "In Progress")

2. ✅ Add new projects for changed priorities

3. ✅ Update workstream mappings

4. ✅ Review coverage (ensure still high)

5. ✅ Save changes

6. ✅ Document reason for changes

Time Investment: 30-60 minutes

Scenario 4: Cross-Functional Projects

Goal: Map work from multiple cohorts to a shared project

Steps:

1. ✅ Define project once in refinement period

2. ✅ For each cohort:

   • Select cohort

   • Find relevant workstreams

   • Map to shared project

3. ✅ System automatically aggregates across cohorts

4. ✅ View project detail to see total effort from all cohorts

Result: Project shows combined FTE days from all contributing cohorts

Scenario 5: Detailed Financial Tracking

Goal: Understand cost of each initiative for financial reporting

Steps:

1. ✅ Ensure cost estimates enabled in organization settings

2. ✅ Create refinement period with financial focus

3. ✅ Define projects matching budget line items

4. ✅ Map workstreams with high precision (use rules if needed)

5. ✅ Aim for 90%+ coverage (financial accuracy matters)

6. ✅ Export allocation report with FTE Days Cost

7. ✅ Share with finance team

Output: Cost allocation by project for capitalization or budget tracking

Scenario 6: Team Restructure

Goal: Org chart changed mid-quarter, need to adjust

Options:

Option A - Continue Current Period:

• Keep cohorts as-is (snapshot in time)

• Accept that period reflects old structure

• New structure will appear in next period

Option B - Restart Period:

• Discard current period

• Create new period with new cohorts

• Remap from scratch

• Use if restructure is major

Recommendation: Usually Option A (less work, preserves history)

Troubleshooting

Error: "Refinement period overlaps with last refinement period"

Cause: New period's dates overlap or have gap with previous period

Solution:

1. Check previous period's end date

2. Ensure new period starts on next day after previous end

3. Example: Previous ends 2024-03-31 → New starts 2024-04-01

Prevention: System should auto-suggest correct start date

Error: "Member person IDs are duplicated across cohorts"

Cause: Same person assigned to multiple cohorts

Solution:

1. Review cohort configurations

2. Find person appearing in multiple cohorts

3. Decide which cohort they should belong to

4. Remove from all others

5. Save cohorts

Prevention: Use quick setup options which enforce non-overlapping membership

Error: "Have to include parent roadmap item in the request"

Cause: Trying to save child projects without including parent

Solution:

1. When defining projects with hierarchy, include parent in same save operation

2. If editing existing children, fetch and include parent in request

3. Use UI (which handles this automatically) rather than API

Prevention: Always work with complete project trees

Error: "Cannot be moved to a different parent"

Cause: Attempting to change a project's parent relationship

Solution:

1. Parent relationships are immutable

2. Create new project with correct parent

3. Map workstreams to new project

4. Delete old project (if no mappings remain)

Prevention: Plan project hierarchy carefully before creation

Issue: Coverage is Low (<50%)

Diagnostic Questions:

• Are all major projects defined?

• Are there workstreams you don't recognize?

• Is work happening outside defined projects?

Solutions:

1. Review Unmapped Workstreams: Sort by FTE days descending, examine top unmapped items

2. Define Missing Projects: Create projects for initiatives not yet captured

3. Map to "Other": For miscellaneous work, map to "Other" project

4. Check Cohort Membership: Ensure all active engineers are in cohorts

Acceptable Level: 70-85% coverage is realistic; 100% is usually unnecessary

Issue: Workstream Name is Confusing

Problem: AI-generated workstream names aren't intuitive

Solution:

1. Navigate to workstream detail page (not in refinement)

2. Edit workstream name and description

3. Save changes

4. Customized name appears in all future refinement periods

Note: This is separate from allocation—edit workstreams in main workstreams view

Issue: Project Should Be Split

Problem: Realized a project is too broad, should be multiple projects

Solution:

1. In current refinement period, create new sub-projects under the broad project

2. Or create peer projects if not hierarchical

3. Review workstream mappings

4. Remap workstreams to more specific projects

5. Save changes

Prevention: Start with more granular projects; easier to combine than split

Issue: Team Member Missing from Cohorts

Problem: Person's work not appearing in allocation

Check:

1. Go to refinement period → Setup tab

2. Scroll to "Unassigned People" section

3. Look for person's name

Solution:

1. Add person to appropriate cohort

2. Save cohort configuration

3. Refresh mapping view

4. Person's workstreams now appear

Prevention: Review "Unassigned People" before starting mappings

Issue: Want to Change Previous Period

Problem: Realized mistake in completed period

Reality: Completed periods are immutable (locked)

Options:

1. Accept: Historical data reflects state at that time

2. Document: Note the issue for future reference

3. Correct in Next Period: Apply learnings to next refinement period

Prevention: Thoroughly review before completing periods

Advanced Topics

Integration with External Tools

Jira/Linear Integration:

• Workstreams automatically link to tracked issues

• Use issue IDs in mapping rules

• Reflects actual work management structure

GitHub/GitLab Integration:

• Pull requests associated with workstreams

• Use PR IDs in mapping rules for code-level precision

Cost Management Systems:

• Export FTE Days Cost for capitalization

• Map to budget line items via project naming

API Usage

For programmatic access or custom reporting:

Base Endpoint:

/api/v1/investment/ai-workstreams/refinement

Common Operations:

# List all refinement periods
GET /api/v1/.../refinement/

# Get cohorts for period
GET /api/v1/.../refinement/{periodId}/cohorts

# Get mappings for cohort
GET /api/v1/.../refinement/{periodId}/cohorts/{cohortId}/mappings-data

# Update mappings
POST /api/v1/.../refinement/{periodId}/cohorts/{cohortId}/mappings-data

Authentication: Requires ManageInvestment permission

Documentation: See API reference in platform settings

Permissions & Access Control

Who Can Access Allocation Features:

• Organization administrators

• Users with ManageInvestment permission

Permission Scope:

• Global (all-or-nothing, cannot scope to specific cohorts)

• Includes: create periods, define cohorts, manage projects, update mappings

Audit Trail:

• All changes tracked with timestamps

• Creator information available

• Changes are transactional (atomic)

Quick Reference

Refinement Period Checklist

•  Create period with appropriate date range

•  Define cohorts (use quick setup if first time)

•  Verify no unassigned people

•  Define projects based on current roadmap

•  Map top workstreams first (by FTE days)

•  Aim for 70-85% coverage

•  Review with stakeholders

•  Make final adjustments

•  Complete period when finalized

•  Export report for distribution

Coverage Goals by Organization Size

Time Estimates

Common Mistakes to Avoid

❌ Creating future-dated refinement periods
❌ Overlapping people across cohorts
❌ Mapping to non-leaf projects
❌ Forgetting to save changes
❌ Completing periods prematurely
❌ Skipping "Unassigned People" review
❌ Defining too few projects (everything goes to "Other")
❌ Over-engineering with excessive rules

Getting Help

Support Resources

• In-App Help: Click "?" icon in any refinement screen

• Customer Success: Contact your dedicated CSM

• Email Support: support@span.app

Requesting Features

Have ideas for improving allocation tracking? We'd love to hear from you! Reach out to your Span rep.

Summary

Span's Allocation feature provides powerful visibility into engineering resource distribution. By following this guide, you'll be able to:

✅ Track where engineering capacity is going
✅ Align work with strategic priorities
✅ Measure investment across initiatives
✅ Report allocation to leadership
✅ Optimize resource planning over time

Next Steps:

1. Create your first refinement period

2. Set up cohorts using quick setup

3. Define your top 10 projects

4. Map your largest workstreams

5. Review coverage and refine

Remember: Start simple, iterate, and improve over time. Your first allocation won't be perfect—and that's okay!

Allocation Guide last updated: January 2026
Questions? Contact support@span.app