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
The gate is being walked around
- A story moved to
in progresswhile 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
| Excuse | Reality |
|---|---|
| "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.