Weekly Team Briefing Generator

## TL;DR

> Keep a folder of YOUR reference material and a queue of topics. Every Monday the
> LLM drafts a tight ~250-word briefing from the next topic — grounded only in your
> folder, with citations back to the source files. You review, fix a line, deliver.
> The blank page is gone; the expert (you) stays in charge.

## The problem this solves

If you run crews in construction, trades, or field services, you owe your people a regular safety talk — often legally. Office teams have the weekly huddle. Either way the pattern is the same: the talk matters, writing it is nobody's favourite job, and so it gets improvised badly or recycled until everyone tunes out.

This workflow keeps the talks relevant (Tuesday's near-miss becomes Monday's topic), grounded (drafts come only from your material, cited), and cheap (five minutes of review instead of forty-five of writing).

## The full picture

```
                          THE END-TO-END FLOW
═══════════════════════════════════════════════════════════════════════

 ┌─────────────────────┐      ┌─────────────────────┐
 │  KNOWLEDGE FOLDER   │      │     TOPIC QUEUE     │
 │  (yours, markdown)  │      │  topics.md — a list │
 │                     │      │                     │
 │ regs/ ─ OHS code    │      │ - ladder safety     │
 │ procedures/ ─ yours │      │ - Tue near-miss:    │
 │ incidents/ ─ learns │      │   pinch point       │
 │ equipment/ ─ manuals│      │ - winter startup    │
 └──────────┬──────────┘      └──────────┬──────────┘
            │                            │
            └──────────┬─────────────────┘
                       ▼  Monday 6 am (cron)
            ┌─────────────────────────┐
            │      LLM DRAFTER        │
            │ next topic + ONLY the   │
            │ relevant folder files   │
            │                         │
            │ → ~250-word talk        │
            │ → 3 discussion questions│
            │ → citations per point   │
            │ → watermarked DRAFT     │
            └────────────┬────────────┘
                         ▼
            ┌─────────────────────────┐       ┌──────────────────────┐
            │   HUMAN REVIEW (you)    │ ────▶ │  DELIVER + ARCHIVE   │
            │ read every word, edit,  │       │ talks/2026-06-15-    │
            │ approve — 5 minutes     │       │ ladder-safety.md     │
            │                         │       │ + date + attendance  │
            │ NOT optional. Ever.     │       │ = compliance record  │
            └─────────────────────────┘       └──────────────────────┘
═══════════════════════════════════════════════════════════════════════
```

## What you need

| Piece | What it does | Pick |
|---|---|---|
| Knowledge folder | The only thing drafts may be built from | Plain markdown files in folders — the folder structure IS the database |
| Topic queue | What's next, and why it's relevant | One `topics.md` file you append to from your phone |
| LLM | Drafts from your material, cites sources | Claude (Sonnet tier for grounded drafting) |
| Scheduler | Runs it every Monday | cron, Make/n8n, or just a saved prompt you trigger |
| Archive | Proof you delivered | A `talks/` folder with date + attendance |

## Phase 1 — The knowledge folder (do this once, well)

```
 briefing-kb/
 ├── regs/
 │   ├── ab-ohs-part9-fall-protection.md   ← your province's actual rules
 │   └── ab-ohs-part12-ladders.md            (paraphrase Crown regs freely;
 ├── procedures/                              NEVER paste licensed standards
 │   ├── our-ladder-inspection.md             like CSA — reference by clause
 │   └── our-lockout-procedure.md             number only)
 ├── incidents/
 │   └── 2026-06-09-pinch-point-nearmiss.md ← Tuesday's lesson, anonymized
 └── equipment/
     └── genie-lift-quickref.md
```

The rule that makes this trustworthy: **the AI drafts only from what's in the folder, and cites which file each point came from.** An ungrounded LLM will happily invent plausible-sounding regulations. Grounding plus citation makes every error visible at review.

## Phase 2 — The topic queue

