brag-sheet

Brag Sheet — Work Impact Writer

Turn engineering work into evidence-backed impact statements for performance reviews, self-reviews, promotion packets, and weekly updates. Uniquely mines Copilot CLI session logs, git history, and PRs to reconstruct forgotten work.

USE FOR: "brag", "log work", "what did I do", "backfill", "performance review", "self-review", "promo packet", "weekly update", "status report", "write impact statement", "what did I ship", "I forgot to log my work", "review prep", "accomplishments" DO NOT USE FOR: project management, sprint planning, time tracking, ticket creation

Quick Start

Agent Behavior Rules

1. DO confirm the time range and scope before scanning sources. Don't assume "last week" — ask.
2. DO check which tools are available (save_to_brag_sheet, git, gh) before choosing a workflow.
3. DO always include all three parts: action → result → evidence. If evidence is missing, write (evidence needed) — never silently omit.
4. DO show all drafted entries to the user before saving. Never call save_to_brag_sheet or any write tool until the user has explicitly confirmed the entries in the current turn. A prior general instruction ("yes, save everything") does not count — require per-batch confirmation.
5. DO group related commits into a single entry. Ten commits on the same feature = one entry.
6. DO preserve the user's voice. Reframe for impact, but don't invent accomplishments or inflate scope.
7. DO NOT fabricate metrics, team sizes, or impact numbers. If the user doesn't provide a number, don't invent one.
8. DO NOT write entries for work the user only described verbally without verifying. Ask: "Did this ship? Is there a PR or doc I can reference?"
9. DO NOT skip the backfill scan steps or draft entries before scanning is complete.
10. DO NOT pad weak periods with trivial entries. An honest gap is better than inflated fluff.

Entry Format

Every entry uses impact-first framing with three required parts:

Did [action] → [result/impact] → [evidence]

Do not output an entry unless it includes all three parts. If evidence is missing, ask for it or mark as "(evidence needed)".

Anti-Patterns

Evidence Ladder

Not every entry needs a metric. Use the strongest evidence available:

Never invent a metric to fill the gap. Qualitative evidence with context beats fabricated numbers.

Categories

How to Help the User

Follow this decision tree:

1. If save_to_brag_sheet tool is available → use extension tools directly (save_to_brag_sheet, review_brag_sheet, generate_work_log). Do not reference or attempt to call these tools unless they are confirmed available.

   • Before calling save_to_brag_sheet, display the entry and ask: "Save this entry? (yes/no)". Do not batch-save without explicit per-batch approval from the user in the current turn.

2. If git or gh CLI is available → backfill from commits and PRs (see Backfill section below)

3. Otherwise → guided interview: "What did you work on?", "Who benefited?", "What's the evidence?"

For each entry, walk through: What (the deliverable) → Why (who benefits) → Evidence (PR, metric, link). Output formatted markdown the user can paste into a review doc.

Backfill Workflow

When the user asks "what did I do last week" or "backfill my history":

Follow these steps in order. Do not draft entries until scanning is complete.

Step 1: Scan available sources

Check what's available, then mine each source:

git --version 2>/dev/null         # for commit mining
gh --version 2>/dev/null          # for PR mining

Use ReadFile to check for workspace YAML files at: ~/.copilot/session-state/<session-id>/workspace.yaml If no files are found at that path, treat as "no session history" and proceed.

Git commits — recent commits by the user in the current repo:

AUTHOR_EMAIL=$(git config --get user.email)
git log --author="$AUTHOR_EMAIL" --since="2 weeks ago" \
  --pretty=format:'%h|%ad|%s' --date=short --no-merges

PR history — merged PRs across repos:

gh pr list --author @me --state merged --limit 20 \
  --json number,title,repository,mergedAt

Copilot session history (unique to this skill):

• Path: ~/.copilot/session-state/<session-id>/workspace.yaml
• Read fields: summary, cwd, repository, branch
• Skip sessions without a summary field
• Note: this directory may not exist on all machines

If none of these sources are available, fall back to the guided interview.

Step 2: Group related work

Cluster related signals into one entry:

• Same PR + its commits → 1 entry
• Multiple commits on the same file/feature within 3 days → 1 entry
• Copilot sessions referencing the same repo + branch → merge into PR entry if one exists

