Snapshots

Edit, check, snapshot, publish: one loop keeps this handbook honest

Being built
  • Every page keeps six parts in order and cites its sources on each Today line.
  • The check script must end with zero errors before anything is published.
  • Only Param sets a page to verified; opinion pages get proposals, never direct edits.
  • A 9 am scheduled run keeps pages fresh, with no snapshot, no deploy and no spend.
  • Comments are not deployed yet, so they do not work today.
12steps in the change loop
Your call

Who besides Param may set a page to verified, and when do we take Handbook 1.0?

People and ways of working · 14.7

Changing this handbook

DraftLast checked Mon Oct 26Owner Param

Answer

Every change to this handbook goes through the same loop, edit the document with sources, run the checks, update Next, snapshot when it matters and publish, and this page is that loop written out for a person or a Claude session without the handbook-update skill.

Today

What a document is

  • Markdown with front matter in content/<department>/<slug>.md; branded documents have five versions, <slug>.<dog|bee|raccoon|octopus|cooker>.md. handbook/AGENTS.md handbook/check.mjs:23
  • Front matter: id, title, dept, status, owner, branded, last_verified, sources. handbook/AGENTS.md handbook/WRITING.md
  • Six parts in order: Answer, Today, Tomorrow, How we do it, Numbers, Open. handbook/check.mjs:19
  • registry.json lists every document; map.json maps source paths and memory notes to the documents they feed. handbook/AGENTS.md handbook/map.json:1-3
  • config.json holds liveDirections, empty until a direction is picked. handbook/config.json

Statuses

Status Means Who sets it Source
draft Written from sources, not checked by Param the writer handbook/WRITING.md
generated Rebuilt from code on every build tools/gen.mjs handbook/AGENTS.md
needs-you Core facts have no source; questions and proposals written the writer handbook/WRITING.md
verified Param checked it Param only handbook/WRITING.md

What check.mjs checks

Check Fails or warns Source
Six parts present and in order, no part left unwritten error handbook/check.mjs:32-37
No dash, no exclamation mark, no emoji, no banned word error handbook/check.mjs:39-42
A status from the four above error handbook/check.mjs:45
Links between handbook pages resolve error handbook/check.mjs:56
The shared docs' catalogues still match the code error handbook/check.mjs:59-60
"moves" where Plays is meant; parentheses outside code warning handbook/check.mjs:43-44
More than a quarter of Today lines without … warning handbook/check.mjs:47-50
A brew source changed after last_verified stale, becomes a task in Next handbook/check.mjs:52-54

The tools

Tool Does Source
tools/snapshot.mjs take <n> "<note>" Commits, tags hb-<n> with what changed; snapshots never move or get deleted handbook/tools/snapshot.mjs:1-6
tools/snapshot.mjs build Builds every snapshot into out/v/<n>/ handbook/tools/snapshot.mjs:4
tools/comments.mjs open, reply, propose, resolve, task, accepted Claude's side of the comments, same Firestore rows handbook/tools/comments.mjs:1-7
tools/next-sync.mjs Builds tasks for Next from needs-you documents, unwritten departments, warnings, stale documents and open build steps handbook/tools/next-sync.mjs:1-8
tools/stop-hook.mjs Asks a session that touched brew, brand-directions or memory, or said "decided", to run handbook-update before it stops; never blocks twice handbook/tools/stop-hook.mjs:1-6 .claude/settings.json
Scheduled task handbook-morning, 9 am Runs handbook-update unattended: no snapshot, no brew deploy, no spend ~/.claude/scheduled-tasks/handbook-morning/SKILL.md
brand-directions/_tools/deploy-handbook.py --public Publishes to handbook.joinsquareup.com with no sign in, at Param's call on 26 Oct; refuses on check errors brand-directions/_tools/deploy-handbook.py:57-63
tools/tldr.mjs Checks every TL;DR file: shape, word limits, icons, mood, writing rules, and that the stat appears in the document; --missing lists the ones not written handbook/tools/tldr.mjs:1-14

