Architect
How-to guides
ReferenceNormative

Red flags

The sentences that mean stop — this is data, not specification — and the excuses that keep them alive.

Use this page as the checklist for review: auditing an existing design for hardcoded constants and rigid flow.

It is data, not specification

  • Writing a number into a specification: "the ministry has 32 regions", "there are 8 categories"
  • A question to the client that begins "what is the list of…"
  • A question asking the client to decide a value your own engine already makes changeable
  • Naming a specific organisational unit inside an immutable artefact
  • A workflow step that only makes sense for this one client
  • "We'll ask them and hardcode it for now"
  • A specification that cites a filename

All of these mean: it is data, not specification. See the configurability boundary.

Go and find out what the thing is already called

  • Offering a shortlist of invented names — that is a skipped lookup, not creativity
  • Any identifier derived from initials, or needing a legend to be read

See naming.

The authority is forking

  • A second document that describes the domain instead of pointing at the specification
  • An enumeration, status or role copied into a second file
  • A brief still being edited after a specification was accepted — that is a shadow specification
  • A task or a story that restates a rule instead of citing its identifier

See artefacts and authority.

The gate is being walked around

  • A story moved to in progress while its epic gate still awaits a dependency
  • A task list for a gated story — "a list of small concrete things reads as permission to start"
  • An assumption with no owner and no expiry. That is not an assumption, it is a decision nobody made
  • "Investigate…" or "Look into…" as a task — that is a question with a checkbox

See delivery gates.

Rationalisations

ExcuseReality
"The client only has 32 of them, it will never change"Organisations reorganise. That is what they do.
"Configuration is over-engineering for one client"You are building for the second client too. And the first one after their next restructure.
"It is faster to hardcode and ask"Faster to write, and it converts into a blocking question, a redeploy, and a divergence.
"Making everything configurable is its own failure"True — which is why principle 2 exists. Configure the path, never the walls.
"The client asked for exactly this flow"They described their flow today. They did not ask you to make tomorrow's impossible.
"This question genuinely needs an answer"Run the questions pass. Most do not.

The excuses for skipping the naming lookup have their own table, on naming.

On this page