Universal Repository Specification (URS)

Artifact-first documentation for LLM-assisted development

Note: This URS refers to the Universal Repository Specification, not a User Requirements Specification.

---

What URS is

A Universal Repository Specification (URS) describes how a repository—or a clearly bounded module within it—actually behaves. It is derived from artifacts first and reconciled with documentation second.

---

The problem

LLMs trust what they read: READMEs, comments, filenames, variable names, design docs.

When those drift from code, LLMs confidently do the wrong thing.

Common failure modes:

• Trusting outdated migration docs and producing invalid schema changes
• Believing comments that claim validation where none exists
• Inferring conventions that are not enforced anywhere

Humans catch these mistakes by probing and correcting assumptions.
LLMs don’t, unless you give them a reliable reference.

---

What URS does

URS produces a single specification grounded in evidence from the repository itself.

It makes three things explicit:

1. What’s enforced — validators, schemas, guards, limits
2. What’s convention — relied on but not checked
3. What’s unknown — cannot be determined from artifacts

If it’s not in the URS, it’s not guaranteed.

---

When to use URS

Use it when:

• LLMs modify code, run queries, or orchestrate workflows
• Misunderstanding system behavior would cause real damage
• The system has state, schemas, or multi-step execution

Skip it when:

• The repo has a single obvious entrypoint
• A human reviews every LLM action in detail
• A README already fully answers “what does this do?”

---

How it works

URS is produced in two passes.

Pass 1: Derive from artifacts

• Inspect code, schemas, tests, configs—not docs
• Record observed behavior
• Mark gaps and unknowns explicitly

Output is exhaustive and raw.

Pass 2: Reconcile with documentation

• Edit for clarity and structure
• No new facts
• Label enforced behavior vs. convention vs. doc-only claims

The result is a spec you can hand to an LLM with “read this first.”

---

In practice

URSs are typically generated by an LLM after traversing the repository’s artifacts, followed by human review.

In the examples here, the initial pass took a few minutes.
The human role was verification and distillation, not discovery.

---

What’s in this repo

Template

• URS_TEMPLATE.txt — the v1 URS template

Examples

• examples/reddit-fetcher/ — a completed URS for a production data pipeline
• examples/llm-sql/ — an evaluative example testing whether an LLM follows the two-pass workflow, in isolation and end-to-end

---

Authority model

Code > docs.

• If code enforces it, it’s binding
• If docs claim it but code doesn’t check, it’s convention
• Unknowns stay unknown

No inference. No gaps filled.

---

Summary

URS forces repositories to describe what they do, not what they wish they did.

---

Prompting model

The URS template is designed to be self-explanatory.

In practice, generating a URS requires only a minimal instruction to the LLM:

• where the repository is,
• which template to follow,
• where to write the output.

The template enforces ordering and separation of concerns; the prompt adds no logic.

Example: “Follow the URS template in this repo and write the completed spec to /docs.”