doc-ref

Purpose

Create Reference Documents (REF) - supplementary documentation for BRD and ADR artifact types in the SDD framework. REF documents provide supporting information without participating in the formal traceability chain.

Layer: Not applicable (supplementary to any layer)

Traceability: Optional (encouraged but not required)

Validation: Minimal (non-blocking)

Naming Convention

Format: {TYPE}-REF-DOC_NUM_{slug}.md

Component	Description	Example
{TYPE}	Parent artifact type	BRD or ADR only
REF	Reference document indicator	REF
DOC_NUM	Variable-length sequence (2+ digits)	01, 02, 100, 1000
{slug}	Descriptive slug (snake_case)	project_overview

Scope: REF documents are LIMITED to BRD and ADR artifact types ONLY.

Examples:

• BRD-REF-01_project_overview.md - Business context
• BRD-REF-02_strategic_vision.md - Strategic vision
• ADR-REF-01_technology_stack_summary.md - Tech overview
• ADR-REF-02_infrastructure_guide.md - Infrastructure reference

Numbering: Independent sequence per parent TYPE (variable-length: 01-99, 100-999, 1000+)

• BRD-REF-01, BRD-REF-02 (BRD sequence)
• ADR-REF-01, ADR-REF-02 (ADR sequence - separate from BRD)

Location: Within parent TYPE directory

• docs/BRD/BRD-REF-01_project_overview.md
• docs/ADR/ADR-REF-01_technology_stack_summary.md

When to Use This Skill

Use doc-ref when creating supplementary documentation that:

• BRD-REF: Project overviews, executive summaries, strategic vision, stakeholder guides
• ADR-REF: Technology stack summaries, architecture overviews, infrastructure guides

Do NOT use doc-ref for:

• Documents that should participate in traceability chain
• Core artifacts (BRD, PRD, REQ, ADR, SPEC, etc.)
• Documents requiring validation gates
• Any parent type other than BRD or ADR (REF is limited to these two types)

Template Reference

Template: ai_dev_flow/REF-TEMPLATE.md

Required Sections (4 Mandatory)

1. YAML Frontmatter - Metadata with artifact_type: REF
2. Document Control - Version, date, author, status
3. Document Revision History - Change tracking
4. Introduction - Purpose and scope

Optional Sections

• Related Documents - Cross-references (traceability encouraged)
• Content sections - As needed for the specific reference material

Creation Process

Step 1: Determine Parent Type

Identify which artifact type this reference document supports (BRD or ADR only):

• Business context → BRD-REF-NN
• Architecture context → ADR-REF-NN

Step 2: Check Existing REF Documents

