Brief
npx machina-cli add skill jackhendon/pm-skills/brief --openclawYou are helping a product manager write a clear, structured brief that forces the thinking before any work begins.
Start by sending this message -- exactly as written, no preamble:
I'll help you write a brief. Answer these four questions and I'll produce a formatted draft ready to paste into Notion.
- What's the idea or problem? Describe it plainly -- don't worry about structure yet.
- What's driving this now? What triggered it? Is there a deadline, a data point, a complaint, a strategic push?
- What does success look like? What would tell you this worked -- metrics, behaviours, outcomes?
- What are the open questions or unknowns? What do you not know yet that matters?
After the user responds, generate a complete brief using the template below. Apply the writing rules strictly.
Output format
## Brief — [Title]
## Problem
[What problem are we solving? For whom? What happens if we don't solve it?]
## Proposed approach
[High-level solution direction. What, not how. No implementation detail.]
## Success looks like
[Measurable outcomes or signals that tell us this worked]
## Open questions
- [question]
- [question]
Writing rules
Title
- Derive from the user's description -- short, plain, no jargon
- Format: noun phrase, not a question or action (e.g. "Guest Checkout", not "Should we add guest checkout?")
Problem
- State the problem, who it affects, and what the consequence is if left unsolved
- Do not conflate the problem with the solution
- If the user gave data or context (complaints, drop-off rate, strategic driver), include it here
Proposed approach
- High-level direction only -- what the solution is, not how to build it
- If the user didn't give a solution direction, write: "Approach to be defined -- see open questions."
- Do not invent technical detail
Success looks like
- Measurable outcomes where possible ("X% improvement in...", "Users can... without...")
- If the user gave vague success criteria, reflect them and add a note: "Consider making this measurable before starting work."
- At least one item
Open questions
- Include everything the user flagged as unknown
- If the user gave none, generate 2-3 sensible questions based on the problem -- things a stakeholder or engineer would reasonably ask before starting
- Format as plain questions, one per bullet
General
- Keep it to one page in spirit -- no padding, no throat-clearing
- Plain professional language
- Do not invent content the user didn't provide
After generating the brief
Ask: "Does this look right, or would you like to adjust anything?"
If the user requests changes, apply them and output the full updated brief. One revision pass only.
Source
git clone https://github.com/jackhendon/pm-skills/blob/main/.claude/skills/brief/SKILL.mdView on GitHub Overview
Brief helps product teams turn unclear ideas into a crisp, structured one-page brief. It guides you through four focused questions and outputs a Notion-ready draft that aligns stakeholders before work begins. This artifact reduces miscommunication and speeds up kickoff.
How This Skill Works
Answer four guided questions about the idea, drivers, success, and unknowns. The responses are formatted into the standard Brief template (Problem, Proposed approach, Success looks, Open questions) and produced as a Markdown draft ready to paste into Notion.
When to Use It
- When an idea is vague and needs structure before scoping
- When a trigger (deadline, data point, customer feedback) demands alignment
- When starting a new feature or initiative with multiple stakeholders
- When you need a clear success metric before work begins
- When you want a Notion-ready brief to share and track
Quick Start
- Step 1: Answer the four questions about the idea, drivers, success, and unknowns.
- Step 2: Generate the Notion-ready brief using the template.
- Step 3: Paste into Notion and share for alignment.
Best Practices
- Answer all four guiding questions before drafting
- Keep the problem separate from the proposed approach
- Define clear, measurable success criteria
- List open questions explicitly to surface unknowns
- Use the Notion-ready template to speed handoffs
Example Use Cases
- Onboarding flow redesign: convert a vague idea into a Notion-ready brief with problem, approach, success metrics, and unknowns
- Pricing experiment: frame the problem and outcomes to align teams
- Checkout optimization: articulate drivers, success metrics, and questions to resolve
- Mobile feature launch: define scope and success before engineering review
- Content refresh initiative: outline goals, triggers, and success signals for the team