dazuck/create-briefing

Create Briefing

Transform work sessions, research, or learnings into shareable briefing documents. Designed for the emerging pattern where documents need to serve both human readers and AI agents that will consume them later.

Core Philosophy

Dual-audience documents: Every briefing has two sections:

1. Human-readable top: Clear, scannable, persuasive content for human readers
2. AI context bottom: Structured data, research findings, definitions, and source material that AI agents can draw on

This pattern is increasingly important as people use AI to read and summarize documents.

When to Use

• End of a research or exploration session
• After significant decisions or debates
• When creating proposals for team review
• When synthesizing multiple sources into a single artifact
• When documenting learnings for future reference

Invocation

/briefing — Assess session and recommend format /briefing proposal — Create a proposal document /briefing summary — Quick summary of session learnings /briefing research — Research synthesis document /briefing [custom] — Natural language guidance on format

Process

Step 1: Assess the Content

Before writing, understand:

• What was accomplished: Decisions, findings, builds, learnings
• Who will read this: Team, stakeholders, future-self, future-AI-agents
• What's the goal: Persuade, inform, document, propose, request decision
• What artifacts exist: Code, data, research, quotes, examples

Step 2: Determine Format

Choose format based on purpose (what you're trying to accomplish):

Inform & Update

| Format | Best For | Length | When to Use | | --------------------- | --------------------------------------- | ------------- | ---------------------------------------- | | Status Update | Regular progress reports | 200-400 words | Weekly/periodic updates to stakeholders | | Executive Summary | High-level overview for busy readers | 300-500 words | When execs need the gist without details | | Session Notes | Capturing learnings from a work session | 200-500 words | End of research/exploration sessions |

Propose & Decide

| Format | Best For | Length | When to Use | | -------------------------- | ------------------------------------- | --------------- | ---------------------------------------------------- | | Proposal | Pitching an idea, requesting approval | 800-2000 words | New initiatives, budget requests, strategy changes | | Decision Doc | Structured decision with options | 500-1500 words | When multiple stakeholders need to align on a choice | | One-Pager | Concise pitch or summary | 400-600 words | Quick executive read, meeting pre-read | | 6-Pager (Amazon-style) | Comprehensive narrative memo | 1500-2500 words | Major initiatives requiring deep thinking |

Technical & Engineering

| Format | Best For | Length | When to Use | | -------------------------------------- | ----------------------------------------- | --------------- | -------------------------------------------------- | | RFC / Design Doc | Technical proposals seeking feedback | 1000-3000 words | Architecture decisions, new systems, major changes | | Technical Briefing | Explaining implementation approach | 500-1500 words | Onboarding, handoffs, knowledge transfer | | ADR (Architecture Decision Record) | Documenting a specific technical decision | 300-600 words | Recording why a particular approach was chosen |

Learn & Reflect

| Format | Best For | Length | When to Use | | ------------------------------- | --------------------------------------- | -------------- | --------------------------------------------- | | Research Synthesis | Consolidating investigation findings | 500-1500 words | After research phase, before action | | Post-Mortem / Retrospective | Learning from incidents or projects | 500-1200 words | After incidents, project completion, failures | | Lessons Learned | Capturing insights for future reference | 300-800 words | End of project phase, after experiments |

If format isn't clear from invocation, present 2-3 relevant options:

"This could be a [format A] (if goal is X) or [format B] (if goal is Y). Which fits better?"

Step 3: Extract Core Elements

Identify before drafting:

1. The headline: What's the single most important thing?
2. The "so what": Why should the reader care?
3. The evidence: What supports the conclusions?
4. The ask (if any): What decision or action is needed?
5. The open questions: What's unresolved?

Step 4: Draft the Document

Follow the dual-audience structure:

# [Title]

## Summary

[2-4 sentences capturing the essence. A reader should understand the core message from this alone.]

---

## [Human-Readable Sections]

[Main content organized by format type - see Format Templates below]

---

## Additional Context (For AIs and Deep Dives)

This section documents the research, analysis, and reasoning that informed this briefing.
Useful for humans wanting to verify claims or AIs needing context for future work.

### [Structured subsections]

[Research findings, source material, definitions, detailed analysis, data dumps]

### Key Definitions

[Terms and concepts that might be ambiguous]

### Referenced Sources

[Links, citations, data sources]

Step 5: Write to File

Ask for location if not specified:

"Where should I save this? Default: docs/briefings/[date]-[slug].md"

File naming: YYYY-MM-DD-descriptive-slug.md

Format Templates

Status Update

# [Project/Work] Status Update — [Date/Week]

## TL;DR

[One sentence: What's the headline?]

---

## Progress This Period

- **Completed**: [What shipped or finished]
- **In Progress**: [What's actively being worked on]
- **Blocked**: [What's stuck and why]

## Key Metrics / Milestones

| Milestone     | Status                                | Notes        |
| ------------- | ------------------------------------- | ------------ |
| [Milestone 1] | ✅ Done / 🟡 In Progress / 🔴 Blocked | [Brief note] |

## Risks & Issues

[Any concerns stakeholders should know about]

## Next Period Focus

[What's planned next]

## Decisions Needed

[Any blockers requiring stakeholder input]

---

## Additional Context (For AIs)

[Detailed progress notes, links to artifacts, raw data]

Session Notes / Quick Summary

# [Topic] — Session Notes

## Key Takeaways

- [Most important point]
- [Second point]
- [Third point]

## What Happened

[Brief narrative, 2-3 paragraphs]

## Open Questions

- [Unresolved item 1]
- [Unresolved item 2]

## Next Steps

- [ ] [Action 1]
- [ ] [Action 2]

---

## Additional Context (For AIs)

[Session details, raw notes, source material]

One-Pager / Executive Summary

# [Title]

## The Headline

[One sentence capturing the essence]

## The Situation

[2-3 sentences on context/problem]

## The Proposal / Finding

[2-3 sentences on what you're recommending or what you found]

## Key Points

- [Point 1]
- [Point 2]
- [Point 3]

## The Ask

[What you need from the reader — decision, feedback, awareness]

---

## Additional Context (For AIs)

[Supporting details, data, sources]

Decision Doc

# Decision: [Question We're Answering]

## Summary

[What decision is needed and recommended option, 2-3 sentences]

---

## Background

[Context needed to understand the decision]

## Options Considered

### Option A: [Name]

- **Pros**: [Benefits]
- **Cons**: [Drawbacks]
- **Effort**: [High/Medium/Low]

### Option B: [Name]

- **Pros**: [Benefits]
- **Cons**: [Drawbacks]
- **Effort**: [High/Medium/Low]

### Option C: [Name] (if applicable)

- **Pros**: [Benefits]
- **Cons**: [Drawbacks]
- **Effort**: [High/Medium/Low]

## Recommendation

[Which option and why]

## Decision Roles (DACI)

- **Driver**: [Who's driving this to resolution]
- **Approver**: [Who makes the final call]
- **Contributors**: [Who has input]
- **Informed**: [Who needs to know]

## Decision Needed By

[Date/deadline]

---

## Additional Context (For AIs)

### Analysis Details

[Deeper comparison, data, research]

### Stakeholder Input

[Feedback received, concerns raised]

### References

[Related decisions, prior art]

Proposal

# [Proposal Title]

## Summary

[What we're proposing and why, in 2-4 sentences]

---

## The Proposal

[Detailed description of what's being proposed]

## Why This / Why Now

[Motivation, context, urgency]

## How It Works

[Implementation approach, phases, details]

## Bull Case / Bear Case

### Why This Could Work

[Arguments in favor, evidence]

### Why This Could Fail

[Risks, challenges, mitigations]

## Resource Requirements

[What's needed: time, people, money, tools]

## Decision Requested

[Specific ask: approve, reject, modify, discuss]

---

## Additional Context (For AIs and Deep Dives)

### Background Research

[Full research, analysis, data that informed proposal]

### Alternatives Considered

[What else was evaluated and why rejected]

### Key Definitions

[Terms that might be ambiguous]

### References

[Sources, prior art, related work]

RFC / Design Doc

# RFC: [Title]

**Status**: Draft | Under Review | Approved | Implemented
**Author(s)**: [Names]
**Reviewers**: [Names]
**Last Updated**: [Date]

## Summary

[2-4 sentence overview of the proposal]

---

## Background & Motivation

[Why is this change needed? What problem does it solve?]

## Goals

- [Goal 1]
- [Goal 2]

## Non-Goals

- [What this RFC explicitly does NOT address]

## Proposed Solution

### Overview

[High-level description]

### Detailed Design

[Technical specifics, architecture, interfaces]

### Alternatives Considered

[Other approaches evaluated and why rejected]

## Migration / Rollout Plan

[How to implement incrementally, rollback strategy]

## Risks & Open Questions

- [Risk 1]
- [Open question 1]

## Success Metrics

[How we'll know this worked]

---

## Additional Context (For AIs and Deep Dives)

### Technical Appendix

[Code examples, schemas, detailed specs]

### Research & Prior Art

[Related systems, papers, prior RFCs]

### Glossary

[Technical terms defined]

Post-Mortem / Retrospective

# Post-Mortem: [Incident/Project Name]

**Date**: [Date of incident/completion]
**Author**: [Name]
**Status**: Draft | Final

## Summary

[What happened in 2-3 sentences]

---

## Timeline

| Time   | Event           |
| ------ | --------------- |
| [Time] | [What happened] |
| [Time] | [What happened] |

## Impact

- **Duration**: [How long]
- **Affected**: [Who/what was impacted]
- **Severity**: [High/Medium/Low]

## Root Cause Analysis

[What actually caused this? Use "5 Whys" if helpful]

## What Went Well

- [Thing 1]
- [Thing 2]

## What Didn't Go Well

- [Thing 1]
- [Thing 2]

## Lessons Learned

- [Lesson 1]
- [Lesson 2]

## Action Items

| Action   | Owner  | Due Date | Status    |
| -------- | ------ | -------- | --------- |
| [Action] | [Name] | [Date]   | Open/Done |

---

## Additional Context (For AIs)

### Detailed Timeline

[Minute-by-minute if needed]

### Raw Data / Logs

[Supporting evidence]

### Related Incidents

[Links to similar past issues]

Research Synthesis

# [Topic]: Research Synthesis

## Summary

[2-4 sentence executive summary]

---

## Key Findings

### Finding 1: [Title]

[Evidence and analysis]

### Finding 2: [Title]

[Evidence and analysis]

## Implications

[What this means for decisions/actions]

## Confidence Assessment

| Finding     | Confidence      | Reasoning |
| ----------- | --------------- | --------- |
| [Finding 1] | High/Medium/Low | [Why]     |

## Open Questions

[What we still don't know]

---

## Additional Context (For AIs and Deep Dives)

### Research Methodology

[How findings were gathered]

### Detailed Findings

[Full analysis, data, quotes]

### Sources

[Links, citations]

ADR (Architecture Decision Record)

# ADR-[Number]: [Title]

**Status**: Proposed | Accepted | Deprecated | Superseded
**Date**: [Date]
**Decision Makers**: [Names]

## Context

[What is the issue that we're seeing that is motivating this decision?]

## Decision

[What is the change that we're proposing and/or doing?]

## Consequences

[What becomes easier or more difficult to do because of this change?]

---

## Additional Context (For AIs)

[Technical details, alternatives rejected, related ADRs]

Writing Principles

For Human Readers

• Lead with the headline: Most important thing first
• Make it scannable: Headers, bullets, tables
• Be direct: State conclusions, then support them
• Show, don't tell: Use examples, data, artifacts
• End with clarity: Clear ask or next step

For AI Consumers

The "Additional Context" section should:

• Be structured: Use consistent headers and formats
• Include raw data: Quotes, numbers, source material
• Define terms: Avoid ambiguity
• Cite sources: Links, references, attribution
• Preserve reasoning: How conclusions were reached

General Quality

• Honest: Acknowledge uncertainty, present counterarguments
• Concise: Say it once clearly, not three times vaguely
• Actionable: Reader knows what to do after reading
• Complete: All context needed to understand and act

Quality Checklist

Before delivering:

• [ ] Summary captures the essence in 2-4 sentences
• [ ] Human section is scannable and clear
• [ ] AI section has structured, consumable context
• [ ] Any ask or decision request is explicit
• [ ] Open questions are acknowledged
• [ ] File saved to appropriate location

Example: What We Just Did

The proposal document we created earlier (Time Delay Arbitrate - Asian news POC.md) follows this pattern:

• Human sections: Summary, Sprint Plan, Bull/Bear Case
• AI section: "Additional Context (For AIs and Deep Dives)" with research findings, definitions, sources
• Clear ask: Decision requested with resource requirements

This dual-audience structure makes the document useful both for team review and for future AI agents who need to understand the context.