doc-ref

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

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

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

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)

Exempted (Not Checked)

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:

Comparison: REF vs Regular Artifacts

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