/brag-doc

name: brag-doc
description: Generate a comprehensive, impact-framed brag-doc entry for a chosen time window (day, week, biweek, month, or custom). Pulls authored PRs, reviews given, commits, deploys, and linked tickets across GitHub, local git, and configured MCPs, then synthesises a themed narrative, leading with outcomes, quantifying impact, owning the work in first-person past tense, separating IC contributions from amplification, and naming the judgment exercised. Output is designed to drop straight into a developer journal, a personal bragging sheet, or a performance-review packet. Accepts a mode argument, `/flagrare:brag-doc resumancer` renders the output as ready-to-paste Resumancer CLI commands (`resumancer impact "..." --branch ...`) instead of markdown. Use whenever the user says "brag doc", "brag sheet", "what did I do this week", "weekly recap", "monthly recap", "performance review prep", "what should I tell my manager", "summarise my impact", "career log entry", "give me my wins", "biweekly recap", or any variant about looking back over a longer window than a single day's standup. Also trigger near review season ("self-review", "perf packet", "evaluation prep"), and on phrases like "log my wins to resumancer" or "make resumancer entries for this week" (which should pass the `resumancer` mode).

Brag Doc

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

Produce a comprehensive retrospective of the user's code work over a chosen time window, written in **brag-doc voice**: themed by impact, quantified where possible, owned in first-person, and structured to be re-read months later in a performance review or copied into a dev journal.

This skill is the long-arc counterpart to `/flagrare:standup-report`. Same data pipeline (GitHub, local git, deploys, tickets, optional MCPs), inverted output:

| | standup-report | brag-doc | |---|---|---| | Window | last working day | day → month (user picks) | | Audience | team, in Slack | future-me, in a journal or review packet | | Tense | conversational past ("most of the day went to...") | accomplishment-framed past ("I shipped X, which reduced Y by Z%") | | Order | chronological / time-of-day | thematic / impact-area | | Goal | "what's the team status?" | "what's worth remembering and re-telling?" |

The single rule that shapes the synthesis: **lead with what got better, by how much, for whom.** Not "I worked on X." That framing, owned, quantified, outcome-first, is what separates a brag doc from a glorified changelog.

Modes

The skill accepts a mode argument that controls output rendering. The synthesis pipeline is identical across modes, only the final render differs.

| Invocation | Mode | Output | |---|---|---| | `/flagrare:brag-doc` | **default** | Brag-doc markdown (headline, themed sections, refs). Suitable for a dev journal, a personal brag sheet, or a performance-review packet. | | `/flagrare:brag-doc resumancer` | **resumancer** | Ready-to-paste `resumancer` CLI commands (`resumancer impact "..." --branch ... --commit ...`), one per theme/unblock/reflection. Skips markdown rendering, the commands are the output. |

Parse the trailing argument on invocation:

• No arg, empty arg, or unrecognised arg → default mode (mention "rendering as brag-doc markdown; pass `resumancer` to emit CLI commands instead" once in the report header, so the user discovers the option organically).
• `resumancer` (case-insensitive) → resumancer mode.

Both modes run the same data-collection, theme-clustering, and impact-framing logic, they diverge only at the render step. If a user wants both outputs in one invocation, they can ask after the fact ("now give me the same thing as Resumancer entries").

Other repurposings (performance-review packet grouped by competency, append to an existing brag sheet, dev-journal append at a known path) stay as natural-language follow-ups, they don't change the fundamental shape of the output the way Resumancer mode does.

Setup (first run only)

Config lives at **`~/.claude/skills/flagrare/config.json`**: a single file shared across all flagrare skills, outside the plugin tree so it survives plugin updates and reinstalls. Skill-agnostic keys (GitHub login, display name, repo scope, local roots) sit at the top level; brag-doc-specific keys nest under `skills["brag-doc"]`.

In Bash, expand `~` explicitly: `"$HOME/.claude/skills/flagrare/config.json"`. The directory may not exist yet, `mkdir -p "$HOME/.claude/skills/flagrare"` before writing.

Step 1: Migrate legacy config (one-time)

If the new path doesn't exist but a legacy per-skill config does, migrate it:

LEGACY="{skill_directory}/config.json"   # old location, lost on plugin reinstall
NEW="$HOME/.claude/skills/flagrare/config.json"
if [ ! -f "$NEW" ] && [ -f "$LEGACY" ]; then
  mkdir -p "$(dirname "$NEW")"
  # Brag-doc had no skill-specific keys in the old shape; carry over top-level only.
  jq '{
    github_login, display_name, first_person, repo_scope, local_repo_roots, tracker_mcp
  } | with_entries(select(.value != null))' "$LEGACY" > "$NEW"
fi

Tell the user once: "Migrated your config from the old per-plugin location to `~/.claude/skills/flagrare/config.json` so it survives plugin updates."

Step 2: First-time setup (if no config exists at the new path)

If the file already exists from another flagrare skill (e.g. `standup-report`), reuse the top-level keys silently, no re-prompting. Otherwise collect via `AskUserQuestion`:

1. **GitHub login**: for `author:`, `commenter:`, `reviewed-by:` searches. Run `gh api user --jq '.login'` to detect and confirm. 2. **Display name**: how to refer to the user. Default to first-person ("I"). 3. **Repo scope**: `org:<name>`, `user:<login>`, or explicit `owner/repo` list. 4. **Local repo roots**: directories to scan for commits (e