TL;DR and machine files

  • Every document version has a TL;DR beside it, <slug>.tldr.json or <slug>.<direction>.tldr.json: a headline, three to five points with icons, one stat from the document, the one call for Param and a mood. The reader's TL;DR toggle shows it with the direction's character. handbook/tools/tldr.mjs:3-11 handbook/build.mjs
  • check.mjs fails on a broken TL;DR and warns on a missing one, so when a document changes its TL;DR is rewritten in the same update. handbook/check.mjs
  • The build writes every page also as .md and .json, plus index.json, tldr.json, llms.txt, llms-full.txt, sitemap.xml, robots.txt, and the brand pack at /brand-assets/brand.json and /claude/brand-visuals.md with every direction's drawings, sounds, colours, type and voice. handbook/build.mjs

Comments

  • Any paragraph, row or task can carry a thread; a comment is a comment or a proposal. handbook/comments/server.mjs:1-4 handbook/comments/server.mjs:43
  • A comment never edits a document; an accepted proposal is applied by handbook-update. handbook/tools/comments.mjs:7
  • The service is not deployed and the handbook is public, so comments do not work today. handbook/tools/next-build.json ~/.claude/scheduled-tasks/handbook-morning/SKILL.md

Tomorrow

Item Version Tag
The loop below, the checks and the Stop hook v1 Stays
Comments live once the Access gate is on v1 New
First snapshot, Handbook 1.0, once every department is written v1 New
Branded versions cut to one when a direction is picked; the rest archived to content/_archive/, snapshot 2.0 v1 Changes

How we do it

  1. Read AGENTS.md and WRITING.md.
  2. Find what changed: brew commits since .last-sync, new memory notes, decisions in chat, open comments.
cd /Users/param/Documents/ChatGPT/handbook
git -C ../brew fetch -q origin
cat .last-sync
node tools/comments.mjs open --claude
node tools/comments.mjs accepted
  1. Find the documents each change touches with map.json, else by topic in registry.json.
  2. Edit only the affected parts. Cite every Today line with …. Set last_verified to today. Never set verified.
  3. Opinion documents, vision 1.3, strategy 1.5, north star 1.6, positioning 15.1, naming 4.3, pricing 13.1 and 11.11, roadmap 2.7, never get a direct edit: post a proposal instead.
node tools/comments.mjs propose <thread id> "<the change>"
  1. A decision made in chat gets a row in brand-directions/docs2/content/decisions.mjs, newest first, never deleted.
  2. An answered needs-you question moves its document to draft, with the answer sourced as "Param, ".
  3. Regenerate, check and build. check.mjs must end with 0 errors.
node tools/gen.mjs && node check.mjs && node build.mjs
  1. Update Next: run node tools/next-sync.mjs, then write new tasks to the Next artifact, collection tasks. For existing tasks change only ask, doc, docUrl and brief; never status, owner or rank.
  2. Snapshot when the change is material, a new or rewritten document, a decision, an answered question, or a direction picked:
git tag -l 'hb-*'
node tools/snapshot.mjs take <next number> "<what changed>"
  1. Publish:
python3 ../brand-directions/_tools/deploy-handbook.py
  1. Write <brew sha>\t<date> to .last-sync, commit, and end with three lines: what changed, what is new in Next, what waits on Param.

.claude/skills/handbook-update/SKILL.md

Numbers

Metric Definition Where measured
Check errors Errors at the end of node check.mjs .check.json; must be 0 to publish
Stale documents Documents whose brew sources changed after last_verified .check.json
Needs-you documents Documents waiting on Param registry.json and front matter
Verified share Documents Param has verified, over all front matter, Proposed

Open

  1. Who besides Param may set a document to verified? Proposal: only Param, until each department has a named owner; then the owner may verify their own department.
  2. When is Handbook 1.0 taken? No snapshot exists yet. Proposal: the day every department is written and check.mjs passes, before the first upload.
Sources
  • handbook/AGENTS.md, handbook/WRITING.md, handbook/check.mjs:1-80, handbook/config.json, handbook/map.json:1-3
  • handbook/tools/snapshot.mjs:1-30, handbook/tools/comments.mjs:1-30, handbook/tools/next-sync.mjs:1-30, handbook/tools/stop-hook.mjs:1-40, handbook/tools/next-build.json
  • /Users/param/Documents/ChatGPT/.claude/skills/handbook-update/SKILL.md, /Users/param/Documents/ChatGPT/.claude/settings.json Stop hook, ~/.claude/scheduled-tasks/handbook-morning/SKILL.md
  • brand-directions/_tools/deploy-handbook.py:1-60, handbook/comments/server.mjs:1-58
  • memory brew-handbook

Source file content/people-and-ways-of-working/changing-this-handbook.md · For agents: Markdown · JSON