Error Handling & Debugging

Specification > Engineering

This chapter defines how a module reports failures and how you investigate them: a structured error-code format with explicit severities, a grade derived from severity counts, a fixed priority ladder for resolving defects, and a variable-tracing discipline for understanding them. The error-code rules are conditional and apply where a module emits codes; the debugging discipline is always in force.

Error Codes

Where a module reports failures with codes, each code MUST follow a PREFIX-NUMBER format, where PREFIX is a short uppercase namespace for the emitting module and NUMBER is a stable numeric identifier.

Aspect	Rule
Format	A code MUST match `PREFIX-NUMBER` (for example `AUTH-101`).
Prefix	The prefix MUST be a short, uppercase, module-scoped namespace.
Number	The number MUST be stable once assigned; you MUST NOT reuse a retired number for a new meaning.
Message	Every code MUST carry a human-readable message describing the condition.

Severities

Every emitted condition MUST declare exactly one severity:

Severity	Meaning
`ERROR`	A failure that prevents the operation from completing correctly.
`WARNING`	A recoverable or degraded condition that does not stop the operation.
`INFO`	An informational notice with no adverse effect.

Grading

A run MAY be summarized with a single grade derived from its severity counts. When a grade is reported, it MUST be computed from the counts as follows:

Grade	Condition
`A`	No `ERROR` and no `WARNING`.
`B`	No `ERROR`, one or more `WARNING`.
`C`	One or more `ERROR`.

The grade MUST be derived deterministically from the counts; you MUST NOT assign a grade that contradicts the severities present.

Error-handling Priority Ladder

When you resolve a defect, you MUST work the steps in order and MUST NOT skip ahead:

Step	Action
1	Reproduce the problem first; confirm the failure before changing anything.
2	Research the cause; understand why it happens before proposing a fix.
3	Never rush an architectural change; structural rewrites are not a first response.
4	Changing the environment is the last resort, attempted only after the steps above.

You MUST NOT alter environment or configuration to mask a defect whose cause you have not yet established.

Variable Tracing

When you debug, you MUST make no assumptions about a value and instead follow each variable through every method it passes, step by step, from where it originates to where it is consumed. You MUST confirm a value’s actual state at each step rather than inferring it, because an unverified assumption can send a fix in the wrong direction.