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:
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,statusCheckRollupNever 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
# π§ 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.
## πΊοΈ 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 HEREafter 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,storyandtechnical. Inshortit 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
## π’ 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, prominentlyDo 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:
## β 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.
## π 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:
**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:
**Verified:** TypeScript + unit tests
**Not verified:** production browser workflowNo 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:
# π§ <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.
# π― Decisions
<decision-choice blocks, with the PR URL if approval is the decision>If there are none:
# π― 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.
# π¬ 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.
# π§ This Tab
# π’ Bottom Line
# π§± Architecture / Code
# π§ͺ Verification
# β οΈ Risks
# π Git / PR
# π― Decisions
# β‘οΈ NextThis is the only mode where Level 3 detail is shown by default.
Special states
Blocked
# π΄ 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."
# β
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.