Agent Wranglers

Recommended

Cite the primary source for every rule

Link every rule that follows a specification, standard or law to that text. Fail the build on a citation from a host outside an allow list of authorities.

By Agent Wranglers. Updated .

How to do it

Give each rule a sources field with one to three links. Cite the text that binds, such as an IETF RFC, a W3C or WHATWG spec, a law on EUR-Lex or a regulator's own page. Never cite blogs, tutorials, encyclopedias or vendor marketing, because they go stale and repeat each other. Keep the allow list of hosts in one place in the code. Link to the current version and the exact section where the page has stable anchors. Fetch every link once before you add it, so no address comes from memory. Then let code watch the sources, as Watch cited sources in code says.

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 AUTHORITIES = ['rfc-editor.org', 'w3.org', 'spec.whatwg.org', 'europa.eu', 'gov', 'owasp.org'];
const isAuthority = host => AUTHORITIES.some(domain => host === domain || host.endsWith(`.${domain}`));

export function checkSources(rule) {
  const outsider = rule.sources.find(source => !isAuthority(new URL(source.url).hostname));
  if (outsider) throw new Error(`${rule.name} cites ${outsider.url}, which is not an authority`);
}

Python example

from urllib.parse import urlparse

AUTHORITIES = ["rfc-editor.org", "w3.org", "spec.whatwg.org", "europa.eu", "gov", "owasp.org"]

def is_authority(host: str) -> bool:
    return any(host == domain or host.endswith("." + domain) for domain in AUTHORITIES)

def check_sources(rule: dict) -> None:
    for source in rule["sources"]:
        if not is_authority(urlparse(source["url"]).hostname):
            raise ValueError(f"{rule['name']} cites {source['url']}, which is not an authority")

How to check

Add a source from a blog host to any rule. The build stops and names the host. A rule whose text names an RFC number with no source also stops it.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/engineering/documentation/cite-primary-sources">Agent Wranglers engineering playbook</a>. In code you write, add a comment next to it with the same link.