Step 3: Draft entries

Write impact-first entries for each group. Assign categories.

Step 4: Present and refine

Show all drafted entries to the user. Adjust based on feedback.

Step 5: Output

Format as markdown grouped by week:

## Week of 2025-04-14

### 🚀 PRs & Features
- **Migrated auth service to managed identity** → eliminated 3 secret rotation incidents/quarter → PR #312

### 🏗️ Infrastructure
- **Built CI pipeline for copilot-brag-sheet** → 107 tests across 3 OSes × 3 Node versions → shipped v1.0.0

Performance Review Prep

When the user is preparing for a performance review (Connect, annual review, etc.):

Structure

1. Gather — collect entries from the work log (or backfill using the workflow above)
2. Select — pick the top 3–5 highest-impact items
3. Rewrite each item with three parts:
   • What I did — the specific action
   • Why it mattered — who benefited, what changed
   • Proof — PR number, metric delta, dashboard link, customer outcome
4. Organize by impact theme (not chronologically):
   • Delivering results / operational excellence
   • Customer / team impact
   • Collaboration / mentoring / leadership
   • Growth / learning
5. Ask for gaps — if evidence is missing, prompt the user: "What metric changed?", "Who was unblocked?", "What's the PR or incident ID?"

Strong vs weak entries

Narrative format

For longer narrative sections, use STAR: Situation → Task → Action → Result.

For Microsoft employees using the Connect preset, frame entries around Core Priorities: delivering results, customer obsession, teamwork, and growth mindset.

Output Contract

Before finishing, ensure:

1. Every entry has action → result → evidence (mark (evidence needed) if missing)
2. No fabricated metrics — only user-provided or source-verified data
3. Entries shown to user before saving
4. Time range explicitly stated
5. Output is pasteable markdown with categories assigned

Gotchas

No recent commits in the current repo

The user may work across multiple repos. Before concluding there's nothing to backfill:

1. Ask if they want to scan a different repo or branch
2. Check gh pr list --author @me --state merged for cross-repo PRs
3. Fall back to the guided interview — not all impactful work leaves git traces (design docs, incident response, mentoring)

Review period doesn't match git history

Performance reviews often cover 6–12 months. Explicitly set the date range:

AUTHOR_NAME=$(git config --get user.name)
git log --author="$AUTHOR_NAME" --since="2024-07-01" --until="2025-01-01" --oneline

PR history (gh pr list --state merged) is more reliable for long time ranges than commit logs.

User can't quantify impact

Not every entry needs a number. See the Evidence Ladder above. Acceptable evidence includes PR links, "unblocked Team X", or qualitative outcomes with context. Never invent a metric to fill the gap.

Copilot session directory doesn't exist

~/.copilot/session-state/ only exists if the user has run Copilot CLI sessions. Don't error — silently skip and note: "No Copilot session history found; scanning git and PRs only."

"brag" might mean something else

The user might say "brag about this feature to my team" (a launch announcement, not a work entry). Confirm intent if ambiguous.

Pair programming or co-authored commits

If multiple authors appear on the same commits, ask: "Should I credit this as your work, shared work, or skip it?"

Automatic Session Tracking (Optional)

⚠️ Before installing: The copilot-brag-sheet extension adds three write-capable tools (save_to_brag_sheet, review_brag_sheet, generate_work_log) to all future Copilot CLI sessions, not just brag-sheet sessions. Install only if you intend to use automatic tracking long-term. This is not required — the core skill works without it using git and gh CLI.

For automatic background tracking of every Copilot CLI session (files edited, PRs created, git actions), you can install the community copilot-brag-sheet extension.

Install by pinning to a specific release tag (do not install from the default branch):

# Replace vX.Y.Z with the latest release tag listed at:
# https://github.com/microsoft/copilot-brag-sheet/releases
gh extension install microsoft/copilot-brag-sheet@vX.Y.Z

After installing, verify the correct version is active:

gh extension list

ℹ️ copilot-brag-sheet is a community extension. Verify release notes and the repository's SECURITY.md before pinning to any new version, especially in regulated or enterprise environments.