{ "id": "14.7", "title": "Changing this handbook", "department": "People and ways of working", "department_slug": "people-and-ways-of-working", "direction": null, "branded": false, "status": "draft", "owner": "Param", "last_verified": "Mon Oct 26", "holds": "Front matter, statuses, checks, publishing", "urls": { "html": "https://handbook.joinsquareup.com/people-and-ways-of-working/changing-this-handbook", "markdown": "https://handbook.joinsquareup.com/people-and-ways-of-working/changing-this-handbook.md", "json": "https://handbook.joinsquareup.com/people-and-ways-of-working/changing-this-handbook.json" }, "other_directions": [], "tldr": { "headline": "Edit, check, snapshot, publish: one loop keeps this handbook honest", "points": [ { "icon": "book", "text": "Every page keeps six parts in order and cites its sources on each Today line." }, { "icon": "check", "text": "The check script must end with zero errors before anything is published." }, { "icon": "lock", "text": "Only Param sets a page to verified; opinion pages get proposals, never direct edits." }, { "icon": "clock", "text": "A 9 am scheduled run keeps pages fresh, with no snapshot, no deploy and no spend." }, { "icon": "chat", "text": "Comments are not deployed yet, so they do not work today." } ], "stat": { "value": "12", "label": "steps in the change loop" }, "decide": "Who besides Param may set a page to verified, and when do we take Handbook 1.0?", "mood": "building" }, "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" ], "open_questions": [ "**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.", "**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." ], "parts": { "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\n\n- Markdown with front matter in `content//.md`; branded documents have five versions, `..md`. [src: handbook/AGENTS.md] [src: handbook/check.mjs:23]\n- Front matter: `id`, `title`, `dept`, `status`, `owner`, `branded`, `last_verified`, `sources`. [src: handbook/AGENTS.md] [src: handbook/WRITING.md]\n- Six parts in order: Answer, Today, Tomorrow, How we do it, Numbers, Open. [src: handbook/check.mjs:19]\n- `registry.json` lists every document; `map.json` maps source paths and memory notes to the documents they feed. [src: handbook/AGENTS.md] [src: handbook/map.json:1-3]\n- `config.json` holds `liveDirections`, empty until a direction is picked. [src: handbook/config.json]\n\n### Statuses\n\n| Status | Means | Who sets it | Source |\n|---|---|---|---|\n| draft | Written from sources, not checked by Param | the writer | [src: handbook/WRITING.md] |\n| generated | Rebuilt from code on every build | `tools/gen.mjs` | [src: handbook/AGENTS.md] |\n| needs-you | Core facts have no source; questions and proposals written | the writer | [src: handbook/WRITING.md] |\n| verified | Param checked it | Param only | [src: handbook/WRITING.md] |\n\n### What `check.mjs` checks\n\n| Check | Fails or warns | Source |\n|---|---|---|\n| Six parts present and in order, no part left unwritten | error | [src: handbook/check.mjs:32-37] |\n| No dash, no exclamation mark, no emoji, no banned word | error | [src: handbook/check.mjs:39-42] |\n| A status from the four above | error | [src: handbook/check.mjs:45] |\n| Links between handbook pages resolve | error | [src: handbook/check.mjs:56] |\n| The shared docs' catalogues still match the code | error | [src: handbook/check.mjs:59-60] |\n| \"moves\" where Plays is meant; parentheses outside code | warning | [src: handbook/check.mjs:43-44] |\n| More than a quarter of Today lines without `[src: …]` | warning | [src: handbook/check.mjs:47-50] |\n| A brew source changed after `last_verified` | stale, becomes a task in Next | [src: handbook/check.mjs:52-54] |\n\n### The tools\n\n| Tool | Does | Source |\n|---|---|---|\n| `tools/snapshot.mjs take \"\"` | Commits, tags `hb-` with what changed; snapshots never move or get deleted | [src: handbook/tools/snapshot.mjs:1-6] |\n| `tools/snapshot.mjs build` | Builds every snapshot into `out/v//` | [src: handbook/tools/snapshot.mjs:4] |\n| `tools/comments.mjs open, reply, propose, resolve, task, accepted` | Claude's side of the comments, same Firestore rows | [src: handbook/tools/comments.mjs:1-7] |\n| `tools/next-sync.mjs` | Builds tasks for Next from needs-you documents, unwritten departments, warnings, stale documents and open build steps | [src: handbook/tools/next-sync.mjs:1-8] |\n| `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 | [src: handbook/tools/stop-hook.mjs:1-6] [src: .claude/settings.json] |\n| Scheduled task `handbook-morning`, 9 am | Runs `handbook-update` unattended: no snapshot, no brew deploy, no spend | [src: ~/.claude/scheduled-tasks/handbook-morning/SKILL.md] |\n| `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 | [src: brand-directions/_tools/deploy-handbook.py:57-63] |\n| `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 | [src: handbook/tools/tldr.mjs:1-14] |\n\n### TL;DR and machine files\n\n- Every document version has a TL;DR beside it, `.tldr.json` or `..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. [src: handbook/tools/tldr.mjs:3-11] [src: handbook/build.mjs]\n- `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. [src: handbook/check.mjs]\n- 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. [src: handbook/build.mjs]\n\n### Comments\n\n- Any paragraph, row or task can carry a thread; a comment is a comment or a proposal. [src: handbook/comments/server.mjs:1-4] [src: handbook/comments/server.mjs:43]\n- A comment never edits a document; an accepted proposal is applied by `handbook-update`. [src: handbook/tools/comments.mjs:7]\n- The service is not deployed and the handbook is public, so comments do not work today. [src: handbook/tools/next-build.json] [src: ~/.claude/scheduled-tasks/handbook-morning/SKILL.md]", "Tomorrow": "| Item | Version | Tag |\n|---|---|---|\n| The loop below, the checks and the Stop hook | v1 | Stays |\n| Comments live once the Access gate is on | v1 | New |\n| First snapshot, Handbook 1.0, once every department is written | v1 | New |\n| 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`.\n2. Find what changed: brew commits since `.last-sync`, new memory notes, decisions in chat, open comments.\n\n```bash\ncd /Users/param/Documents/ChatGPT/handbook\ngit -C ../brew fetch -q origin\ncat .last-sync\nnode tools/comments.mjs open --claude\nnode tools/comments.mjs accepted\n```\n\n3. Find the documents each change touches with `map.json`, else by topic in `registry.json`.\n4. Edit only the affected parts. Cite every Today line with `[src: …]`. Set `last_verified` to today. Never set `verified`.\n5. 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.\n\n```bash\nnode tools/comments.mjs propose \"\"\n```\n\n6. A decision made in chat gets a row in `brand-directions/docs2/content/decisions.mjs`, newest first, never deleted.\n7. An answered needs-you question moves its document to draft, with the answer sourced as \"Param, \".\n8. Regenerate, check and build. `check.mjs` must end with 0 errors.\n\n```bash\nnode tools/gen.mjs && node check.mjs && node build.mjs\n```\n\n9. 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`.\n10. Snapshot when the change is material, a new or rewritten document, a decision, an answered question, or a direction picked:\n\n```bash\ngit tag -l 'hb-*'\nnode tools/snapshot.mjs take \"\"\n```\n\n11. Publish:\n\n```bash\npython3 ../brand-directions/_tools/deploy-handbook.py\n```\n\n12. Write `\\t` to `.last-sync`, commit, and end with three lines: what changed, what is new in Next, what waits on Param.\n\n[src: .claude/skills/handbook-update/SKILL.md]", "Numbers": "| Metric | Definition | Where measured |\n|---|---|---|\n| Check errors | Errors at the end of `node check.mjs` | `.check.json`; must be 0 to publish |\n| Stale documents | Documents whose brew sources changed after `last_verified` | `.check.json` |\n| Needs-you documents | Documents waiting on Param | `registry.json` and front matter |\n| 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.\n2. **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." } }