workspace-calibration

Workspace Calibration Skill

Analyze Linear workspace health and usage patterns before jumping into backlog work. Like a pre-flight check for a new PM joining a team or organization.

Relationship to /linear-calibrate Command

For reliable, structured analysis: Direct users to run /linear-calibrate

This skill provides conversational context about Linear workspaces. For formal health checks with explicit thresholds and guaranteed output format, the /linear-calibrate command is more reliable.

When this skill triggers: Provide helpful context, then suggest:

"For a formal health check with explicit pass/fail thresholds, run /linear-calibrate"

When to Invoke

Auto-invoke this skill when:

• User is new to a Linear workspace and needs to understand how it's organized
• User asks about workspace health, structure, or organization
• User wants to understand how this org uses Linear
• User mentions too many teams, confusing structure, or workspace chaos
• User asks "where do I start?" with a large existing backlog
• Before running backlog commands like /lno-prioritize on an unfamiliar workspace

Trigger phrases (must mention Linear explicitly):

• "Help me understand this Linear workspace"
• "How is this org using Linear?"
• "Run a Linear workspace health check"
• "Analyze our Linear workspace"
• "Calibrate this Linear workspace"
• "Is our Linear workspace healthy?"
• "There are so many teams in Linear, where do I start?"

Note: Generic phrases like "workspace health check" may be interpreted as project/codebase checks. Always include "Linear" in the request.

What This Skill Does

CRITICAL: API Limits

When calling Linear MCP tools, ALWAYS specify limit: 250 to avoid default truncation:

• list_teams defaults to 50 - use limit: 250
• list_projects defaults to 50 - use limit: 250
• list_issues defaults to 50 - use limit: 250
• list_issue_labels defaults to 50 - use limit: 250

If any result count equals 250, note there may be more items.

1. Workspace Discovery

Gather data about the workspace structure using Linear MCP tools:

• List all teams, their members, and activity
• Sample issues to understand quality patterns
• Analyze projects, cycles, labels
• Identify conventions and patterns

2. Health Assessment

Compare reality to Linear's methodology (see references/linear-methodology.md):

• Are teams structured as durable groups or labels-as-teams?
• Is issue quality good (clear titles, no user story format)?
• Are backlogs manageable or overwhelming?
• Are projects well-scoped with owners and dates?
• Is triage being used effectively?

3. Calibration Report

Produce actionable output:

• Health indicators (green/yellow/red) for each dimension
• Conventions guide ("Here's how this org uses Linear")
• Red flags requiring attention
• Recommendations for cleanup or improvement
• Context for future backlog work

---

Calibration Process

Step 1: Announce Intent

I'll analyze this Linear workspace to help you understand:
- How it's structured (teams, projects, workflows)
- What's healthy vs concerning
- How this org uses Linear compared to best practices
- Where to focus your attention

This takes a few minutes. I'll pull data across teams and issues.

Step 2: Gather Data

Use Linear MCP tools to collect:

1. Teams
   - list_teams with limit: 250 (max)
   - If count = 250, flag as SEVERE: "Workspace may have 250+ teams - extreme proliferation"
   - For each active team: get_team for details
   - Note: member count, activity, naming patterns

2. Issues (sample)
   - list_issues with various filters:
     - Recent issues (last 30 days)
     - Stale issues (no update in 90 days)
     - Sample from multiple teams
   - Analyze: titles, descriptions, age distribution

3. Projects
   - list_projects: Get all projects
   - Note: leads, dates, status, issue counts

4. Cycles (if used)
   - list_cycles for active teams
   - Note: completion rates, carryover

5. Labels
   - list_issue_labels: Get all labels
   - Note: count, naming consistency, usage

6. Statuses
   - list_issue_statuses for key teams
   - Note: complexity, customization

Step 3: Analyze Against Methodology

For each dimension, compare findings to Linear best practices:

Team Structure:

• Count teams, calculate members per team
• Identify teams with 0-3 members (potential labels-as-teams)
• Check for topic-named teams vs group/area-named teams
• Flag teams with no activity in 90 days

Issue Quality:

• Sample 50-100 issues across teams
• Check for user story format ("As a...")
• Analyze title quality (action-oriented vs vague)
• Note description patterns

Backlog Health:

• Calculate age distribution of open issues
• Identify staleness (% untouched in 60/90 days)
• Note backlog size per team

Project Health:

• Check for leads assigned
• Check for target dates
• Identify stale projects
• Note scope (issues per project)

Workflow Complexity:

• Count statuses per team
• Compare to Linear defaults
• Flag over-engineered workflows

Step 4: Produce Calibration Report

