/promotion

name: promotion
description: Build and maintain a sourced promotion map for the user's next level. It interviews the user about their target (level, track, cycle, and why), researches how promotions actually work at their company (process, calendar, packet template, the rubric managers rate against), maps the org and who has first-hand knowledge of the user's work, and computes when to talk to their manager. Every fact carries a source and a verified/unverified/inferred status, and conflicting sources are shown, not resolved silently. Writes ~/.claude/skills/flagrare/career/promotion-map.md and .json, which impact-scan, opportunity-scan and career read. Use when the user says "promotion", "promo plan", "how do promotions work here", "when should I talk to my manager about promotion", "who should see my work", "am I ready for senior", "build my promotion map", or "promotion packet" (packet mode). Also trigger when the user asks about career strategy, sponsors, or calibration at their company.

Promotion

> **No em-dashes.** Nothing this skill writes may contain an em-dash; use a comma, colon, or parentheses instead. Enforced by a repo hook. See `/flagrare:write-docs`.

> **Plain words.** In anything the user reads, use the plain names in `<plugin root>/lib/career/GLOSSARY.md` ("Senior behaviors", not "rubric rows"; "your written case", not "packet"; "the project you own", not "initiative"). The first time a term appears, say what it means in a few words and add the company's own word in parentheses when the user will hear it at work.

A promotion is decided in a room the user isn't in, from a written case, by people who mostly don't know them, on a calendar set months ahead. This skill makes those facts visible early: where the user wants to go and why, how the company actually decides, what the rubric asks for, who has first-hand knowledge of their work, and when the key conversations must happen.

It writes a **promotion map**: `promotion-map.md` for the user to read and bring to a 1:1, and `promotion-map.json` with the same facts for the other career skills. The map is local and private. **This skill never posts, sends, or publishes anything.**

Library

The plugin ships helper scripts at `<plugin root>/lib/career/`. The plugin root is two directories above this skill's base directory. Run each as `python3 <plugin root>/lib/career/<script>.py ...`. They only read and print JSON; this skill writes every file with the Write tool, because a sandboxed shell cannot write under `~/.claude/skills`.

• `career_state.py paths|contributions|plan --home "$HOME"`: file locations, the contributions log (union of old and new locations), and the migration plan.
• `map_schema.py check <map.json> --today YYYY-MM-DD`: errors, missing sections, stale sections (over 90 days), conflicts.
• `deadlines.py --deadline YYYY-MM-DD --today YYYY-MM-DD [--dead START:END ...] [--published]`: when to talk to the manager. `--dead` is optional and repeatable.

The map's shape is in `reference/map-schema.md`, and the markdown layout is in `reference/map-template.md`. The other shared state files (contributions log, flags, initiatives) are described in `<plugin root>/lib/career/STATE.md`; clear a handled flag by writing `flags.json` back without it.

1. Load state (every run)

1. Run `career_state.py plan`. Apply each `write` action with the Write tool, reading the target first if it already exists (the Write tool will not overwrite a file it has not read). A `mkdir` action needs no separate step: the folder is created by the first file written into it. Do not write a placeholder map. **Never delete anything.** 2. Read `~/.claude/skills/flagrare/config.json` (top-level identity keys, the `skills.promotion` block) and the existing map, if any. If the config file or the `skills.promotion` block is missing, continue with defaults. 3. No map means a **first run** (section 3). A map whose `map_schema.py check` output lists `missing` sections means an interrupted first run: resume it at the earliest phase whose sections are missing. Otherwise run a **refresh** (section 4), unless the user asks for `packet` mode (section 5).

**Called by `/flagrare:career`.** The arguments name a mode (`first_run`, `resume` or `refresh`) and the sections to work on: do only those. When they also say `scheduled`, never interview or ask: re-research and save only the sections that need no answer from the user (process, calendar, rubric, org, precedent), and return each one that needs the user (target, people, manager questions) as a line for the coordinator's Needs you list. In either case, return a short summary of what changed instead of the full map.

2. Rules for every fact

• **Source, date, status.** Every fact gets a link or quoted location, the date you checked it, and a status: `verified` (read and quoted in the raw source), `unverified` (a summary, snippet or secondhand), or `inferred` (your reasoning).
• **Quote verbatim from the raw source.** Summarizing fetch tools paraphrase. When a quote will be relied on, re-read the raw page (for example the page's JSON or HTML) and confirm the exact words.
• **Show conflicts, never pick silently.** When two sources disagree (an org chart vs a squad directory, a process page vs the ladder file), store both as `alternatives` and tell the user.
• **"Nothing found" is a valid result.** If a step finds nothing, add a concrete question to `manager_questions` instead of guessing. Many companies have no written process.
• **People facts are sensitive.** Only read the user's own interactions. Record who has first-hand context on the user's work, never a ranking of how useful people are.
• **Ask for consent before using the browser** on HR portals or internal sites.

3. First run

Tell the user up front: the first run is long, often an hour or more, and it saves after each phase, so it can be stopped and resumed.

**Every save** writes both `promotion-map.json` and `promotion-map.md`