/brief

You are creating a context preservation document from the current conversation.

Purpose

Extract key information from this discussion and create an organized markdown file that allows a future Claude Code session to understand what was discussed and start building without needing the original conversation context.

Command Usage

/brief [optional-slug-name]

If no slug provided, suggest one based on conversation topic.

Process

1. Analyze the current conversation

   • Extract what is being built/improved/explored
   • Identify key decisions made
   • Capture technical details discussed
   • Note trade-offs and alternatives considered
   • Preserve code examples and configurations
   • Record open questions and uncertainties

2. Determine scope

   • Is this a big/future idea? → Suggest GitHub issue
   • Is this immediate next work? → Skip GitHub issue
   • Indicators for issue: "explore later", "future feature", multi-phase, needs stakeholder input
   • Indicators to skip: "build now", simple task, clear next step

3. Ask user

   What should I call this brief?
   Suggestion: brief-[your-suggestion].md
   
   Create GitHub issue? [Yes/No based on scope]
   

4. Generate file: /docs/brief-[slug].md

File Structure Guidance

ALWAYS INCLUDE:

• What We're Building: Thorough description (not just 1 sentence)
• Why: Problem, opportunity, business context
• Key Decisions: Tech choices with reasoning, alternatives rejected, trade-offs
• Next Actions: Concrete first steps

INCLUDE IF DISCUSSED (adapt sections to conversation):

• Features: Detailed - how they work, edge cases, user flows
• Technical Approach: Architecture, patterns, component design
• Database/Data Model: Schema, relationships, indexes discussed
• API Design: Endpoints, request/response formats, auth
• UI/UX: Interface decisions, layouts, user experience preferences
• Dependencies: Packages with reasoning why chosen
• Security: Auth strategy, permissions, privacy considerations
• Out of Scope: What we explicitly decided NOT to do (with reasoning)
• Open Questions: Unresolved decisions with context
• Code Examples: Preserve snippets from conversation
• References: Links, docs, examples shared
• Conversation Highlights: Key exchanges, debates, "aha moments"

CONTEXT AWARENESS:

• Assume existing project/repo unless stated otherwise
• Preserve why not just what
• Include alternatives considered and why rejected
• Capture uncertainties honestly (don't invent decisions)
• Use actual details from conversation (not placeholder examples)

STYLE:

• Organized with markdown headings
• Detailed enough for future Claude to build without questions
• Use code blocks for examples
• Scannable but comprehensive
• Don't force sections that weren't discussed
• Length doesn't matter - capture everything relevant

File Header Format

# Brief: [Name]

**Created**: [YYYY-MM-DD]
**Type**: [Feature | Exploration | Improvement | Task | Bug]
**Status**: Planning
**Effort**: [Small (<4h) | Medium (4-16h) | Large (>16h) | Unknown]

[GitHub Issue: #[number]] (if created)

---

[Rest of content organized by sections that fit the conversation]

GitHub Issue Creation

If creating issue:

Title: Same as brief title

Body (concise version):

Brief: `/docs/brief-[slug].md`

## Summary
[2-3 sentences]

## Key Points
- [Bullet 1]
- [Bullet 2]

## Next Steps
1. [Action 1]
2. [Action 2]

Labels: Ask user or suggest based on type Milestone: Ask if relevant to conversation

Output

After creating file (and optional issue):

Created `/docs/brief-[slug].md` ([X] lines)

[If issue created:]
GitHub Issue: #[number] - [title]
Labels: [labels]

**Next**: You can start a fresh session and reference this brief to begin building.

Important

• Extract from ACTUAL conversation, don't invent details
• Preserve user's language and specific requirements
• Capture the "why" behind decisions
• Don't oversimplify - future Claude needs full context
• Sections should emerge from discussion, not forced template