---
name: doc-ref
description: Create Reference Documents (REF) - free-format supplements for BRD and ADR that sit outside the formal traceability chain. Use for project overviews, strategic vision, or technology/infrastructure summaries.
metadata:
  tags:
    - sdd-workflow
    - utility
  custom_fields:
    skill_category: utility
    upstream_artifacts: [BRD, ADR]
    downstream_artifacts: []
    version: "0.24.0"
    framework_spec_version: "0.40.0"
    last_updated: "2026-05-23"
---

# doc-ref

## Purpose

Create **Reference Documents (REF)** — free-format supplementary documents that
support a **BRD or ADR** without participating in the formal traceability
chain. REF documents provide context (overviews, summaries, guides); they carry
no element IDs, cumulative tags, ready-scores, or quality gates.

**Layer**: cross-cutting utility — REF documents are limited to **BRD and ADR
parent types only**.

## When to Use

**Use** `doc-ref` for supplements such as:

- **BRD-REF** — project overviews, executive summaries, strategic vision,
  stakeholder guides.
- **ADR-REF** — technology-stack summaries, architecture overviews,
  infrastructure guides.

**Do NOT use** for: anything that should participate in traceability; core
artifacts (BRD/PRD/EARS/BDD/ADR/SPEC/TDD/IPLAN — use their `doc-*` skills); or
any parent type other than BRD or ADR.

## Behavior

### Naming and location

- File name: `{TYPE}-REF-NN_{slug}.md` (`TYPE` ∈ {BRD, ADR}); H1:
  `# {TYPE}-REF-NN: Title`.
- `NN` is a variable-length sequence (2+ digits), independent per parent type:
  `BRD-REF-01`, `BRD-REF-102`, `ADR-REF-01` are separate sequences.
- Located inside the parent type directory, e.g.
  `docs/01_BRD/BRD-REF-01_project_overview.md`,
  `docs/05_ADR/ADR-REF-01_technology_stack_summary.md`.
- Regex — file: `^(BRD|ADR)-REF-[0-9]{2,}_[a-z0-9_]+\.md$`;
  H1: `^#\s(BRD|ADR)-REF-[0-9]{2,}:.+$`.

### Creation process

1. **Determine the parent type** — business context → BRD-REF; architecture
   context → ADR-REF.
2. **Allocate the next number** — `ls docs/01_BRD/*-REF-* 2>/dev/null` (or
   `05_ADR`) and take the next free `NN`.
3. **Draft from the parent template, stripped to REF essentials** — start from
   `${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml` (BRD-REF) or
   `${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml` (ADR-REF) and keep only the four
   mandatory sections, dropping the traceability scaffolding.
4. **Place** the file in the parent type directory with the correct H1.

### Required sections (4, mandatory)

1. YAML frontmatter (`artifact_type: REF`).
2. Document Control (version, date, author, status).
3. Document Revision History.
4. Introduction (purpose and scope).

Optional: Related Documents (cross-references encouraged) and any content
sections the reference material needs.

### Validation (this skill is the validator)

Blocking checks only: H1 matches `{TYPE}-REF-NN: Title`; Document Control,
Revision History, and Introduction sections are present. **Exempt** (not
checked): cumulative tags, full traceability, quality gates, ready-scores —
REF documents do not participate in the chain. No element IDs apply.

## Related Resources

- Parent templates: `${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml`,
  `${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml`
- Naming authority: `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md` ·
  `../doc-naming/SKILL.md`
- Governance & per-layer authority: `${CLAUDE_PLUGIN_ROOT}/framework/governance/` and each
  `${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md`
- Parent skills: `../doc-brd/SKILL.md` · `../doc-adr/SKILL.md`
- Workflow routing: `../doc-flow/SKILL.md`
- Diagrams: `../charts-flow/SKILL.md`