---
name: talentco-linear-update-planner
description: Correlates recent repo history (git, CHANGELOG, TalentCo-scoped code) with the TalentCo MVP Development board in Linear, drafts state/comment/retro issue plans, optional project-level update text for Linear’s Project update feed (or GraphQL), and uses Linear MCP read-only first; applies updates only after explicit go-ahead per linear-issues-talentco. Use when syncing the board with implementation, planning a Linear update pass, retro-capturing shipped work, or when the user asks to reconcile TalentCo MVP issues with the codebase.
---

# TalentCo Linear update planner

## When to use

- Prepare a **board update plan** (issue states, comment drafts, new retro issues) from codebase evidence.
- **Default pass is read-only:** do not create, edit, or comment in Linear until the user approves or explicitly asks to execute (then follow [linear-issues-talentco](../linear-issues-talentco/SKILL.md)).

## Linear MCP

1. **Before `call_mcp_tool`:** read the JSON schema under `mcps/<server>/tools/` for the tool you will call (e.g. `list_issues.json`, `get_issue.json`, `list_comments.json`).
2. **Workspace:** TalentCo MVP issues for this repo live in the **Earth Ventures** Linear workspace. Use the MCP server that backs that workspace (e.g. `user-linear_Earth_Ventures` when enabled). If the tool is missing, calls fail with auth errors, or the workspace is wrong, **stop** and ask the user to connect or fix Linear MCP in Cursor settings.
3. **Routing:** Default team **Earth Ventures**, default project **TalentCo MVP Development** — same table as [linear-issues-talentco](../linear-issues-talentco/SKILL.md). Use `list_projects` / `list_teams` if names drift.

**Read tools for planning:** `list_issues` (filter by `project`, `orderBy`, `updatedAt` / `createdAt` as needed), `get_issue`, `list_issue_statuses`, `list_comments`, optionally `get_team` / `get_project` for IDs.

**Write tools (only after go-ahead):** `save_issue`, `save_comment`, etc. — follow schemas and the other skill.

### Project update (dedicated dialog / feed — not project description)

Linear’s **Project** page has an **Updates** timeline fed by GraphQL **`projectUpdateCreate`** (`ProjectUpdateCreateInput`: `projectId`, `body` markdown, optional `health`: `onTrack` | `atRisk` | `offTrack`). That is **separate** from the project **Description** field (`save_project`).

- **Cursor Linear MCP:** `save_status_update` only supports **`type: initiative`** (with an **initiative**). It does **not** create **project** updates. Do not use `save_project` **description** as a substitute for a project update post unless the user explicitly wants the long-form description edited.
- **What to do:** After a board sync pass, **attempt** to add a project-level summary by either:
  1. **Giving the user paste-ready markdown** (and optional `health`) for **Project → New update** in the Linear UI, or
  2. If a **Linear Personal API key** is available in the environment, **`projectUpdateCreate`** via `curl` to `https://api.linear.app/graphql` with `Authorization: <key>` — do not print the key.

**Initiative + MCP (explored, not a full substitute for `projectUpdateCreate`):** The MCP can **`save_initiative`**, link the project with **`save_project`** + **`addInitiatives`**, and post **`save_status_update`** with **`type: initiative`** and **`initiative` required**. That creates **initiative** status updates (activity URLs point at the **initiative**, not a standalone project update). Passing **`project`** as well does not switch the post to a native **project** update — it is still `type: initiative`. **`get_status_updates`** filtered by **`project`** may still return these rows when the project is **linked** to the initiative, so the project page may surface the same content depending on Linear UI. For a real **Project → New update** entry, use the UI or **`projectUpdateCreate`**.

Keep project update text **TalentCo-scoped** like issues (same exclusions as below).

## Scoping: TalentCo only

