Writing standard

How super-board writes commits, PR bodies, tickets and comments, in the pack and in every project it is installed in. The rules live in writing-standard.md.

Commit

The commit message, in the super-board repo and every project it is installed in. Emoji map: ✨ feat · 🐛 fix · 🔧 chore · ♻️ refactor · 🧪 test · ⚡ perf · 📝 docs · 👷 ci · 💄 ui · 🔒 security · ⏪ revert · 🚧 wip. Squash merge = PR title + bullet body.

Short bullets

🐛 [fix] receipts: show a size error over 10 MB

- 413 now shows "File too large"
- client checks size before upload
- e2e covers desktop + mobile

Closes #790
Co-Authored-By: Claude …

PR status card

The first line of the PR. It says where the PR stands.

GitHub alert

ⓘ Note

⏳ In review · round 1 · ✅ 2/3 AC · Closes #790

💡 Tip

✅ Merged · 9c41e07

⚠ Warning

🛑 Blocked · needs Eric

> [!NOTE]
> ⏳ In review · round 1 · ✅ 2/3 AC · Closes #790

PR · Problem

Where it happens, who sees it, how to get there (one step per line), and what happened.

Lettered under Where

Problem

Where: Receipts page, /dashboard/receipts
1. Sign in
2. Click Receipts in the sidebar
3. Drag a 12 MB PDF onto Drop receipts here
Who: any signed-in user (free plan)
What happened: the spinner never stops

PR · Solution

What we did.

Plain bullets

Solution

413 shows "File too large (max 10 MB)"
Client checks size before upload
One limit constant for client + server

Acceptance criteria

A checklist. Unchecked means not verified, with a one-line reason.

Checklist + proof line

Acceptance criteria

12 MB file shows the size message in 1 s↳ upload-size.spec.ts:14
No request over 10 MB↳ spec asserts 0 calls · HAR
No new Sentry events after deploy↳ not verified: needs prod deploy · Eric

Iteration history

The lane timeline. GitHub markdown can't run JavaScript, so the time is fixed when the lane writes it.

Local time from config

Lane	Done	Time	Details
🔨 builder	✅	Oct 2, 10:02 EDT	draft
🔍 qa	❌ v1	Oct 2, 10:40 EDT	mobile hidden
🔍 qa	✅ v2	Oct 2, 11:55 EDT	runs/…-v2/

config timezone: America/Toronto. Onboarding sets it to the machine's time zone.

Before | After

For UI changes. Images are committed on the branch and embedded by a raw URL pinned to the sha.

Two-column table

Before | After

	Before `5a2363b`	After `3f9c2a1`
Desktop
Mobile

Risk

What could break, and what limits the damage. If it merged with a red check, Risk says which check and why.

Level + one line

Risk

🟢 Low. Limit read from one constant; no plan differences.

Ticket

Problem · Context · Fix · Acceptance criteria · Risk · Blocked by. Context uses one step per line.

Lettered under Where

🐛 [bug] receipts: spinner never stops over 10 MB

Problem

A 12 MB PDF spins forever. The 413 is never handled.

Context

Where: /dashboard/receipts
1. Sign in as owner
2. Click Receipts
3. Drag 12mb.pdf onto the drop zone
Who: any signed-in user

Fix

Map 413 to the size message; check size first.

Acceptance criteria

Size message within 1 s
No request over 10 MB

Risk

Limit in two places → one constant.

Blocked by

None.

Bug · Evidence

For agents. All 12 rows; an empty row says n/a, why.

Folded table

Evidence

12 rows · Sentry BOOKZERO-3F1 · 14 users

Steps	1. sign in 2. Receipts 3. drop `12mb.pdf`
Expected / actual	size message / endless spinner
Error + stack	`PayloadTooLargeError` · `route.ts:48`
Request / trace ID	`req_01JB8…7QK`
Sentry	BOOKZERO-3F1
PostHog replay	replay 0193…b7
Logs	`413 size=12.4MB`
HAR / API sample	`POST /api/receipts/upload → 413`
Env + release	staging · v1.42.0 · `5a2363b`
First / last seen	Sep 28 · Oct 2
Screenshots	embedded raw URL · `receipts-desktop.png`
Users affected	14 (7 days)

Lane comment

The head is [role] [label] status, then what was done, what's left, and who's next. The reviewer report is one comment, edited in place each round. All prose goes through humanizer.

Short sections

super-board commented

[qa] [report] ❌ failing · round 1

Did: ran AC1–AC2, desktop + mobile

✅ AC2 no request over 10 MB

❌ AC1 mobile: message under keyboard

Next: builder

AGENTS.md section

What install writes into a project. CLAUDE.md = @AGENTS.md.

Tables + caps rules

## Writing (super-board)
| Thing  | Format                      |
|--------|-----------------------------|
| title  | `emoji [type] scope: subj`  |
| PR     | card · Problem · Solution · |
|        | AC · history · B|A · Risk  |
| ticket | Problem · Context · Fix ·   |
|        | AC · Risk · Blocked by      |

- NEVER put arrows in steps. one per line.
- NEVER link screenshots. embed raw URL.
- DON'T list files in comments.

Examples use a sample receipts bug (#790). ← super-board