update-audience-notes

name

update-audience-notes

description

Appends one structured YAML observation block to substacker shared-context/audience-notes.md iff the week produced at least one observation with confidence ≥ medium. Includes supporting evidence (post slugs + numbers) and reviewed_by_curator flag. Never rewrites or deletes prior entries. Append-only discipline protects downstream agents' shared context. Use at the end of each weekly pipeline after write-weekly-report. Trigger keywords — audience notes, append observation, audience insight, confidence-rated.

Update Audience Notes

Workflow

At end of weekly pipeline:
- [ ] Step 1: Review attribution outputs for any pattern observed
- [ ] Step 2: Filter to confidence ≥ medium only (low is never appended)
- [ ] Step 3: Format as YAML block per schema
- [ ] Step 4: Append to shared-context/audience-notes.md
- [ ] Step 5: If no medium+ observation this week, log "no additions this week" to weekly report's data-caveats (not to audience-notes)

YAML block schema

- date: YYYY-MM-DD
  week: YYYY-WW
  observation: >
    {plain English, ideally testable}
  confidence: medium | high
  evidence:
    - slug: {post-slug}
      metric: {value}
      baseline: {value}
  reviewed_by_curator: false

Example entries

- date: 2026-06-01
  week: 2026-W22
  observation: >
    External restack from a larger ML account on Substack Notes is
    the strongest sub-acquisition channel observed to date —
    +49 subs from a single post vs ~+4 baseline, with 71% of the
    new cohort landing in "active" tier immediately.
  confidence: high
  evidence:
    - slug: why-your-embedding-search-melted-at-10pm
      open_rate: 0.61
      click_rate: 0.12
      baseline_open: 0.49
      baseline_click: 0.05
      new_subs: 49
      active_tier_of_new_subs: 35
      external_restacks_observed: 2
  reviewed_by_curator: false

Guardrails

1. Append-only. Never rewrite or delete prior entries. Entries stand.
2. Confidence floor: medium. Low-confidence observations stay in the weekly report body; never enter shared context.
3. Evidence required. Every observation cites at least 2 posts (or 1 post + 1 external datum) with specific numbers.
4. reviewed_by_curator: false on append; Curator flips to true on its next monthly review.
5. Never append an observation identical to a prior entry. Dedupe by the observation field's content.
6. If >2 medium+ observations in one week, append all of them as separate blocks.
7. Individual subscriber info (email, name) never in evidence — aggregate counts only.

Quick reference

• Append-only writes.
• Confidence floor: medium.
• Evidence: ≥2 posts / data points with numbers.
• Fires once per week at pipeline end; may write 0, 1, or 2+ blocks.