readable-referenceslisted

# Readable References ## The problem this solves An opaque reference is a pointer with no text attached. "3.1 is satisfied by this design" is a footnote marker with the footnote torn off. The writer knew what 3.1 meant; the reader — a teammate skimming a PR, or the same writer three weeks later — does not, and now has to stop, find the spec, and look it up. Every bare `FR001`, `Phase 2B`, or `P3b Task 3` in a PR comment or code comment spends the reader's time to save the writer's. These identifiers are cheap for an agent to emit because the agent still has the plan in context. The reader never does. Write for the reader who is missing that context. **The fix:** at the moment you would write a bare plan identifier for a human, expand it to carry its own meaning — the ID plus its title — and link it to the source it came from. ``` 3.1 is satisfied by this design → [Requirement 3.1: User Login via Social](docs/specs/auth.md#requirement-31) is satisfied by this design ``` Keep the ID *and* add the title. The ID preserves traceability to the plan; the title makes it readable without leaving the page. ## When it applies Apply to any human-facing output that would otherwise contain a bare plan pointer: - PR / MR descriptions and review comments - Source-code comments and docstrings - Commit messages - Task / ticket updates, ADRs, READMEs, generated docs - Slack, email, or chat messages to a person It does **not** govern how specs are authored — only how their identifiers