Brief

Turns raw material into decision-ready briefs: executive summaries, status updates, meeting pre-reads, and decision documents. Use when asked to brief someone, write a TL;DR or weekly update, prepare a board, investor, or incident update, hand off a project, compare options with a recommendation, or condense a long report, thread, transcript, or doc pile into what the reader needs to act. Also when updates run long, readers skim past the point, or the lede keeps getting buried. Not for plain compression with no decision to serve, or for recurring digests pulled from external sources.

User configuration and learned preferences live in ~/Clawic/data/brief/ (see setup.md on first use, preferences-template.md for the learned-preferences file format). If you have data at an old location (~/brief/ or ~/clawic/brief/), move it to ~/Clawic/data/brief/.

When To Use

• User asks for an executive brief, TL;DR, or bottom-line summary of material they provide
• A recurring status or project update is due and the reader needs the delta, not a restate
• A meeting, board session, or review is coming up and the reader needs decisions-needed plus prep
• An incident is live and stakeholders need impact, status, and a committed next-update time
• A transition, offboarding, or vacation cover needs a handoff with gotchas and open questions
• The reader must choose between options and needs a recommendation with tradeoffs
• A long report, thread, transcript, or doc pile must be condensed to what drives a decision

Not for: compressing content when there is no decision or action to serve — use summarizer for shorter-content-only needs.

Quick Reference

Situation	Play
Reader must choose between options	Decision brief: recommendation first, 2-3 options including do-nothing (templates.md)
Recurring status update	Project brief: lead with the delta since last brief, never a full restate (recurring.md)
Meeting coming up	Meeting brief: decisions needed + prep checklist; deliver the day before, not the morning of (delivery.md)
Board or investor update due	Board brief: metrics vs plan, lowlights before highlights, explicit asks (templates.md)
Something is on fire right now	Incident brief: impact in user terms, status, committed next-update time (templates.md)
Findings must become a decision	Research brief: answer with confidence level, evidence split from interpretation (templates.md)
Transition, offboarding, vacation cover	Handoff brief: gotchas and open questions outrank achievements (templates.md)
Source is huge or messy	Triage by decision-relevance, never proportionally to source length (sources.md)
Sources disagree or have gaps	Show the conflict and name the gap — never average or silently narrow (sources.md)
Audience unclear or mixed	Name the decider; their action sets depth and jargon (audiences.md)
Formal channel (exec email, external doc)	Same structure, strip emoji markers, plain headers (delivery.md)
Brief keeps coming back "too long"	Cutting passes, hedge blacklist, decision-grade rounding (writing.md)
User reacts to a delivered brief	Record it in ~/Clawic/data/brief/preferences.md; signal mapping in dimensions.md
Anything else	Executive structure: bottom line, 3 key points, explicit ask

Depth on demand: templates.md section-by-section structures per type · sources.md raw-material triage, conflicts, gaps · audiences.md reader calibration · delivery.md channels, register, timing · writing.md line-level compression · recurring.md running a brief series · dimensions.md preference taxonomy · setup.md first-use loading.

Core Rules

1. User Specifies Sources

When the user requests a brief:

1. User provides the information OR specifies where to get it
2. If a source requires access, the user grants it explicitly
3. Skill structures and formats the output

Example:

text

User: "Brief me on project X status"
Agent: "I'll need access to the project docs. Can you share
        the status doc or grant access to the project folder?"
User: [shares doc or grants access]
→ Brief generated from user-provided source

2. A Brief Is Not a Summary

A summary compresses content; a brief serves the reader's next action. If you cannot name the decision or action this brief enables, ask "what will you do with this?" before writing. Competent people summarize; briefers select.

3. Write in Reverse Reading Order

Compose ask → bottom line → key points → context; the reader consumes the opposite order. Writing front-to-back is how ledes get buried: you discover the point last and leave it there.

4. Bottom Line Commits

One sentence, no hedge. If it contains "and", you have two takeaways — keep the one that changes what the reader does, demote the other to key points. "Mostly on track, but..." is not a bottom line; it is a decision you refused to make.

5. Three Key Points, Five Hard Max

A point qualifies only if removing it would change the reader's decision. Six "key" points means you haven't decided what matters — cut, or tier the rest under a "more detail" note. This selection rule beats source length: one decision-relevant page outweighs forty pages of background.

6. Every Number Carries a Comparator

"$1.2M revenue" is decoration; "$1.2M, 8% under plan" is a brief line. Valid comparators: target, prior period, benchmark. None available → write "no baseline yet" or drop the number.

7. Status Words Have Definitions

• On track — schedule/scope buffer intact
• At risk — buffer being consumed; the first slip counts, no grace period
• Blocked — cannot proceed without a named external action

Declaring at-risk early is cheap. A green-to-red flip with no warning destroys trust in every future brief you send. (status_scheme: rag in config maps these 1:1 to Green/Amber/Red.)

8. Learn Only From Explicit Feedback

"Too detailed" / "missing X" / "perfect" → one line in ~/Clawic/data/brief/preferences.md with a level (pattern/confirmed/locked, promotion rules in dimensions.md). Check the file before writing any brief — a well-built brief in the wrong learned format still misses.

Scope

This skill:

• ✅ Structures information the user provides into briefs (act-as writer: it drafts; the user sends)
• ✅ Learns format preferences from explicit feedback
• ✅ Stores configuration and preferences in ~/Clawic/data/brief/

User-driven model: the user specifies WHAT information to include and grants access to any needed sources; the skill handles STRUCTURE and FORMAT.

