# Readable References > Replace opaque spec/plan/requirement pointers with self-describing, linked references whenever writing for a human. Use this skill whenever you are about to write an identifier that points into a spec, plan, requirements doc, design doc, or task breakdown — a section number like 3.1 or 4.2.1, a requirement ID like FR001 / NFR-12 / RD-XAT1 / REQ-045, a phase or milestone like Phase 2B / P3b / Milestone 3, or a task like "P3b Task 3" — into a PR description or review comment, a source-code comment or docstring, a commit message, a task or ticket update, an ADR / README / generated doc, or any Slack/email/chat message to a person. Instead of emitting the bare code (which forces the reader to leave and hunt for its meaning), expand it to include its human-readable title and hyperlink it to the source it came from — e.g. "[Requirement 3.1: User Login via Social](link) is satisfied by this design" rather than "3.1 is satisfied by this design". Trigger even when the user never mentions links or references — any time - Skill: `ebellefontaine/readable-references` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ebellefontaine/readable-references` - Raw SKILL.md: https://api.skillmd.com/api/skills/ebellefontaine/readable-references/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: ebellefontaine (https://skillmd.com/u/ebellefontaine) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ebellefontaine/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.