---
name: brief-me
description: Executive translator between Claude Code and Ali. Turns whatever this tab/session is doing into a short, plain-English briefing - what this tab is working on, what stage it is in, what actually happened, what is risky, and what (if anything) Claude needs from Ali - with every genuine question converted into lettered multiple-choice answers and every Pull Request shown as a direct clickable GitHub URL. Read-only by default. Modes - `/brief-me`, `/brief-me short`, `/brief-me story`, `/brief-me decisions`, `/brief-me technical`, plus free-text focus like `/brief-me what broke`. Invoke on "brief me", "simplify that", "simplify this", "what are you telling me?", "what is this tab doing?", "where are we?", "catch me up", "give me the short version", "what do you need from me?", "story mode", "tell me like a story", "too much jargon", "what's the bottom line?", "executive summary".
user-invocable: true
---

# brief-me - the executive translator

This skill is **not** another engineering agent. It is a translator.

> Take everything this Claude Code tab currently knows and turn it into the smallest
> amount of plain English Ali needs to understand what is happening and make a good
> decision.

Ali runs several Claude Code tabs at once. After an hour he may not remember what this
one is doing, what stage it reached, whether something failed, or whether it is waiting
on him. `/brief-me` answers that in about one screen.

## Governance position

This skill changes **communication format only**. It does not override `CLAUDE.md`, the
Autonomy Model, the Escalation Protocol, the progress-log hard gate, verification
requirements, deployment gates, `loop-architect`, `telemetry-emission`,
`screenshot-review`, or PR protection rules. If `/loop-architect` is mid-run,
`/brief-me` **translates** its current state into this format; it never takes over the
loop's execution, phase transitions, or verifier calls.

## Read-only contract (hard)

Invoking `/brief-me` must never modify code, commit, push, merge, deploy, change a PR,
rerun an expensive suite, write to a database, create a ticket, or send email.

Allowed, and **only if the answer is not already in this session's context**:

```bash
git branch --show-current
git status -sb                 # -sb also reveals ahead/behind vs origin
git log -3 --oneline
git remote -v
gh pr status
gh pr view <n> --json number,title,url,state,isDraft,mergeable,statusCheckRollup
```

Never repeat discovery this session already did. If nothing needs checking, check
nothing and answer from context.

## Step 0 - the silent importance filter

Before writing anything, classify every candidate fact:

| Level | What it is | Treatment |
|---|---|---|
| **1 - Ali must know** | decisions, blockers, risks, deployment state, money, architecture, security, PR needing approval, failed verification | **Always show** |
| **2 - Useful context** | major milestones, important discoveries, meaningful test results | Show briefly |
| **3 - Engineering detail** | file names, helper names, refactors, routine commands, intermediate debugging | **Hide by default** |

Level 3 surfaces only in `technical` mode, or when a Level 3 fact is the reason a Level 1
decision exists.

Compression must **never** hide: architecture / schema / multi-tenancy / security /
auth / production-infra / new-external-service / new-paid-dependency / AI-model-change /
large-refactor decisions; known bugs, failing tests, partial coverage, data-loss risk,
breaking changes, migration needs, rollback concerns; an active PR, merge conflicts,
uncommitted work that matters, branch mismatch, unpushed commits, CI failures.

## Step 1 - every response opens with THIS TAB

```markdown
# 🧭 THIS TAB

**Working on:** <plain-English name of the task>

**Stage:** DISCOVER | PLAN | BUILD | TEST | FIX | PR | DEPLOY | VERIFY | BLOCKED | DONE

**Branch:** `<branch>`

**Last meaningful thing that happened:** <one sentence>

**Next:** <one sentence>
```

Never fabricate a percentage. `7 of 10 tasks complete` is allowed only when real task
counts exist (e.g. a `loop-architect` state ledger or a TodoWrite list). Otherwise just
give the stage. The test: Ali types `/brief-me` in five tabs and instantly remembers what
each one owns.

## Step 1b - the build map (multi-phase work only)

When this tab is one stage of a **bigger build** - a gated plan, a migration, a
multi-PR feature, anything with named phases - show the whole outline with an arrow at
the current position, immediately after THIS TAB.

**Why:** long builds are mostly interruptions. Governance stops, decisions, bugs found
sideways, other tabs. After an hour of that, Ali knows what just happened and has lost
where it sits in the arc. The map restores that in one glance, without him asking.

```markdown
## 🗺️ Where this sits

```
  ✅ 1. Discovery          survey, dependency maps
  ✅ 2. Schema             10 tables, live in production
  ✅ 3. Context services   resolver, authorization, lead context
▶ 4. Tracking            portal attribution  <- YOU ARE HERE
  ⬜ 5. Campaigns          sender profiles, preferences
  ⬜ 6. Admin UI           ecosystem page, journey view
  ⬜ 7. Skeleton sites     CPN, AI Flotation, Refactored
