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...

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 |