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/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/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_ssd_flow/DIAGRAM_STANDARDS.md and mermaid-gen skill.

Related Resources

• Template: ai_dev_flow/REF/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