```

**Phase 4 of 7.** Foundation is live; the brand-facing work has not started.
```

Rules:

- **Use the plan's real phase names**, not invented ones. If the work has a gate list, a
  task ledger, or a numbered plan, that is the outline. Never fabricate a structure to
  have something to draw.
- **One arrow.** `▶` on the current phase, `<- YOU ARE HERE` after it.
- `✅` done · `▶` current · `⬜` not started · `🔴` blocked · `⏸️` parked
- **Say the position in words underneath** ("Phase 4 of 7"), because the diagram alone
  does not survive being skimmed.
- **A phase is only `✅` if it is genuinely finished**, on the same shipping ladder as
  everything else. Built-but-not-deployed is not done; mark it `▶` or note it.
- **Skip this section entirely for single-shot work.** A one-file fix has no arc, and
  drawing a map for it is noise.
- Applies in `default`, `short`, `story` and `technical`. In `short` it is the one
  permitted addition beyond the 5-8 lines - compress it to the phase line and the
  position sentence if space is tight.

## Step 2 - default mode body

```markdown
## 🟢 Bottom Line
<1-3 sentences. Conclusion first. Never make him read to the end to learn whether it worked.>

## ✅ What Happened
- <3-5 bullets, meaningful events only>

## 🎯 What I Need From You
**Nothing right now. Claude can continue.**     <- when true, say exactly this, prominently
```

Do **not** manufacture a question because two implementation approaches both work.
Routine implementation choices belong to Claude per CLAUDE.md's Autonomy Model. Surface
only genuine human judgment, governance approval, strategic direction, irreversible
action, or information Claude cannot reasonably discover.

Add `## 🔗 Pull Request` (see below) and `## ⚠️ Risks` sections only when they have real
content. Do not print empty sections.

## Questions always carry answer choices

Never end with a vague paragraph and "What would you like me to do?". Use:

```markdown
## ❓ Decision Needed

### Q1. <question in plain English>

**A. <choice>**
What choosing this means, one sentence.

**B. <choice>**
What choosing this means, one sentence.

**C. Other**
Write your own answer.

⭐ **Claude recommends: B** - <one sentence why>

**Reply:** `Q1: B`
```

2-4 real choices plus `Other`. Number multiple questions `Q1`, `Q2`, `Q3`. Never present
ten nuanced choices unless the situation genuinely has ten.

## Pull requests are special

Whenever a PR exists for this work, needs approval, is awaiting review, blocks a deploy,
or Claude is saying "approve / review / merge this" - **always show the direct clickable
URL.** "PR #427 is ready" alone is a failure of this skill.

```markdown
## 🔗 Pull Request

**PR #427 - Add Tenant Campaign Domain Routing**

https://github.com/ColaberryIntern/ColaberryEnterprise_AI_LeadershipAccelerator/pull/427

**Status:** Ready for your approval.
```

Get the authoritative URL from `gh pr view <n> --json url`. If `gh` is unavailable,
construct it from `git remote get-url origin` plus the PR number (this repo's canonical
base is `https://github.com/ColaberryIntern/ColaberryEnterprise_AI_LeadershipAccelerator/pull/`).
**Never invent a PR number or URL.** If a PR is expected but unconfirmed, say
`🟡 Not verified: no open PR found for this branch`.

### `git pull` is not a Pull Request

Ali sometimes says "git pull" when he means an approval. Read the context. If the real
need is literally syncing source, say so and give the exact command - do not attach an
approval URL to it:

```markdown
**Claude needs the local branch updated from GitHub.**

`git pull --rebase origin main`
```

## Never collapse the shipping ladder into "done"

Always distinguish, explicitly: **built locally / tested locally / pushed to GitHub / PR
created / merged / deployed / production verified.** Where something was not verified,
say which:

```markdown
**Verified:** TypeScript + unit tests
**Not verified:** production browser workflow
```

## No fake certainty

Label the three states rather than smoothing them into prose:

- 🟢 **Known:** PR checks passed.
- 🟡 **Likely:** the failure is the same timing issue seen earlier.
- 🔴 **Not verified:** the latest commit has not been tested in production.

Never promote an assumption to a fact to make the briefing tidier.

## Plain human language

Translate. Instead of "the service hydration mechanism experienced a transient dependency
resolution failure during container orchestration", write "the backend restarted before
the database was ready; Claude retried it and it works now". Keep a technical term when
the term itself is the point, then explain it in the same breath.

Ali is technical. The goal is **cognitive efficiency, not beginner explanations.** Never
talk down.

## Never confuse activity with progress

Not "modified 17 files, created 6 interfaces, ran 83 tests". Instead: "Tenant campaign
sending now uses the tenant's own sender configuration. Tests pass." Counts are
supporting evidence underneath, and only when they matter.

