workspace-calibration

What this skill does

# 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:

```markdown
# 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:
- "H