This skill does NOT:

• ❌ Access files, email, or calendar without user request
• ❌ Pull data from sources the user hasn't specified
• ❌ Store brief content (only configuration and format preferences)

Output Gates

Run before delivering any brief:

• Bottom line survives alone — if the reader stops there, they still have the takeaway
• Every metric has a comparator or an explicit "no baseline yet"
• The ask names an owner and a date, or states "no action needed" — never an implied ask inside an FYI
• Bad news sits above the fold, next to its mitigation, not in section four
• Data that can go stale carries source and as-of date
• Conflicting sources are shown as a conflict, never averaged into one number
• Jargon calibrated to the least-technical decider, not the most technical reader
• Format matches ~/Clawic/data/brief/config.yaml and preferences.md — checked, not remembered

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/brief/config.yaml.

Variable	Type	Default	Effect
default_length	one-screen | one-page | two-page	one-page	Sizing target: one-page = 450-500 words (templates.md); one-screen = fits without scrolling (chat cap, delivery.md); two-page only when the reader asked for depth
status_scheme	words | rag	words	Status labels everywhere a status renders: On track/At risk/Blocked vs Green/Amber/Red (definitions in Rule 7 apply to both)
emoji_markers	bool	true	Section markers (⚡📊🎯) on informal channels; false = plain headers everywhere (formal channels strip them regardless, delivery.md)
default_channel	chat | email | doc	chat	Assumed delivery surface; sets register and length caps per delivery.md
locale	text (BCP-47, e.g. en-US)	en-US	Date order (Jul 21 vs 21 Jul), decimal/thousands separators, and currency symbol + placement in every rendered number and date (writing.md); falls back to ~/Clawic/profile.yaml before the default

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Audience mix: who reads most briefs (boss, board, clients, team) — shifts the default template and jargon level (audiences.md)
• Conventions: section names, bullet style, status-word extensions — shifts the structures in templates.md
• Timing: lead times, cadence, delivery day — shifts the scheduling guidance in delivery.md
• Exclusions: topics or metrics never to include (confidential, legal) — screens extraction in sources.md
• Voice: bad-news directness, person (I/we/team), formality floor — shifts the register rules in writing.md
• Localization: beyond the locale tag — timezone for timestamps and deadlines, and multi-currency policy (show native vs converted, which symbol) when amounts span currencies — affects number lines in writing.md and the incident/board timestamps in templates.md

Config vs learned preferences: config.yaml holds what the user declared; preferences.md holds what feedback revealed (levels in dimensions.md). A stated preference that names a config variable goes straight to config.yaml. Precedence: config > confirmed/locked learned preferences > defaults. Universal variables (locale, timezone) additionally fall back to ~/Clawic/profile.yaml before their table default: config > profile.yaml > default.

Traps

Trap	Why it fails	Do instead
Burying the lede	Readers triage; the point placed last is the point never read	Bottom line first — and write it first (Rule 3)
Hedged bottom line	Reader cannot act on a hedge	Commit to one takeaway; nuance goes in key points
Watermelon status (green outside, red inside)	The eventual flip costs more trust than early honesty ever would	First buffer slip → At risk (Rule 7)
Summarizing proportionally to source length	Background volume drowns the decision material	Select by decision-relevance (Rule 5, sources.md)
Averaging conflicting sources	Reader inherits a number nobody actually reported	Show both figures with provenance; the conflict may be a key point (sources.md)
Sandwiching bad news	In a brief, softening reads as hiding	Bad news first, mitigation beside it
Options without a recommendation	"Neutral" presentation transfers your analysis work to the reader	Recommend one; keep tradeoffs honest and visible
Exactly two options	Frames a false binary and hides the status quo	Price do-nothing as an explicit option (templates.md → Decision)
One brief for decider and spectators	Too deep for one, too shallow for the other	Write for the decider; spectators get the same brief, not a longer one (audiences.md)
Restating unchanged items every edition	Trains readers to skim; they miss the week something changes	Delta only, unchanged sections collapse to one line (recurring.md)
Precision theater ($1,234,567.89)	False confidence and a slower read	Decision-grade rounding: 2-3 significant figures (writing.md)
Emoji markers on formal channels	Reads unserious to exec/external audiences	Same structure, plain headers (delivery.md)

Where Experts Disagree

• Bullets vs narrative memos. The Amazon six-page school argues prose forces complete thinking; the BLUF school argues readers triage and bullets respect that. Boundary: match the reading ritual — narrative where the room reads silently before discussing; bullets where the brief replaces the meeting. Default here: bullets, with a prose-memo variant in templates.md.
• Recommendation-first vs neutral staffing. Staff tradition separates information briefs from decision briefs and warns against advocacy; operators say a briefer who won't recommend transfers the analysis work. Boundary: recommend by default; go neutral only when brokering between peer factions — and say you're doing it.
• How much context. "Context is respect for the reader" vs "context is where ledes go to die." Boundary: context earns lines only when it changes how the reader acts on the points; SCQA-test it (templates.md), otherwise cut.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/brief (install if the user confirms):

• summarizer - compression when there is no decision to serve, just shorter content
• digest - recurring curated updates pulled from external sources on a schedule
• report - recurring configured reports with fixed data sources
• meetings - the full meeting system (notes, agendas, follow-ups); brief covers only the pre-read

Feedback

• If useful, star it: https://clawic.com/skills/brief
• Latest version: https://clawic.com/skills/brief

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/brief.