Brief

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

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:

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.

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

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.