Give every rule a short ID that never changes

How to do it

An agent then cites a rule by its ID in plans, reports, commits and code comments, not by a long title or address. Number rules in the order they are written, not by position. A position such as 3.4 shifts whenever a rule is added above it, so old reports point at the wrong rule. Give each area its own prefix, keep the ID next to the rule in the source, and let the build name the next free number. Retire the ID of a deleted rule. Put the ID in every list an agent reads, and offer a short address that opens a rule from its ID, such as /r/SEC-12. Ask the agent to report each rule as pass or fail by ID. The same applies to acceptance criteria and to decision notes.

Examples

Using these examples: they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

JavaScript example

const ID = /^[A-Z]{3}-[1-9]\d*$/;
const seen = new Set();
for (const rule of rules) {
  if (!ID.test(rule.id)) throw new Error(`"${rule.title}" needs an ID such as ${prefix}-${nextFree(rules)}`);
  if (seen.has(rule.id)) throw new Error(`${rule.id} is used twice`);
  seen.add(rule.id);
}

Python example

retired = set(json.loads(Path("retired-ids.json").read_text()))
current = {rule["id"] for rule in rules}
missing = previous_release_ids - current - retired
if missing or current & retired:
    sys.exit(f"Missing IDs: {sorted(missing)}. Reused retired IDs: {sorted(current & retired)}")

How to check

The build fails when a rule has no ID or when two rules share one. A test compares the IDs of the last release with the current ones. No ID is missing unless it is listed as retired, and no retired ID is in use.

Related rules

• Give every task acceptance criteria in AI development
• Write down the decisions agents keep getting wrong in AI development