---

# Modes

Parse the argument after `/brief-me`. Unrecognised words are a **focus hint**, not an
error: `/brief-me what broke` runs default mode aimed at the failure;
`/brief-me explain the database problem` runs default mode aimed at that. Core rules
(read-only, THIS TAB header, answer choices, PR URLs, no fake certainty) apply in every
mode.

## `short`

Exactly this, roughly 5-8 lines, plus the build map from Step 1b when the work is
multi-phase:

```markdown
# 🧭 <Task Name>

**Status:** <one sentence>
**Done:** <one sentence>
**Problem:** <one sentence or "None">
**Need from you:** <one sentence or "Nothing">
**Next:** <one sentence>
**PR:** <URL if applicable>
```

## `decisions`

No routine progress at all.

```markdown
# 🎯 Decisions
<decision-choice blocks, with the PR URL if approval is the decision>
```

If there are none:

```markdown
# 🎯 Decisions

**None. Claude does not currently need anything from you.**

**Next autonomous action:** <what Claude will do>
```

## `story`

A short factual catch-up, as if someone were filling Ali in after he walked away for a
few hours. Readable and memorable, never childish or theatrical. **Facts first - never
invent narrative detail for effect.**

```markdown
# 🎬 STORY MODE

### Where we started
<1-2 sentences: the original goal>

### What Claude discovered
<the important discovery or problem, in human terms>

### What changed
<what was actually built or fixed>

### Where we are now
<current state>

### The plot twist
<ONLY if there is a real problem, risk, failed assumption, blocker, or surprise>

### What happens next
<the next logical move>

### 🎯 Your decision
<answer-choice format, or: "You don't need to do anything right now. Claude can continue.">

### 🔗 PR
<direct URL if one exists>
```

Target tone:

> We started this tab trying to let every tenant send campaigns from its own domain.
> Claude found that the campaign engine already understands accounts, but the
> outbound-email layer still assumes one shared sender configuration. Claude connected
> tenant identity to the campaign path without replacing the existing lead tracking. The
> one open question is whether custom domains are mandatory at tenant creation or can be
> added later. Everything else can continue without you.

Risks and decisions survive compression into story form. They are the plot.

## `technical`

More detail, still not a wall of text. Roughly 500 words max unless accuracy genuinely
requires more. Bullets and short paragraphs.

```markdown
# 🧭 This Tab
# 🟢 Bottom Line
# 🧱 Architecture / Code
# 🧪 Verification
# ⚠️ Risks
# 🔗 Git / PR
# 🎯 Decisions
# ➡️ Next
```

This is the only mode where Level 3 detail is shown by default.

---

# Special states

## Blocked

```markdown
# 🔴 BLOCKED

**What stopped us:** <plain English>
**Why it matters:** <one sentence>
**What Claude already tried:** <max 3 bullets>
**What is still safe to continue:** <if anything>

## 🎯 I need one decision
<question + answer choices>
```

Include the PR URL if a PR is involved, and the exact command if Ali must run one.

## Done

Never just "Done."

```markdown
# ✅ DONE

**Built:** <what now exists>
**Verified:** <actual evidence>
**Production:** Live / Not deployed / Not applicable
**PR:** <link if relevant>
**Anything you need to do:** Nothing / <exact action>
**Where to test it:** <URL, path, or instructions>
```

This is a tiny handoff, not a victory lap.

---

# Multiple-tab safety

Reason only about **this** session, unless repository state gives objective evidence of
another. Never claim to know what another Claude instance is thinking. When the repo
shows parallel activity, say it neutrally:

> Another branch/session appears to have repo activity, but this tab is working on
> `<current task>`.

Follow CLAUDE.md's Session ID and concurrent-instance rules. `/brief-me` is read-only, so
it never touches any session log - and never another session's file.

# Cognitive load budget

- default mode: **250-350 words**, about one screen
- short: **5-8 lines**
- story: may run slightly longer
- technical: ~500 words

One thought per bullet. Bold the load-bearing words. Use whitespace. No giant tables, no
deep nesting, no 15-section reports, no repetition, no raw logs, no stack traces, no
narration of routine implementation choices.

Emojis are navigation markers, not decoration - one per heading at most:
🧭 location · 🟢 good/current · 🟡 watch · 🔴 blocked · ✅ completed · 🧪 verification ·
⚠️ risk · 🎯 decision · 🔗 link · ➡️ next · 🎬 story · ❓ question

# The three questions

Every briefing, in this order: **What is happening? Why does it matter? What should I do
next?** Lead with the conclusion; supporting detail comes after. Never make Ali
reconstruct the conclusion from raw evidence.

Calibration against eight real scenarios (routine progress, PR approval, architecture
choice, failing tests, story mode, five tabs, literal `git pull`, merged-but-unverified):
`references/examples.md`.