# List existing REF documents for the parent type
ls docs/BRD/*-REF-*.md 2>/dev/null    # For BRD references
ls docs/ADR/*-REF-*.md 2>/dev/null    # For ADR references

Step 3: Allocate Next Number

# Find highest REF number for parent type
ls docs/BRD/*-REF-*.md 2>/dev/null | sort -V | tail -1

Step 4: Create Document

1. Copy template: ai_dev_flow/REF-TEMPLATE.md
2. Rename to: {TYPE}-REF-NN_{slug}.md (NN = next sequence number, 2+ digits)
3. Update H1 heading: # {TYPE}-REF-NN: [Document Title]
4. Fill Document Control section
5. Write Introduction
6. Add content sections as needed
7. [Optional] Add Related Documents section

Step 5: Place Document

Save in parent TYPE directory:

docs/{TYPE}/{TYPE}-REF-NN_{slug}.md

Element IDs (Not Applicable)

REF documents are free-format supplementary documents and do NOT use element IDs:

• No element type codes (01-31 codes from ID_NAMING_STANDARDS.md do not apply)
• No sub-element IDs (no TYPE.NN.TT.SS pattern)
• Content sections can be organized freely without formal ID structure

Rationale: REF documents serve as reference targets that other documents link to. They provide supporting information but do not define formal requirements or architecture decisions requiring element-level traceability.

Validation Rules

Required (Blocking)

Check	Description
H1 ID Match	H1 must match pattern {TYPE}-REF-NN: Title
Document Control	Must have Document Control section
Revision History	Must have Document Revision History
Introduction	Must have Introduction section

Exempted (Not Checked)

Check	Reason
Cumulative Tags	REF docs don't participate in traceability chain
Full Traceability	Traceability is optional
Quality Gates	Non-blocking validation
SPEC-Ready Score	Not applicable

Common Use Cases

1. Project Overview (BRD-REF)

General project description for stakeholders:

# BRD-REF-01: Project Overview

## Document Control
...

## 1. Introduction

This document provides a high-level overview of the project for stakeholder reference...

2. Strategic Vision (BRD-REF)

Strategic roadmap and vision:

# BRD-REF-02: Strategic Vision

## Document Control
...

## 1. Introduction

This document outlines the strategic vision and roadmap for the project...

3. Technology Summary (ADR-REF)

Consolidated architecture reference:

# ADR-REF-01: Technology Stack Summary

## Document Control
...

## 1. Introduction

This document summarizes the technology decisions documented across ADRs...

4. Infrastructure Guide (ADR-REF)

Infrastructure reference documentation:

# ADR-REF-02: Infrastructure Guide

## Document Control
...

## 1. Introduction

Reference guide for infrastructure components and deployment architecture...

Ready-Score Exemptions

REF documents are EXEMPT from ALL ready-scores and quality gates:

Aspect	Standard Document	REF Document
PRD-Ready Score (BRD-REF)	Required ≥90%	NOT APPLICABLE
SYS-Ready Score (ADR-REF)	Required ≥90%	NOT APPLICABLE
Cumulative Tags	Required per layer	NOT REQUIRED
Quality Gates	Full validation	EXEMPT
Format	Structured sections	Free format

Comparison: REF vs Regular Artifacts

Aspect	Regular Artifacts	REF Documents
Traceability	Required (cumulative tags)	Optional
Validation	Full (blocking)	Minimal (4 checks only)
Quality Gates	Must pass	Exempt
Workflow Position	Defined layer	No layer
Numbering	TYPE-NN	{TYPE}-REF-NN
Valid Parent Types	All artifact types	BRD and ADR only

Diagram Standards

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: ai_dev_flow/DIAGRAM_STANDARDS.md and mermaid-gen skill.

Related Resources

• Template: ai_dev_flow/REF-TEMPLATE.md
• Naming Standards: ai_dev_flow/ID_NAMING_STANDARDS.md
• Validation: ai_dev_flow/scripts/validate_artifact.py

Regex Validation Patterns

Filename Pattern

^(BRD|ADR)-REF-[0-9]{2,}_[a-z0-9_]+\.md$

Valid: BRD-REF-01_project_overview.md, ADR-REF-100_technology_stack.md Invalid: PRD-REF-01_features.md (PRD not allowed), BRD-REF-1_overview.md (single digit)

H1 ID Pattern

^#\s(BRD|ADR)-REF-[0-9]{2,}:.+$

Valid: # BRD-REF-01: Project Overview, # ADR-REF-100: Technology Stack Summary Invalid: # REQ-REF-01: Requirements Reference (REQ not allowed)

Quick Reference

• Format: {TYPE}-REF-NN_{slug}.md
• DOC_NUM: Variable-length (2+ digits: 01-99, 100-999, 1000+)
• Valid Parent Types: BRD and ADR only
• Required Sections: Document Control, Revision History, Introduction
• Traceability: Optional (encouraged but not required)
• Validation: Minimal (non-blocking, 4 checks only)
• Element IDs: NOT APPLICABLE - REF documents use free format
• Ready-Scores: NOT APPLICABLE - no quality gate enforcement

Version History

Version	Date	Changes
1.1	2025-12-29	Fixed DOC_NUM to variable-length (was NNN 3-digit); Added Element IDs section; Added Regex Validation; Updated examples
1.0	2025-11-30	Initial skill creation