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) YAML Frontmatter - Metadata with artifact_type: REF Document Control - Version, date, author, status Document Revision History - Change tracking 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
ID Numbering Convention: Start with 2 digits and expand only as needed.
✅ Correct: BRD-REF-01, ADR-REF-99, BRD-REF-102 ❌ Incorrect: BRD-REF-001, ADR-REF-009 (extra leading zero not required) Step 4: Create Document Copy template: ai_dev_flow/REF-TEMPLATE.md Rename to: {TYPE}-REF-NN_{slug}.md (NN = next sequence number, 2+ digits) Update H1 heading: # {TYPE}-REF-NN: [Document Title] Fill Document Control section Write Introduction Add content sections as needed [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...
- 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...
- 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...
- 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