| name | weekly-org-summary |
| description | Produce the weekly Open Austin org summary, broken out per team into separate Slack channels, from a fresh snapshot. Use when the user asks for a 'weekly summary', 'weekly update', 'org digest', or 'what's going on this week'. |
Weekly Org Summary
This is the Open Austin org repo's own weekly summary process. It supersedes the old docs/runbook-weekly-summary.md (removed) and is project authority here.
What This Produces
As of 2026-07-07 this is a multi-channel report, not a single post. Each team's active issues go to that team's own Slack channel, and #oa-org is now a priority-only feed rather than a full org digest. See Routing below for the exact mapping.
Each channel's draft is written to its own file under snapshot/ so review and Slack posting use the same text. snapshot/ is gitignored, so these are temporary working output. Each draft is rendered to Block Kit JSON with the existing generic renderer before posting — no per-channel tooling changes are needed, render_weekly_summary_blocks.py and post.sh already take an input file / webhook var as arguments.
All drafts are shown in the conversation for review before anything is posted.
Routing
Group issues by label into these destinations. An issue can appear in more than one channel if it carries more than one mapped label.
| Label | Webhook var | Channel |
|---|
board | SLACK_WEBHOOK_BOARD | #oa-board |
infrastructure | SLACK_WEBHOOK_INFRASTRUCTURE | #t-infrastructure |
finance | SLACK_WEBHOOK_FINANCE | #t-finance |
fundraising | SLACK_WEBHOOK_FUNDRAISING | #t-fundraising |
communications | SLACK_WEBHOOK_COMMUNICATIONS | #t-communications |
education | SLACK_WEBHOOK_EDUCATION | #t-education |
engagement (excluding issues also labeled product team or open role) | SLACK_WEBHOOK_ENGAGEMENT | #t-engagement |
fellowship | SLACK_WEBHOOK_FELLOWSHIP | #pg-data-fellowship |
priority (any team) | SLACK_WEBHOOK_ORG | #oa-org |
community and product team are intentionally not routed anywhere — this was a deliberate call (2026-07-07), not an oversight. Their non-priority issues don't appear in any weekly post. open role issues are already covered by role-pipeline-report.yaml (monthly) and stale-role-warning.yaml (weekly) — never include them here.
SLACK_WEBHOOK_BOARD, _INFRASTRUCTURE, _FINANCE, _FUNDRAISING, _COMMUNICATIONS, _EDUCATION, and _FELLOWSHIP are new as of this routing change. Each needs its own Incoming Webhook created in Slack before it can be used — see .env.example. If a webhook var isn't set yet, skip posting to that channel but still show its draft in the conversation.
If a channel has zero matching issues that week, skip both drafting and posting for it — don't post an empty "nothing to report" message. Bounded notifications matter on a shared org.
Steps
1. Sync the snapshot
tools/sync/run.sh
This regenerates snapshot/ from the live GitHub state. Always sync before summarizing — never summarize from a stale snapshot.
2. Read the snapshot and context
Load and read:
snapshot/issues.md — open issues by team label (each issue's labels are listed; use them for routing)snapshot/labels.md — current label taxonomy (for reference)docs/templates/weekly-summary-template.md — canonical per-channel and #oa-org message shapes- recent files in
docs/weekly-review-archive/, if any — trend context only
Individual issue detail files (snapshot/issues/*.md) are available if a specific issue needs deeper context.
Always summarize from the fresh snapshot. The archive is useful context, not source of truth.
3. Produce the per-channel drafts
For each row in Routing with at least one matching issue, write snapshot/weekly-summary-<slug>.md (e.g. weekly-summary-infrastructure.md, weekly-summary-org.md for the priority feed), following docs/templates/weekly-summary-template.md. Use Slack-friendly mrkdwn: short headings, - markers with line breaks for list structure, plain text. Avoid tables. Do not use * as a bullet marker; in Slack mrkdwn, *text* means bold.
When naming issues, put the issue title first, then link only the issue number:
Issue title | <https://github.com/open-austin/org/issues/123|#123>
Do not use full-title links or standard Markdown links such as [Issue title](https://...); Slack renders incoming webhook text more predictably with angle-bracket links.
For a team channel draft: a flat bulleted list of that team's matching issues, one per line, with assignment status ((assigned: none) or (assigned: name)). No per-team header nesting needed — the channel itself is the team.
For the #oa-org priority draft: a flat bulleted list of all priority-labeled issues across every team, each line prefixed with its originating team label so cross-team context isn't lost: [infrastructure] Issue title | <URL|#123> (assigned: none).
Keep it skimmable. One issue per line, concrete numbers, no semicolon-separated chains. Do not include Open Roles or recruiting tickets. Do not include internal repo TODOs or tooling status unless they directly affect the org-facing work being summarized.
4. Review with user
Show every non-empty draft in the conversation together. Ask:
- "Anything to add or correct before I post these?"
- Only post to Slack after explicit confirmation.
5. Post to Slack (if confirmed)
For each approved draft, render it into a Slack Block Kit payload using the same generic renderer for every channel:
tools/notify/render_weekly_summary_blocks.py snapshot/weekly-summary-<slug>.md --output snapshot/weekly-summary-<slug>.blocks.json
Preview each payload without posting:
tools/notify/post.sh SLACK_WEBHOOK_<VAR> --payload snapshot/weekly-summary-<slug>.blocks.json --dry-run
Then post each after approval:
set -a
source .env
set +a
tools/notify/post.sh SLACK_WEBHOOK_<VAR> --payload snapshot/weekly-summary-<slug>.blocks.json
Skip posting to any channel whose webhook var isn't set in .env yet — report that in the conversation rather than failing silently.
If Block Kit rendering fails for a given draft, fall back to the plain-text message for that channel only:
tools/notify/post.sh SLACK_WEBHOOK_<VAR> < snapshot/weekly-summary-<slug>.md
If no Slack webhooks are configured yet at all, just deliver every draft in the conversation.
6. Archive the final drafts
After the user approves, save each posted channel's exact final text to docs/weekly-review-archive/YYYY-MM-DD/<slug>.md:
mkdir -p docs/weekly-review-archive/YYYY-MM-DD
cp snapshot/weekly-summary-<slug>.md docs/weekly-review-archive/YYYY-MM-DD/<slug>.md
This is a change from the old flat docs/weekly-review-archive/YYYY-MM-DD.md naming (single file per week) to one dated folder per week containing one file per channel that was posted. Older flat files are historical and don't need renaming.
If a draft was revised after posting, archive the revised text with a suffix such as <slug>-revised.md.
Frequency
This is manually triggered — no cron. Run it when the user asks. Once a week is typical but there's no fixed schedule.
Related
tools/sync/run.sh — sync commandtools/notify/post.sh — Slack post command, generic across channels/webhook varstools/notify/render_weekly_summary_blocks.py — renders any weekly-summary-shaped markdown file to Slack Block Kit JSON, generic across filesdocs/templates/weekly-summary-template.md — per-channel and #oa-org message templatesdocs/weekly-review-archive/ — final weekly summary archive.env.example — webhook var placeholders, including the new per-team onesAGENTS.md — agent rules and write safetysnapshot/ — gitignored, always regenerate before use
