Back-office functional spec

Internal tools rarely fail because the code was hard. They fail because something was underspecified. A feature gets mentioned once in a meeting, nobody writes down how it actually works, and months later it turns into a gap in production. The problem was never technical: it was a subject that got named and never turned into a defined process.

That is why our specifications run long. The document we write for a back-office tool covers every process, every screen field by field, every table and chart with the formula behind each figure, the data model, the stack and the libraries, and the PDF models each screen produces. We spell everything out, because whatever a spec leaves vague is what comes back later as a bug.

Read everything first

Before writing a line, we read the whole project folder, not a sample. Two sources come first.

The video-call transcripts carry the real business rules, the daily pains, and the subjects the client actually cares about, in their own words. That is where the truth of the process lives, not in a tidy summary.

The brief we write ourselves comes next: our own framing of the scope, the recap of what the tool must cover. It becomes the spine of the spec. Around it we read the quote, the emails, the exports and screens of the existing tool, the domain glossary, the stack documents.

The brief opens the questions

The brief is written before the spec on purpose. Its job is not to summarize, it is to surface every subject the tool touches. Each mention of a subject opens a complete definition process for that subject.

A feature named once in passing becomes a full module: its screens, its fields, its statuses, its rules. A spreadsheet the team still relies on becomes a data-migration plan. An outside tool that must stay in sync becomes an integration: what transits, in which direction, which side holds the truth. We walk the brief line by line and turn every subject into a named slot carrying its own open questions.

Grill-me answers all of it

Those open questions are then closed through grill-me, our questioning method: it walks the plan one question at a time, each with a recommended answer to react to, and refuses to move on while anything stays fuzzy. Applied to a spec, it means every open subject is settled live on the page. The subjects are walked in an order where the early ones constrain the later ones: roles first, then the business flows, the data, the views, the tables and charts, the integrations, the stack, the phasing. A subject leaves the interview either fully defined or, if it is genuinely unresolved, parked as an explicit open risk. Never as a plausible guess.

What exhaustive means, concretely

For every module, the spec defines all of it:

• The business flows, end to end and numbered: who does what, in which state, with every branch and every exception.
• Every view, field by field: the header fields, which are required, the statuses, the buttons, the default values, the validation.
• Every table and chart: the columns, the KPI tiles, the filters, and the exact formula behind each number.
• Statuses and numbering: closed status lists, continuous-numbering rules.
• The PDF models the module produces.

Around the modules sit the layers defined once: the data model, the editable referentials that must not be frozen in code, the rules for the rich editor, the exports and the notifications, and the stack with its libraries.

A real fragment

Claims about rigor are easy to make, so here is an actual fragment of one of our specs. This is section 8.0, the base conventions applied to every entity in the system, written once so they never have to be repeated table by table:

8.0  Base conventions & types

Systematic fields, present on every table:
  id          uuid v4        server-generated primary key, immutable
  createdAt   timestamptz    creation timestamp, not editable
  updatedAt   timestamptz    auto-updated on every write
  archivedAt  timestamptz?   soft-delete: non-null = archived, purged after
                             30 days; every list filters archivedAt IS NULL

Normalized business types:
  Amount      Decimal(12,2)  stored raw, never a formatted string
  Percentage  Decimal(6,4)   ratios and rates (margin coefficient, tax rate)
  Quantity    Decimal(12,3)  allows fractions (hours, metres)
  Hours       Decimal(6,2)   duration in decimal hours
  Date        date           stored ISO, displayed DD/MM/YYYY
  Rich text   HTML in text    sanitized on input (tag whitelist, anti-XSS),
                             rendered as-is into the generated PDF
  File        signed URL      private object storage, time-limited signed URLs;
                             MIME whitelist validated by magic bytes, not the
                             extension; executables and SVG rejected

Every entity in the spec inherits these rules. That is what exhaustive buys: a developer, or an agent, never has to guess how money is stored, how a date is displayed, or what happens to a deleted row.

Standardized by reference, never reinvented

We build the same way every time, so the spec never re-explains a method we already own. For anything standardized, it states what this client needs and points to the method that carries the how: the design system and component library, the way we integrate electronic invoicing, authentication and role permissions, security, the data model and API, and deployment. The spec says what, the referenced method says how. That is what keeps a 100-page document coherent instead of contradicting itself.

A full re-read, until complete coherence

A finished draft is not a finished spec. We read the whole document end to end, and every observation, a gap, an inconsistency, a rule that collides with something else we integrate, re-opens the questioning on that exact point and the spec is corrected. We loop until a full pass produces no observation. Only then is the spec in complete coherence with everything the tool will do.

What you walk away with

A document an agent, or a developer, can build any module from without coming back to ask. Every subject that was ever mentioned is defined, every view and table and formula is on the page, the stack and the standards are named. It is the single source every agent reads before touching a ticket, and the reason the tool that ships is the tool that was needed.

---

This whole method is one agent skill: write-back-office-prd, which orchestrates the standardized methods above. If you want to see what we build first, our services lay out the work. And if you already have an internal tool in mind, start a brief on the home page and we turn it into a specification you can build from.