Document Discussion

Capture team discussions with participants, decisions, and action items.

Prerequisites

Verify Discussions entity is enabled:

• Check for .claude/data/discussions/schema.yaml

• If not found, suggest enabling discussions via secondbrain-init

Workflow

Step 1: Gather Information

Collect from user or conversation context:

• Participant(s) — Who was in the discussion

• Topic — Main subject discussed

• Source — manual, meeting, slack

• Key Points — Discussion content

• Decisions — What was decided

• Action Items — Follow-up tasks

Step 2: Generate Discussion File

Filename format: docs/discussions/YYYY-MM-DD-<participant>-<topic-slug>.md

Example: docs/discussions/2026-01-15-sergey-kubernetes-migration.md

Step 3: Create Discussion Document

date: 2026-01-15 participants:

• Sergey Bershadsky
• Kate Angelopoulos topic: Kubernetes Migration Planning status: documented source: meeting tags: [kubernetes, infrastructure, planning]

Kubernetes Migration Planning

Date: 2026-01-15 Participants: Sergey Bershadsky, Kate Angelopoulos

Context

Why did this discussion happen?

Discussion Points

Migration Timeline

Discussion:

• Discussed phased approach
• Agreed on staging first

Outcome: Start with staging environment by end of Q1

Resource Requirements

Discussion:

• Node sizing
• Cost implications

Outcome: Will use 3 node cluster initially

Decisions Made

Action Items

• Create staging environment — @sergey
• Write migration runbook — @kate
• Schedule follow-up review — @sergey

Open Questions

• What's the rollback strategy?
• How do we handle stateful services?

Follow-up

• Next discussion scheduled for: 2026-01-22
• Related topics to explore: CI/CD pipeline changes

Step 4: Update Records

Add to monthly file .claude/data/discussions/YYYY-MM.yaml :

• date: 2026-01-15 member: sergey topic: Kubernetes Migration Planning file: docs/discussions/2026-01-15-sergey-kubernetes-migration.md source: meeting participants:
  • Sergey Bershadsky
  • Kate Angelopoulos

Step 5: Sidebar Note

DO NOT manually add discussions to VitePress sidebar.

Discussions are automatically listed via the EntityTable component on docs/discussions/index.md , which reads from monthly .claude/data/discussions/YYYY-MM.yaml files. No sidebar modification needed.

Step 6: Confirm Creation

Discussion Documented

Date: 2026-01-15 Topic: Kubernetes Migration Planning Participants: Sergey Bershadsky, Kate Angelopoulos Source: meeting File: docs/discussions/2026-01-15-sergey-kubernetes-migration.md

Summary

• 2 decisions recorded
• 3 action items created
• 2 open questions noted

Next Steps

• Follow up on action items
• Address open questions in next discussion

Monthly Partitioning

Discussions are partitioned by month:

• discussions/2025-12.yaml — December 2025

• discussions/2026-01.yaml — January 2026

Past months become immutable, preserving history.

Sources

Source Description

manual Hand-documented discussion

meeting From a scheduled meeting

slack From Slack conversation

Tips

• Capture decisions explicitly — Use the table format

• Create action items — Every decision should have an owner

• Note open questions — Track what needs follow-up

• Link to related content — Reference ADRs, notes, etc.

• Document context — Future readers need to understand "why"