HBM — Hierarchical Briefing Model (v0.1)

┌─────────────────────────────────────────────────────────────────┐
│                        DATA LAYER                               │
│  Event Graph — clean ingestion from all sources (real-time)    │
│  Entities: events, people, locations, materials, states        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ (22:00 UTC nightly trigger)
┌─────────────────────────────────────────────────────────────────┐
│                    COGNITION LAYER                              │
│  Briefing Agent — generates cognitive artifacts from Event Graph│
│  Month/Week: pattern aggregation (no Agent needed)             │
│  Day/Hour: When/Then chains, forgetting budget, scripts         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    PRESENTATION LAYER                           │
│  HTMX templates: month_grid.html, week_deck.html,              │
│  day_chain.html, hour_detail.html                               │
└─────────────────────────────────────────────────────────────────┘

Event:
  id: uuid
  source: calendar|email|sms|voice|manual
  title: string                    # raw extracted title
  start_time: ISO8601
  end_time: ISO8601 | null
  participants:
    - person_id: uuid
      role: primary|secondary|optional
      confirmed: bool
  location:
    name: string
    address: string | null
    lat: float | null
    lon: float | null
  materials: [string]              # things to bring
  prep_tasks: [Task]              # things to do before
  states:                          # dynamic, updated in real-time
    permission_slip: pending|signed|n/a
    lunch_required: bool
    car_seat_needed: bool
  penalty_score: 1-10              # forgetting cost (auto-calculated)
  anchor_weight: 1-10              # structural importance to day

Task:
  id: uuid
  description: string
  trigger_event_id: uuid | null    # if chained
  trigger_type: absolute_time | event_start | event_end | state_change
  due_time: ISO8601 | null
  completed: bool
  delegated_to: person_id | null

MonthBrief:
  month: YYYY-MM
  days:
    - date: YYYY-MM-DD
      commitment_count: int
      anchor_present: bool
      pattern_density: light|medium|heavy|redline
      has_conflict: bool
      family_states_touched: [FamilyState]  # which transition windows hit

WeekBrief:
  week_start: YYYY-MM-DD
  days:
    - date: YYYY-MM-DD
      anchor_event: EventSummary | null   # the structural anchor
      commitment_count: int
      pattern_density: light|medium|heavy|redline
      conflict_count: int
      high_penalty_tasks: [TaskSummary]   # top 3 by penalty_score

EventSummary:
  id: uuid
  title: string
  time_range: "08:15 – 14:30"
  location: string
  participants: [string]  # first names only

DayBrief:
  date: YYYY-MM-DD
  generated_at: ISO8601
  family_state: FamilyState            # which window this day sits in

  anchor_event: EventSummary | null    # the structural anchor

  forgetting_budget:
    active_commitments: int             # events + uncompleted prep_tasks
    budget_threshold: int = 8          # configurable per household
    status: green|yellow|redline
    warning: string | null              # shown if redline

  when_then_chains: [WhenThenChain]    # the implementation intentions

  high_penalty_alerts: [Alert]         # surfaced first, top of brief

  ambient_gist: string                 # 10-word summary for evening glance

FamilyState:
  name: launch_phase|deep_work|the_pivot|wind_down
  window_start: HH:MM
  window_end: HH:MM
  cognitive_priority: high_penalty|ambient_gist|high_coordination|encoding

WhenThenChain:
  id: uuid
  sequence: int                        # order in chain
  trigger:
    type: state_change | time | event_start | event_end
    description: string                  # "When coffee is done..."
    state_check: string | null         # "check if permission_slip == signed"
  action:
    description: string                # "...then check lunchbox is in backpack"
    material_check: [string] | null     # ["lunchbox", "backpack"]
    location_hint: string | null
  fallback:
    description: string | null          # if trigger fires but state wrong
    escalation: person_id | null        # who to notify

Alert:
  id: uuid
  severity: high|medium|low
  title: string
  action_script: WhenThenChain         # full script to resolve
  location_hint: string | null
  material_check: [string] | null

HourDetail:
  event_id: uuid
  generated_at: ISO8601

  full_action_script:
    target: string                      # what we're doing
    action_steps: [string]              # step-by-step
    materials: [string]               # what to bring
    fallback_plan: string | null        # if primary fails
    expected_duration: int              # minutes
    parking_hint: string | null
    checkin_procedure: string | null    # "sign in at front desk"
    contact_on_site: string | null

  dependencies:
    must_complete_before: [Task]        # from Event.prep_tasks
    blocked_by: [uuid] | null           # other events this depends on

  coordination_notes:
    who_picks_up: person_id | null
    who_drops_off: person_id | null
    carpool_optimization: [person_id] | null

1. Identify FamilyState for target date (from time-of-day + day-of-week patterns)
2. Find anchor_event (highest anchor_weight, or first high-penalty event)
3. Calculate forgetting_budget (active_commitments vs threshold)
4. Build when_then_chains:
   - Start from anchor_event, work backward
   - For each prep_task, create chain linking to previous state
   - Add material_check hints where spatial memory helps
   - Add fallback for each high-penalty item
5. Generate high_penalty_alerts (anything with penalty_score >= 7)
6. Draft ambient_gist (10 words, evening-glance optimized)
7. Pre-generate HourDetails for all anchor_event + high_penalty events

You are the Briefing Agent. Generate a DayBrief for {date} based on the Event Graph below.

CONTEXT:
- FamilyState for this date: {family_state}
- Anchor event: {anchor_event}
- Active commitments: {count}
- Budget threshold: 8
- Current states: {event_states}

EVENT GRAPH (next 36h):
{events_json}

OUTPUT:
Generate a DayBrief with:
1. forgetting_budget calculation
2. when_then_chains (minimum 3, maximum 6 chains)
3. high_penalty_alerts (include action_script for each)
4. ambient_gist (exactly 10 words)

Format: YAML matching HBM spec.

GET /family/brief/month/{YYYY-MM}
GET /family/brief/week/{YYYY-MM-DD}     # week start date
GET /family/brief/day/{YYYY-MM-DD}
GET /family/brief/hour/{event_id}
POST /family/brief/regenerate/{YYYY-MM-DD}  # manual trigger (admin only)