```
 topics.md
 ─────────────────────────────────────────────
 - [ ] pinch points              ← from Tuesday's near-miss (incidents/2026-06-09…)
 - [ ] ladder inspection         ← seasonal, roof work starting
 - [ ] heat stress               ← forecast says 30°+
 - [x] lockout refresher         ← delivered 2026-06-08
```

Append topics the moment they occur to you — from the truck, from a near-miss report, from a customer site. The near-miss-to-Monday-talk pipeline is when briefings stop being noise and start being listened to.

## Phase 3 — The drafter

**The prompt (copy, fill, schedule):**

> You are drafting a {{length:250}}-word briefing for {{audience: a residential
> construction crew}} on the topic: {{topic}}.
>
> Use ONLY the attached reference files. If the files don't cover something, say
> "ASK: …" instead of filling the gap yourself.
>
> Structure:
> 1. Why this matters on OUR sites this week (2 sentences — use the incident file
>    if one is attached).
> 2. The 3 things to actually do, in plain crew language. Short sentences. No jargon.
> 3. Three discussion questions that make someone answer from their own experience.
>
> After every point, cite the source file in brackets, like [regs/ab-ohs-part12].
> Quote regulations in 15 words or less. Reference CSA or other licensed standards
> by clause number only — never reproduce their text.
>
> Header: topic, date, "DRAFT — FOR REVIEW BY {{reviewer_name}}".
>
> REFERENCE FILES:
> {{relevant files from briefing-kb/}}

**What a good draft looks like:**

```
 ┌─────────────────────────────────────────────────────────────┐
 │ TOOLBOX TALK — Pinch Points          2026-06-15             │
 │ DRAFT — FOR REVIEW BY KAMAL                                 │
 ├─────────────────────────────────────────────────────────────┤
 │ Why this matters this week: On Tuesday one of our crew      │
 │ nearly lost a fingertip resetting the lift gate. It took    │
 │ two seconds and nobody was being careless.                  │
 │ [incidents/2026-06-09-pinch-point-nearmiss]                 │
 │                                                             │
 │ Three things to do:                                         │
 │ 1. Gloves on before the gate moves — not after. [proce…]   │
 │ 2. One hand on the control, one hand visible. [equipment…] │
 │ 3. Call "hands clear" before anyone activates. [proce…]    │
 │                                                             │
 │ Talk about it:                                              │
 │ • Where's the worst pinch point on our current site?        │
 │ • What made Tuesday's near-miss so easy to walk into?       │
 │ • What would you tell a first-week apprentice about gates?  │
 └─────────────────────────────────────────────────────────────┘
```

## Phase 4 — Review, deliver, archive

```
  DRAFT lands (Monday 6 am)
       │
       ▼
  YOU read every word ── fix what's off ── this gate is the whole system's
       │                                   integrity. The AI assists; the
       ▼                                   qualified human signs.
  DELIVER at the huddle
       │
       ▼
  ARCHIVE: talks/2026-06-15-pinch-points.md
           + who attended
       │
       ▼
  in regulated trades this archive IS your
  compliance record when the auditor asks
```

## Folder structure (the whole system)

```
 briefing-generator/
 ├── CLAUDE.md            ← the AI-builder brief (ships in this kit)
 ├── briefing-kb/         ← the knowledge folder (Phase 1)
 │   ├── regs/  procedures/  incidents/  equipment/
 ├── topics.md            ← the queue (Phase 2)
 ├── talks/               ← dated, delivered archive (Phase 4)
 ├── prompts/
 │   └── drafter.md       ← the prompt, versioned
 └── scripts/
     └── monday.ts        ← pick next topic → gather files → draft → notify you
```

## Hard rules learned in production

- **Every output is watermarked DRAFT** and reviewed by the qualified human before it reaches a worker. The AI assists; it never substitutes.
- **Ground every draft in your own sources** with per-point citations. Reject any draft with an uncited claim.
- **Quote regulations ≤ 15 words with citation; never reproduce licensed standards** (CSA and similar) — clause numbers only.
- **~250 words.** A toolbox talk is five minutes. Longer drafts get skimmed, not delivered.
- Anonymize incident files — lessons, not blame.