REQUIRED: Always output the full structured report below. Do not summarize conversationally - the user needs the health indicators table and red flags to know where to focus.

Output this exact format:

# Workspace Calibration Report

**Workspace:** [name]
**Date:** [date]
**Analyzed:** [X teams, Y issues sampled, Z projects]

---

## Executive Summary

[2-3 sentences: Overall health, key findings, top concerns]

---

## Health Indicators

| Dimension | Status | Finding |
|-----------|--------|---------|
| Team Structure | 🟢/🟡/🔴 | [summary] |
| Issue Quality | 🟢/🟡/🔴 | [summary] |
| Backlog Health | 🟢/🟡/🔴 | [summary] |
| Project Health | 🟢/🟡/🔴 | [summary] |
| Cycle Usage | 🟢/🟡/🔴 | [summary] |
| Workflow Complexity | 🟢/🟡/🔴 | [summary] |
| Triage Usage | 🟢/🟡/🔴 | [summary] |
| Label Hygiene | 🟢/🟡/🔴 | [summary] |

---

## How This Org Uses Linear

[Describe the patterns observed - team structure philosophy,
workflow conventions, project usage, cycle rhythm, etc.
This helps a new PM understand "how we do things here."]

### Teams
[List key teams with brief description of what they own]

### Conventions
- Issue titles: [pattern observed]
- Labels: [how they're used]
- Projects: [how they're scoped]
- Cycles: [if/how they're used]

---

## Red Flags

[List specific issues requiring attention]

1. **[Issue]**: [Details and why it matters]
2. **[Issue]**: [Details and why it matters]

---

## Recommendations

### Immediate (This Week)
1. [Specific action]
2. [Specific action]

### Near-Term (This Month)
1. [Specific action]
2. [Specific action]

### Consider (When Ready)
1. [Larger improvement]

---

## Gut-Check Questions

Before diving into backlog work, consider:

- [ ] Can you explain what each team owns in one sentence?
- [ ] Do you know where to file any given issue within 2 clicks?
- [ ] Are there teams that should be consolidated?
- [ ] Is there stale work that should be archived?

---

*Calibration powered by PM Thought Partner*
*Methodology: Linear Method (linear.app/method)*

Step 5: Offer Next Steps

Your workspace is calibrated. Here's what I'd suggest:

1. [If red flags]: Address the [specific issue] first
2. [If healthy]: You're ready to run /lno-prioritize on [team]
3. [If context needed]: Want me to deep-dive on any dimension?

I now have context about how this org uses Linear. Future backlog
commands will account for your workspace patterns.

---

Key Principles

Compare to Methodology, Not Perfection

Linear's methodology is opinionated. Some orgs intentionally deviate. The goal is:

• Surface where reality differs from best practice
• Help user understand if deviations are intentional or drift
• Don't prescribe - inform and let user decide

New PM Orientation

This skill is especially valuable for PMs joining an existing org:

• "Here's how this workspace is structured"
• "Here's what's healthy vs concerning"
• "Here's where to focus first"

Set Up Future Work

Calibration provides context for subsequent commands:

• /lno-prioritize works better when you understand team structure
• /four-risks makes more sense when you know project conventions
• Backlog cleanup is informed by health assessment

---

Integration with Other Skills

After calibration:

• pm-frameworks skill: Apply prioritization frameworks with workspace context
• backlog-analysis skill (future): Deep-dive on specific team/project backlogs
• Commands like /lno-prioritize, /now-next-later: Run with understanding of conventions

---

Edge Cases

No Linear MCP

If Linear MCP isn't configured:

I'd like to analyze your Linear workspace, but I don't have access.

To enable workspace calibration:
1. Get a Linear API key (Settings > Account > Security & Access)
2. Ask Claude "Set up the Linear MCP server"

Alternatively, you can describe your workspace structure and I'll
help you think through it manually.

Very Large Workspace

For workspaces with 50+ teams or 10K+ issues:

This is a large workspace. I'll sample strategically rather than
analyzing everything:
- All teams (for structure analysis)
- 100-200 issues across key teams (for quality patterns)
- Active projects only (for project health)

This gives representative data without overwhelming the analysis.

Recently Created Workspace

For new workspaces with minimal data:

This workspace is relatively new with limited history.

Instead of a full health check, I'll help you:
- Set up team structure following Linear best practices
- Establish conventions before patterns emerge
- Avoid common pitfalls (labels-as-teams, user story format, etc.)

---

Reference Documents

• references/linear-methodology.md - Linear's recommended practices
• references/health-indicators.md - Detailed health dimensions and thresholds