- **Include** in the plan and in any **future** Linear text: work clearly tied to `CLIENT_CONFIG` / `VITE_CLIENT_CONFIG` **`talentco`**, TalentCo routes copy, `labs/client-config.json` → `talentco`, `api/client-config.json` → `talentco`, and docs that are TalentCo product notes (e.g. `docs/TALENTCO_UI_PATTERNS.md`).
- **Exclude** from TalentCo issues: other tenants (e.g. `bookedai`, `lumie`, `eyefi`, `lortsmith`, `recruitrtech`, `yeshuman` branding), generic platform changes **unless** the changelog or commit message ties them to a TalentCo issue or user confirms TalentCo is the customer for that slice.
- When a change touches **shared** code, describe it in Linear **only** in terms of the TalentCo-facing outcome (Labs UX for TalentCo, API behavior when `talentco` is selected, etc.).

## How far back to analyze

1. **Start with** [CHANGELOG.md](../../../CHANGELOG.md): note `[Unreleased]` and recent version sections; look for `TalentCo`, `EV-` issue keys, and Labs/API bullets that map to MVP themes.
2. **Align git range** to that narrative, e.g. `git log` from the date of the last tagged release in CHANGELOG, or from the start of `[Unreleased]` accumulation. Use `git log --oneline -n`, `git log --since=…`, and optional `git log --grep=EV-`.
3. **If the window is unclear** (no board sync date, messy history, or unclear tenant ownership), **ask the user** how far back to go or which Linear cycle/release to match.

## Workflow

### Phase 1 — Plan only (default)

1. Confirm Linear MCP works (or ask user to auth/connect).
2. Load board context: `list_issues` for **TalentCo MVP Development**; optionally restrict by `updatedAt` to match the git window.
3. Scan repo: CHANGELOG + targeted `git log` / diffs; search code for `talentco`, `EV-`, and files under TalentCo-relevant areas (see [AGENTS.md](../../../AGENTS.md) client list).
4. **Correlate:** for each in-scope change, link to an existing issue (e.g. `EV-85`) or flag **gap** (shipped work with no issue).
5. **Produce a structured plan** (use template below). Include:
   - Proposed **state** changes (with rationale from code/changelog).
   - **Comment** drafts (implementation notes, PR/commit refs — tenant-safe wording).
   - **Retro** issue candidates: title, one-paragraph description, acceptance criteria, link to commits/paths; **no** other clients named.
   - **Project update (optional):** short markdown for the project **Updates** feed (Done / In progress / Backlog, links to `EV-…`); note if the user should paste manually vs API.
6. **Discuss** with the user; ask clarifying questions (tenant scope, done vs in progress, whether to split issues).
7. **Do not** mutate Linear in this phase.

### Phase 2 — Execute (explicit go-ahead or Plan mode)

- After the user approves, apply updates per [linear-issues-talentco](../linear-issues-talentco/SKILL.md): dedupe, `save_issue` / `save_comment`, correct team/project, literal newlines in markdown.
- **Project update:** provide paste-ready **Updates** text (or run **`projectUpdateCreate`** if a Personal API key is available). If the user prefers to post themselves, hand off the markdown only. **Do not** append sync narratives to **`save_project` description** unless the user asked to change the description.

## Plan output template (agent reply)

```markdown
## Window
- Changelog / git range: …
- Linear filter (if any): …

## Issue updates
| ID | Current state | Proposed state | Evidence (TalentCo-scoped) |
|----|---------------|----------------|----------------------------|
| EV-… | … | … | … |

## Comment drafts
- **EV-…:** …

## Retro / capture candidates (no pre-existing issue)
- **Title:** …
  - **Summary:** …
  - **Where in repo:** …

## Excluded (non–TalentCo or needs confirmation)
- …

## Project update (paste into Linear **Project → New update**, or `projectUpdateCreate`)
- **Health:** onTrack | atRisk | offTrack
- **Body (markdown):** …

## Questions for you
1. …
```

## Anti-patterns

- Filing or editing Linear issues in Phase 1 without user ask.
- Mentioning other clients or generic infra in TalentCo issue bodies when the work was not TalentCo delivery.
- Guessing project/team when MCP list results disagree with the table — confirm or ask.
- Using **`save_project` description** to stand in for a **Project update** post when the user wanted the **Updates** feed; use the dialog/API or supplied markdown instead.

## Related

- Issue create/update format and DoR: [linear-issues-talentco](../linear-issues-talentco/SKILL.md)
- Pre-plan product/code discovery: [talentco-feature-planning](../talentco-feature-planning/SKILL.md)