# Lessons

Patterns from corrections and mistakes, so they aren't made twice. Reviewed at the start of a session.

## 6 November 2026

- **Never cut a test run's failures short.** A `head` on the output hid sixteen failures behind one long list, and I nearly committed on it. List the failures first, in full, then read them one at a time. Also: a full run is what finds the rest; a filter finds what you already suspect.
- **Don't ask for what the system already knows.** My grant form asked for start and end dates. The Architect: the grant is recorded on the day it's granted, for a year by default. Before adding a field to a form, ask whether the action itself or a default already gives the value.
- **Start a console from what its owner watches.** I mocked up records (clients, keys, a catalogue, brand previews). The Architect wanted a picture: Atrium surrounded by the products' servers, with state at a glance and details in a drawer. Ask what the owner wants to see first, before drawing lists.
- **Stay inside the project being worked on.** I planned a TuteCore release, a client kit and a sweep there because the handbook says "TuteCore
  first". The Architect: "dont make any changes to the tutecore repo. all these discussions are only relevant to the atrium". When a rule points at
  another repository, ask before building a plan on it.
- **Separate identity, organisation and what's sold.** The Architect corrected the first design, which held an organisation's products inside
  Clavis: "organisations accounts are registered without products information", with product information in a dedicated subscription
  subsystem. Ask early what each concept owns, rather than following a spec's grouping.
- **Check the whole schema before describing a record.** I told the Architect an organisation held six fields after reading only its
  `create_tenant` migration. A later migration adds five more. Read every migration on a table, or the model.
- **Check an agent's quote against the page.** A report attached Atlassian's "not something we would recommend" to the opt-in migration; on
  the page it refers to running two migrations in parallel.
- **Discuss before building, every module.** A finished step opens the next discussion, not the next build; a request for documents
  isn't approval of a plan's decisions. The Architect: "we must discuss each module and plan mockups ahead of each build."
- **Read the apps before accepting a spec's premise.** The spec assumes Clavis can come before Nuntius and that Loop is the second
  payments product. Campus's live sign-in sends SMS, and Desk has Paystack built. Before justifying an order or a design, check what's
  already built; most of Atrium turned out to be extraction.
- **Follow the runbook's steps in order, including the dull ones.** Skipping `npm run build` produced 175 failing tests that looked
  like a broken rename. When a whole class of tests fails the same way, read the log first: it said "Vite manifest not found" 690 times.
- **A piped exit code is the pipe's.** `php artisan test | tail` reports `tail`'s exit code. Capture the suite's own, and read the figures.
- **Find the release procedure before cloning a starter pack.** A clone keeps the pack's history and leaves `origin` pointing at it, so a
  plain push from the new app would land in the pack. TuteCore's runbook says start from a tagged release.
- **A spec's stated name wins over a folder's.** The spec says "shortname atrium". The rename runs once and writes that name everywhere,
  so read the spec for the name before running it.
- **Check an agent's claim before it shapes a decision.** Reports arrive in one confident voice. Read the lines that decide the outcome
  in the code itself, and say what was only reported.
- **Open a module's discussion with what it is, its scope and its failsafe.** A list of decisions has no footing without them. Say what the module is in simple terms, what Atrium handles and what stays in the product, and how things carry on if Atrium fails for a short period, then ask the questions. Working through the failsafe also finds decisions the list missed.
- **Credit the Architect, not "the user".** Decisions are made with a team, so documents say "the Architect". "The user menu" and a person using the app keep their own words.
- **Internal docs name the internal app.** After A1 made `app_name` read the company's name, the docs frame and the journey went on using it, and the journey called Atrium "Tutelora". Internal pages use `short_name`.
- **Use the house's words, and the arriving person's context.** I wrote "Proven" where the app says "Verified", and asked someone arriving from Campus what kind of organisation theirs is. Use the app's existing word for a state, and assume what the way in already says.
- **Identical cards are a catalogue, not a design.** The Products page was three equal cards, called "boring". Draw from what the owner is deciding: what they run now, with figures that are true, and what fits beside it, with a picture of each. Put every choice a step needs on that step, as with addresses when adding a product.
- **A choice should sell, not sort.** "What kind is it" with three plain cards was called boring: people come to choose a product, so show the products, each with its line, a picture of it at work, and what it does. And never prefill what the person hasn't told us, such as a custom domain.
- **Name each page's picture before drawing it, and reread these lessons first.** Tabula's first mockups were called "standard boring and bland. nothing exceptional in aesthetics": the kit's panels, tables and three equal cards with billing words in them, the third time this lesson has been learnt. Before writing a mockup, write down for each page the one picture that shows the reader's situation at a glance (where they are in the year, what they use against what a plan allows, what the money splits into) and the moment worth designing (paying, being paid, a deadline). Build that first; a panel or a table is the fallback, never the page.
- **A journey chapter is four edits, not one.** From chapter 20 to 31 I added each chapter but not its row in "At a glance", left the
  "last chapter" stamp on chapter 11, appended 8 November's chapters oldest-first (the other days run newest-first) and left its count at
  5. The Architect noticed. Each chapter: the chapter itself (newest first in its day), its glance row with commits and the test count,
  the stamp, and the day's summary and count; then check that the glance rows equal the chapters before rebuilding.