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
- Determine the parent type — business context → BRD-REF; architecture
context → ADR-REF.
- Allocate the next number —
ls docs/01_BRD/*-REF-* 2>/dev/null (or
05_ADR) and take the next free NN.
- 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.
- Place the file in the parent type directory with the correct H1.
Required sections (4, mandatory)
- YAML frontmatter (
artifact_type: REF).
- Document Control (version, date, author, status).
- Document Revision History.
- 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
1---
2name: doc-ref
3description: 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.
4metadata:
5 tags:
6 - sdd-workflow
7 - utility
8 custom_fields:
9 skill_category: utility
10 upstream_artifacts: [BRD, ADR]
11 downstream_artifacts: []
12 version: "0.25.0"
13 framework_spec_version: "0.51.0"
14 last_updated: "2026-05-23"
15---
16
17# doc-ref
18
19## Purpose
20
21Create **Reference Documents (REF)** — free-format supplementary documents that
22support a **BRD or ADR** without participating in the formal traceability
23chain. REF documents provide context (overviews, summaries, guides); they carry
24no element IDs, cumulative tags, ready-scores, or quality gates.
25
26**Layer**: cross-cutting utility — REF documents are limited to **BRD and ADR
27parent types only**.
28
29## When to Use
30
31**Use** `doc-ref` for supplements such as:
32
33- **BRD-REF** — project overviews, executive summaries, strategic vision,
34 stakeholder guides.
35- **ADR-REF** — technology-stack summaries, architecture overviews,
36 infrastructure guides.
37
38**Do NOT use** for: anything that should participate in traceability; core
39artifacts (BRD/PRD/EARS/BDD/ADR/SPEC/TDD/IPLAN — use their `doc-*` skills); or
40any parent type other than BRD or ADR.
41
42## Behavior
43
44### Naming and location
45
46- File name: `{TYPE}-REF-NN_{slug}.md` (`TYPE` ∈ {BRD, ADR}); H1:
47 `# {TYPE}-REF-NN: Title`.
48- `NN` is a variable-length sequence (2+ digits), independent per parent type:
49 `BRD-REF-01`, `BRD-REF-102`, `ADR-REF-01` are separate sequences.
50- Located inside the parent type directory, e.g.
51 `docs/01_BRD/BRD-REF-01_project_overview.md`,
52 `docs/05_ADR/ADR-REF-01_technology_stack_summary.md`.
53- Regex — file: `^(BRD|ADR)-REF-[0-9]{2,}_[a-z0-9_]+\.md$`;
54 H1: `^#\s(BRD|ADR)-REF-[0-9]{2,}:.+$`.
55
56### Creation process
57
581. **Determine the parent type** — business context → BRD-REF; architecture
59 context → ADR-REF.
602. **Allocate the next number** — `ls docs/01_BRD/*-REF-* 2>/dev/null` (or
61 `05_ADR`) and take the next free `NN`.
623. **Draft from the parent template, stripped to REF essentials** — start from
63 `${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml` (BRD-REF) or
64 `${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml` (ADR-REF) and keep only the four
65 mandatory sections, dropping the traceability scaffolding.
664. **Place** the file in the parent type directory with the correct H1.
67
68### Required sections (4, mandatory)
69
701. YAML frontmatter (`artifact_type: REF`).
712. Document Control (version, date, author, status).
723. Document Revision History.
734. Introduction (purpose and scope).
74
75Optional: Related Documents (cross-references encouraged) and any content
76sections the reference material needs.
77
78### Validation (this skill is the validator)
79
80Blocking checks only: H1 matches `{TYPE}-REF-NN: Title`; Document Control,
81Revision History, and Introduction sections are present. **Exempt** (not
82checked): cumulative tags, full traceability, quality gates, ready-scores —
83REF documents do not participate in the chain. No element IDs apply.
84
85## Related Resources
86
87- Parent templates: `${CLAUDE_PLUGIN_ROOT}/framework/layers/01_BRD/BRD-TEMPLATE.yaml`,
88 `${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml`
89- Naming authority: `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md` ·
90 `../doc-naming/SKILL.md`
91- Governance & per-layer authority: `${CLAUDE_PLUGIN_ROOT}/framework/governance/` and each
92 `${CLAUDE_PLUGIN_ROOT}/framework/layers/NN_<X>/README.md`
93- Parent skills: `../doc-brd/SKILL.md` · `../doc-adr/SKILL.md`
94- Workflow routing: `../doc-flow/SKILL.md`
95- Diagrams: `../charts-flow/SKILL.md`
vladm3105