Readable References

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 are referenced elsewhere. Assume the source doc is whatever it is; your job is to make the reference readable.

What counts as an opaque reference

The litmus test: would a competent teammate know what this points to without opening another document? If no, it's opaque — expand it.

Common forms (fuller catalog in references/formats.md):

• Section / requirement numbers — 3.1, 4.2.1
• Prefixed requirement IDs — FR001, NFR-12, RD-XAT1, REQ-045
• Phases / milestones — Phase 2B, P3b, Milestone 3, M2
• Task-breakdown items — Task 3, P3b Task 3, Step 4
• Tracker keys used as bare shorthand in prose — CAI-569 (already linkable, but still needs a title so the reader isn't clicking blind)

Do not expand things that are already self-describing, or real code symbols — a function name, a variable, a file name. The signal is whether the token points into a planning artifact (spec, plan, requirements, design doc, task list), not into the code itself.

Workflow

Run this the moment you're about to write a plan pointer for a human. It's a writing reflex, not a separate pass at the end.

1. Detect

Flag the token with the litmus test above. If a reader would have to look it up, continue.

2. Recover the title and the source (provenance)

You emitted this identifier because it came from somewhere in your working context — a spec file you read, a plan you generated, a Notion doc, a Jira issue. That source holds the exact title.

• Title is in context → use the exact wording from the source. Don't paraphrase it into a new title; the reader may search for it.
• Title is not in context → trace it back. Find where the reference came from: grep the repo for the ID, re-open the plan or spec, search the doc store you loaded it from. Recover the real title before you write the reference.
• Can't find it anywhere → this is a signal you're referencing something you can't substantiate. Say that plainly ("I can't locate the source for FR001 — where is it defined?") rather than emitting a bare, unverifiable code. Don't invent a title.

3. Build the link from provenance

The link points to wherever you got the identifier, and only if the reader can reach it:

• In-repo spec, referenced inside a PR on that repo → repo-relative path + heading anchor, or the canonical repo file URL.
• Notion-sourced → the Notion page/block URL.
• Jira / Confluence / GitHub issue → the item URL or key link.
• The medium can't render a link, or the reader can't reach the target → skip the link, keep the title (step 5 fallback).

Match the destination to context — don't link a private doc into a public PR the reader can't open. When unsure the reader can reach it, prefer the title alone.

4. Write it in the medium's format

Format depends on where it's going. Full rules and examples in references/formats.md:

• Markdown surfaces (PR text, ADR/README/docs, Notion, chat that renders markdown) → [3.1: User Login via Social](link)
• Code comments / docstrings (markdown usually won't render) → Requirement 3.1 (User Login via Social) — docs/specs/auth.md#requirement-31 with the path as bare, clickable, greppable text, not [...](...) syntax.
• Commit messages → expand to the title inline; put the source on a trailer line (Spec: docs/specs/auth.md#requirement-31).
• Plain chat / email → expand to title; add the URL only if the recipient can open it.

5. Fallback when there's no link

Best-effort always beats a bare code. If you can't produce a working link, still write the title: Requirement 3.1: User Login via Social. A titled reference with no link is readable; a bare 3.1 is not.

First mention vs. repeats

Expand and link on the first mention in a given artifact. After that, within the same short message or comment, the title-bearing short form ("Requirement 3.1") is enough — don't re-link the same item five times in one comment; that's its own kind of noise. A new artifact (a different PR comment, a new commit) starts over with the full expansion.

Examples

PR review comment Input: 3.1 is satisfied by this design Output: [Requirement 3.1: User Login via Social](docs/specs/auth.md#requirement-31) is satisfied by this design

Source-code comment (no markdown link) Input: // implements FR001 Output: // implements FR001 (Password reset via email) — docs/specs/auth.md#fr001

Commit message Input: Complete Phase 2B Output:

Complete Phase 2B (Billing integration hardening)

Plan: .ai/docs/plans/billing.md#phase-2b

Slack message to a teammate Input: P3b Task 3 is blocked Output: [P3b Task 3: Add retry to the webhook consumer](link) is blocked (or, if the thread doesn't render markdown / the link isn't reachable, P3b Task 3 (Add retry to the webhook consumer) is blocked)

Guardrails

• Never emit a bare plan pointer to a human. Title at minimum; title + link when you can.
• Don't fabricate the title. Use the source's exact wording, or trace it; never guess.
• Keep the ID. Expand, don't replace — the ID is the traceability handle back to the plan.
• Don't over-expand. Code symbols, file names, and self-describing terms are not plan pointers. Leave them alone.
• Respect reach. Only link a source the reader can open; otherwise fall back to the title.