SSR Codex

SSR's engineers answer technical questions with help from an internal AI assistant called Smitty. It searches the firm's library of mechanical, electrical, and plumbing standards, calculators, and design guides, then answers from what it finds. The catch: those documents were written for experienced engineers. They leave out context a newer engineer needs, and some standards were never written down at all, so Smitty comes up short exactly where help matters most.

Codex is the tool senior engineers use to fill those gaps. They go through a document, find what's missing, and add annotations Smitty can draw on. As annotations pile up and start linking documents to each other, Codex becomes less a pile of notes and more a map of what the firm knows.

I led the product design, working with a PM and a lead engineer at By the Pixel: the annotation dashboard, the annotation editor, the metadata model, and the flow an engineer follows to create an entry.

Ask Smitty about panel boards and it can retrieve the panel board standard and summarize it. But if the standard never spelled out that toilet rooms require GFI outlets, Smitty can't tell you that. The document never said it. That knowledge lived in a senior engineer's head, not on the page.

Working through documents this way surfaced a second problem: some standards had no home document at all. The firm was carrying knowledge it had never written down, and nobody was tracking the gap.

There are two jobs here: retrieval, which is finding the right document, and interpretation, which is understanding it once you have it. The team chose interpretation first. User feedback pointed to missing context as the bigger gap, and it was easier to isolate and measure. Codex is the interpretation half.

The people doing this work are discipline leads, the experts who already carry the knowledge. They're also the busiest people at the firm. If the tool cost them time they would drop it, and the whole effort would fail. That constraint shaped every decision after it.

Codex has three roles. Super Admins manage the system, Technical Leaders own and edit content in their discipline, and Reviewers can weigh in without full editing rights. The permissions differ, but the approval process between them stays deliberately light. A heavy review chain would punish exactly the people the tool depends on.

The obvious design, a form where experts write down what they know, fails with these users. Writing context from a blank page is slow. The firm's busiest people would do it once, badly, and not come back.

The better approach came from an observation session. A senior engineer uploaded a real document to Claude and worked through it section by section, building a companion document of the context the original left out. It worked, but it was slow. It took many turns, the companion document wasn't tied to specific passages in the source, and chat was an awkward place to build that layer. The rhythm was right, though. The AI proposed about fifty additions one at a time, and the engineer kept the source open and checked each one against it.

I designed around that rhythm and against those two failures. A conversation keeps the engineer reviewing instead of typing. They react to specific proposals about a document they know well, which is faster and more accurate than starting from nothing. Because each step points back to the source, it's also harder to rubber-stamp what the AI wrote. The editor fixes the rest: every annotation is anchored to its passage, and the conversation sits beside the document instead of replacing it.

The AI finds what's missing. It never produces final numbers and never gets the last word. A person who knows the document reviews everything and is responsible for what gets published.

Fifty proposed annotations only help if reviewing them is cheaper than writing them, so the editor is built to make reacting fast. Starting a document takes one click. From the dashboard an engineer hits Begin Annotating and can give the model instructions first, like what to focus on or what this document tends to assume. Then the model reads the document and drafts annotations.

Each annotation sits in the right margin beside the text it refers to, the way comments work in a Google Doc, and drafts are unmistakably yellow. The engineer works through them one at a time. Every annotation has its own text input, so feedback goes right next to the thing it's about: accept the draft, or tell the model what's wrong and let it try again. Manual editing exists, but SSR wanted the model doing the writing, so the interface leads with feedback instead of a blank field. An approved annotation turns green. The left sidebar shows the document's outline with a count of remaining drafts per section, so you always know how much is left.

Engineers aren't limited to reacting, either. Highlight any passage and add an annotation manually; the person chooses where, and the LLM still takes the first stab at what.

Each annotation also carries some working metadata. An optional expiration date marks information with a shelf life, so a value that will change gets revisited before it goes stale. An annotation can be assigned to a colleague, for review or because the topic is really theirs. Links connect it to related documents and Codex entries, which is where the knowledge map starts. And every annotation has its own URL, so engineers can share one in an email or chat without sending anyone to dig for it.

Alongside the margins runs a global chat sidebar holding the whole conversation with the model, and individual annotations surface in that thread too. Context builds in one place instead of fragmenting across fifty small exchanges, so what the model learns in section 3 is still in the room by section 9.

With dozens of documents in progress across disciplines, the risk is losing track of what's done. Documents come in from the firm's SharePoint and show up as un-started, ready for someone to pick up or assign. From there the dashboard shows each document's annotations, who owns them, what state they're in, and whether they've been published. A "My Documents" tab shows engineers only what's assigned to them, and filters narrow the full list, for example to one discipline's backlog.

The detail that mattered most was how to show where a document stands. Each row has a fraction, approved annotations over total, next to a dot that stays yellow until everything is approved and turns green at 100%. The denominator is the annotations that actually exist rather than a guess at the finish line, so the number can't mislead you the way a progress bar sitting at 80% can.

Approval isn't the end, though. An annotation can be approved but not yet published, and until it's published Smitty can't see it. It works a lot like git: approved but unpublished is committed but unmerged, real work that isn't live yet. So the dashboard tracks publishing separately. An Unpublished badge flags documents with approved work that hasn't shipped, and a last-published column shows when each document's context actually reached Smitty. Between the dot, the badge, and the date, an engineer can see which documents still need work.