## Numbers to watch

| Metric | Healthy | Where it comes from |
|---|---|---|
| Prep time per briefing | ~5 min (was 30–45) | your watch |
| Drafts needing major rewrite | < 1 in 5 after week 3 | your review notes |
| Topics from real events | ≥ 1 in 3 | topics.md sources |
| Archive completeness | 100% — every delivered talk filed | talks/ folder |

## Week-one checklist

- [ ] Knowledge folder has ≥ 8 real files across regs/procedures/incidents
- [ ] Monday run produces a draft with a citation on every point
- [ ] Plant a fake fact gap (topic the folder doesn't cover) — draft says "ASK:" instead of inventing
- [ ] Draft quotes a regulation — 15 words or less, cited
- [ ] Draft references a CSA-type standard — clause number only, no text
- [ ] Your review takes under 10 minutes and improves the draft (it should — you're the expert)
- [ ] Delivered talk lands in talks/ with date + attendance

## Troubleshooting

- **Drafts feel generic:** the folder is thin on YOUR procedures and incidents. The magic is your material, not the model.
- **Citations don't check out:** tighten the prompt to require file names per point, and reject any draft with an uncited claim. Spot-check weekly.
- **Crew tunes out:** stop running evergreen topics back-to-back. Alternate: one from a recent event, one seasonal, one refresher.
- **The "ASK:" lines pile up:** good — that's your list of missing knowledge-base files. Write one per week.
- **Talks run long:** enforce the word count in the prompt and cut the warm-up sentences; crews respect brevity.

# INSTALL.md — One-Shot Build · Weekly Team Briefing Generator (SBW-006)

You don't need to know how to code. You need three things:

1. **Claude Code** installed (`npm install -g @anthropic-ai/claude-code`)
2. Some of **your own material**: the rules for your trade, your procedures,
   notes on things that almost went wrong (don't worry about format — rough is fine)
3. This kit, unzipped into an empty folder

## The one-shot

Open a terminal in the kit folder, run `claude`, and paste this entire block:

```
Read every file in this folder: CLAUDE.md, WORKFLOW.md, SKILLS.md, WALKTHROUGH.md.
They are the complete spec for a weekly team-briefing generator. CLAUDE.md is your
standing brief; its hard rules (drafts ONLY from the knowledge folder with per-point
citations, "ASK:" instead of invention, DRAFT watermark, never reproduce licensed
standards, the human review gate is unskippable) and definition-of-done are binding.

Then build it for me, one-shot, with these ground rules:

1. Ask me ONLY these setup questions, all at once, then stop asking:
   - Business name, trade, and who the briefings are for (crew/office/both)
   - My province or jurisdiction (for which regs apply)
   - Briefing day and time (default Monday 6 am) and where the draft should land
     (email / text / file)
   - Who reviews drafts (probably me — name for the watermark)

2. Build the briefing-kb/ folder structure from CLAUDE.md, then INTERVIEW ME to
   seed it: ask about my procedures, recent near-misses, and main equipment,
   one topic at a time, and write each answer up as a proper kb file yourself.
   Get me to 8–10 real files before any automation.

3. Generate the first draft manually with me watching, tune the prompt from my
   edits, THEN set up the scheduled run with the mechanical validator
   (citations per point, word count, DRAFT header).

4. When you need anything from a dashboard or my files, give me a numbered
   click-path and wait. Never ask me to write the config myself.

5. Don't call it done until CLAUDE.md's definition-of-done is fully checked,
   including the fake-gap test where a topic the folder doesn't cover produces
   "ASK:" lines instead of invented facts.
```

## What you'll be doing while it builds

```
 YOU                                  CLAUDE CODE
 ───                                  ───────────
 answer 4 questions          ──▶      builds the folder structure
 talk about your shop        ──▶      writes your knowledge files FOR you
 (the interview — 30–45 min)          (this is the gold)
 read the first draft        ──▶      tunes the prompt to your voice
 deliver Monday's talk       ──▶      archives it, queue rolls forward
```

Total hands-on time: about an hour, most of it talking about work you know cold.

## If something goes sideways

Paste the error back into Claude Code and say "fix this, re-read CLAUDE.md
first." When drafts say "ASK: …", that's the system telling you which knowledge
file to add next — have Claude interview you for it, same as setup.

# CLAUDE.md — Weekly Team Briefing Generator (SBW-006)

Drop this file in the root of your build folder. It is the standing brief for any AI assistant
(Claude Code or similar) working on this project. Read WORKFLOW.md for the full spec.

## Mission

Every Monday, draft a ~250-word team briefing from the next queued topic, grounded ONLY
in the local knowledge folder, cited per point, watermarked DRAFT. The qualified human
reviews every word before it reaches a worker. Assist, never substitute.

## Architecture guts

```
 briefing-kb/ (markdown folders = the database)     topics.md (the queue)
        │                                                │
        └────────────┬───────────────────────────────────┘
                     ▼  scripts/monday.ts (cron)
        pick next unchecked topic ──▶ gather relevant kb files (folder match
        + filename keywords — simple beats clever) ──▶ LLM draft (prompts/drafter.md)
                     │
                     ▼
        validate: every point cited? word count ok? "DRAFT" header present?
        any uncited claim → reject + retry once → else flag for human
                     │
                     ▼
        notify reviewer ──▶ human edits/approves ──▶ talks/YYYY-MM-DD-topic.md
                                                      + check off in topics.md
```

- **Folders are the state; filenames are the index.** No database, no embeddings to
  start — relevance = same-folder + filename keyword match. Upgrade to retrieval only
  if the kb outgrows ~100 files.
- The validator is mechanical, not LLM: regex for citations per point, word count,
  DRAFT header. Cheap checks that catch expensive failures.

## The three questions

| Component | 1. Where does state live? | 2. Where does feedback live? | 3. What breaks if I delete it? |
|---|---|---|---|
| `briefing-kb/` | the markdown files — the only source of truth | "ASK:" gaps = missing-file backlog | drafts ground on nothing → hallucination |
| `topics.md` | one file, checkboxes | topic-source mix (real events vs evergreen) | scheduler has nothing relevant to draft |
| `prompts/drafter.md` | git — versioned like code | rewrite-rate per draft | grounding rules + citation discipline vanish |
| validator | scripts; rules are code | rejected-draft log | uncited claims reach the reviewer unmarked |
| `talks/` archive | dated files + attendance | audit/compliance requests answered instantly | no proof of delivery when it matters |
| human review gate | the reviewer's calendar | their edits = prompt-tuning signal | the system loses its license to operate |

## Hard rules

- Drafts use ONLY briefing-kb/ content. Gaps produce "ASK:" lines, never invention.
- Every point carries a [file] citation. Uncited claim = rejected draft.
- Regulations quoted ≤ 15 words with citation. Licensed standards (CSA etc.):
  clause numbers only, NEVER reproduced text.
- Every output watermarked "DRAFT — FOR REVIEW BY {{reviewer}}". The human gate is
  not configurable and not skippable.
- Incident files are anonymized: lessons, not blame, no names.
- ~250 words. The word count is a feature, not a constraint to relax.
- No client/employer proprietary content in the kb — reference by name/number only.

## Folder structure

```
 briefing-generator/
 ├── CLAUDE.md            ← you are here
 ├── briefing-kb/         ← regs/ procedures/ incidents/ equipment/ — the database
 ├── topics.md            ← the queue
 ├── talks/               ← delivered archive: YYYY-MM-DD-topic.md + attendance
 ├── prompts/drafter.md   ← versioned like code
 └── scripts/monday.ts    ← cron entry: pick → gather → draft → validate → notify
```

## Definition of done

- [ ] Monday run: queued topic → cited draft in reviewer's hands by 7 am
- [ ] Topic with no kb coverage → "ASK:" lines, zero invented facts
- [ ] Validator rejects a draft with an uncited point (test by prompt-sabotage)
- [ ] Regulation quote ≤ 15 words; CSA reference is clause-number-only
- [ ] Approved talk archived with date + attendance; topic checked off
- [ ] Reviewer's weekly time ≤ 10 minutes

# SKILLS.md — Weekly Team Briefing Generator (SBW-006)

What you (or whoever builds this) need to know, and which skills to load into your AI
assistant before starting.

## Skill map

```
                     ┌──────────────────────────┐
                     │ SBW-006 BRIEFING GENERATOR│
                     └──────────┬───────────────┘
        ┌──────────────┬───────┴────────┬─────────────────┐
        ▼              ▼                ▼                 ▼
 ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌───────────────┐
 │ knowledge   │ │ grounded LLM │ │ scheduling  │ │ domain rules  │
 │ folder      │ │ drafting +   │ │ (cron/n8n)  │ │ (what you may │
 │ curation    │ │ citations    │ │  REQUIRED   │ │ NOT reproduce)│
 │  REQUIRED   │ │  REQUIRED    │ └─────────────┘ │   REQUIRED    │
 └─────────────┘ └──────────────┘                 └───────────────┘
```

## Required skills

| Skill | Why this build needs it | If you're using Claude Code |
|---|---|---|
| **Knowledge-base curation** | Folders-as-database: one file per topic, filenames as the index. The drafts are only as good as this folder. | The persistent-wiki pattern: index file, one page per concept, cross-references. |
| **Grounded LLM drafting** | "Use ONLY the attached files, cite per point, say ASK when missing" — the discipline that separates this from a hallucination machine. | The `claude-api` skill for prompt structure and model choice. |
| **Scheduled automation** | The Monday cron that picks the topic and gathers files. | Any cron/n8n/Make familiarity; this is the easy part. |
| **Your domain's reproduction rules** | In safety work: Crown regs quotable, CSA standards never. Your field has its own version. | No skill replaces knowing what you're licensed to reproduce. |

## Suggested (not required)

| Skill | What it adds |
|---|---|
| **Document export** | Markdown → PDF or slides for crews that want paper at the huddle. |
| **Mechanical validation** | Regex checks for citations/word count/DRAFT header — cheap insurance, write once. |

## Workflows that pair with this one

```
   field events (near-misses, customer feedback, equipment issues)
        │
        ▼ append from your phone
   topics.md ──▶ SBW-006 BRIEFING GENERATOR
                       │
                       └── the archive pattern (dated files + attendance)
                           is the same compliance-record discipline as
                           SBW-004's audit log — different domain, same idea
```

- This kit stands alone, but its *pattern* — knowledge folder + queue + grounded
  drafting + human gate + dated archive — generalizes to newsletters, client updates,
  training modules, anything recurring and written.

## Build order recommendation

1. The knowledge folder, by hand, 8–10 real files. (The unglamorous 80%.)
2. The prompt, run manually for two Mondays — tune before automating.
3. The cron + validator.
4. The archive habit. Attendance noted, every time.

# WALKTHROUGH.md — Weekly Team Briefing Generator (SBW-006)

The build, step by step, in plain words. Each step tells you **what to do**,
**how long it takes**, and **how you know it worked**.

## Your board

```
 ┌─ TO DO ─────────┐  ┌─ BUILDING ──────┐  ┌─ TESTING ───────┐  ┌─ SHIPPED ───────┐
 │ 1 the folder    │  │                 │  │                 │  │                 │
 │ 2 topic queue   │  │  cards move     │  │  cards move     │  │  cards move     │
 │ 3 first draft   │  │  this way ──▶   │  │  this way ──▶   │  │  this way ──▶   │
 │ 4 monday robot  │  │                 │  │                 │  │                 │
 │ 5 the archive   │  │                 │  │                 │  │                 │
 └─────────────────┘  └─────────────────┘  └─────────────────┘  └─────────────────┘
```

## How the pieces hold hands

```
     ┌─────────────┐         ┌─────────────┐
     │  knowledge  │         │   topic     │
     │   folder    │         │   queue     │
     │ (your stuff)│         │ (what's next)│
     └──────┬──────┘         └──────┬──────┘
            │     Monday 6 am      │
            └─────────┬────────────┘
                      ▼
               ┌─────────────┐
               │  AI drafter │
               │ (reads YOUR │
               │ files only, │
               │ cites them) │
               └──────┬──────┘
                      ▼
               ┌─────────────┐
               │  YOU review │  ← the boss gate. always.
               │  (5 minutes)│
               └──────┬──────┘
                      ▼
               ┌─────────────┐
               │ deliver at  │
               │ the huddle, │
               │ file a copy │
               └─────────────┘
```

---

## Step 1 — Build the folder (one rainy Saturday)

This is the unglamorous step that makes everything else work.

**Do this:** Make four folders and fill them with 8–10 short markdown files of
YOUR material:

```
   briefing-kb/
   ├── regs/         ← the actual rules for your province/industry
   ├── procedures/   ← how YOUR shop does things
   ├── incidents/    ← lessons from things that almost went wrong (no names)
   └── equipment/    ← quick-refs for the gear you actually run
```

One topic per file. Plain words. If you only have time for one folder, do
`incidents/` — it's where the gold is.

**You know it worked when:** a new hire could read three files and learn
something true about your shop.

## Step 2 — Start the queue (10 minutes, then forever)

**Do this:** Make one file, `topics.md`. Add five topics now. From then on,
add one any time something happens — from your phone, in the truck:

```
   - [ ] pinch points        ← Tuesday's near-miss
   - [ ] ladder checks       ← roof season starting
   - [ ] heat stress         ← hot week coming
```

**You know it worked when:** Tuesday's near-miss is in the queue by Tuesday night.

## Step 3 — The first draft, by hand (one hour)

Before any automation, run the prompt manually so you can feel the quality.

**Do this:** Copy the drafter prompt from WORKFLOW.md. Attach the 2–3 relevant
files from your folder. Run it. Read what comes back:

```
   ✓ does every point cite one of YOUR files?
   ✓ is it ~250 words — five spoken minutes?
   ✓ would your crew actually listen to this?
   ✗ anything invented that's not in your files? → tighten the prompt
```

**You know it worked when:** you fix two sentences instead of rewriting the page.

## Step 4 — The Monday robot (half a day)

**Do this:** A small scheduled script (cron, Make, or n8n) that every Monday at
6 am: takes the top unchecked topic, grabs the matching files, runs the prompt,
and sends the draft to you (email, text, whatever you read at 6:30).

Add the dumb-but-mighty checks before it sends: citations on every point?
under 300 words? "DRAFT" in the header? If not — it retries once, then flags it.

**You know it worked when:** Monday coffee comes with a draft you didn't write.

## Step 5 — The archive habit (5 minutes a week)

**Do this:** After you deliver the talk, drop the final version in `talks/` with
the date and who was there:

```
   talks/2026-06-15-pinch-points.md
   attended: Dave, Maria, J.T., the new guy (Sam)
```

**You know it worked when:** someone official asks "show me your safety meetings
for June" and you answer in thirty seconds.

---

## After it ships — the loop that feeds itself

```
        something happens on site
                  │
                  ▼
        you add a topic from your phone     (10 seconds)
                  │
                  ▼
        Monday: draft appears               (0 minutes of yours)
                  │
                  ▼
        you review and deliver              (5 + 5 minutes)
                  │
                  ▼
        crew hears about THIS week's        (priceless — this is
        real risk, not a recycled talk       when they start listening)
```

The "ASK:" lines in drafts are your homework: each one is a file your folder is
missing. Write one a week and the system gets smarter than your binder ever was.