doc-naming Skill

Enforces unified ID naming standards and threshold naming rules for all SDD documentation artifacts.

1. Purpose & Scope

When to Invoke

Invoke this skill BEFORE creating or editing any SDD documentation artifact. Use it to:

• Verify element ID format compliance
• Check for removed/legacy patterns
• Validate threshold tag syntax
• Ensure document ID format correctness

Coverage

This skill covers all 12 SDD document types:

2. Reserved ID Exemption (TYPE-00_*)

Scope

Documents with reserved ID

000

Pattern

{DOC_TYPE}-00_{slug}.{ext}

Document Types

• Index documents (e.g.,

  BRD-00_index.md

  ,

  REQ-00_index.md

  )
• Traceability matrix templates (e.g.,

  SPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md

  )
• Glossaries, registries, checklists

Rationale

Reserved ID 000 documents are framework infrastructure (indexes, templates, reference materials), not project artifacts requiring traceability or quality gates.

Validation Behavior

Skip all element ID and traceability checks when filename matches

{TYPE}-00_*

3. Document ID Format (TYPE-NN)

Pattern

TYPE-NN

• TYPE: Uppercase document type acronym (BRD, PRD, EARS, etc.)
• Separator: Single dash

  -

• NN: 2+ digit sequential number with leading zeros

Validation Regex

^[A-Z]{2,5}-[0-9]{2,}$

Examples

BRD-01

PRD-02

ADR-001

TASKS-12

brd-01

PRD_02

BRD-1

BRD01

Filename Convention

TYPE-NN_descriptive_slug.md

Example:

BRD-01_ib_stock_options_mcp_server.md

REF Document Pattern

Reference documents use a modified pattern within parent TYPE directories:

{TYPE}-REF-NN

# BRD-REF-01: Project Overview

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

BRD-REF-01_project_overview.md

docs/BRD/BRD-REF-01_project_overview.md

Notes:

• REF documents are supplementary and do not participate in formal traceability chain
• Similar exemption treatment as

  {TYPE}-000

  index documents
• Numbering is independent per parent TYPE (BRD-REF-01, ADR-REF-01 are separate sequences)

4. Element ID Format (TYPE.NN.TT.SS)

Pattern

{DOC_TYPE}.{DOC_NUM}.{ELEM_TYPE}.{SEQ}

Validation Regex

^[A-Z]{2,5}\.[0-9]{2,}\.[0-9]{2,}\.[0-9]{2,}$

Examples

BRD.02.06.01

PRD.01.09.03

ADR.05.10.01

SPEC.03.16.02

AC-001

FR-01

BRD-02-06-01

brd.02.06.01

Heading Format

Element IDs appear as markdown headings:

### BRD.02.06.01: User Authentication Acceptance Criteria
#### PRD.01.09.03: User Login Story

5. Element Type Codes Table

All 31 element type codes with document type applicability:

Quick Lookup by Document Type

6. Removed/Legacy Patterns

These patterns are DEPRECATED. Do NOT use them in new documents.

AC-XXX

TYPE.NN.06.SS

FR-XXX

TYPE.NN.01.SS

BC-XXX

TYPE.NN.03.SS

BA-XXX

TYPE.NN.04.SS

QA-XXX

TYPE.NN.02.SS

BO-XXX

TYPE.NN.23.SS

RISK-XXX

TYPE.NN.07.SS

METRIC-XXX

TYPE.NN.08.SS

Feature F-XXX

TYPE.NN.22.SS

Event-XXX

TYPE.NN.25.SS

State-XXX

TYPE.NN.25.SS

TASK-XXX

TYPE.NN.18.SS

T-XXX

TYPE.NN.18.SS

Phase-XXX

TYPE.NN.29.SS

IP-XXX

TYPE.NN.29.SS

IF-XXX

TYPE.NN.16.SS

DM-XXX

TYPE.NN.17.SS

CC-XXX

TYPE.NN.20.SS

DEC-XXX

TYPE.NN.10.SS

ALT-XXX

TYPE.NN.12.SS

CON-XXX

TYPE.NN.13.SS

Migration Examples

### AC-001: Login Validation

### BRD.02.06.01: Login Validation

#### FR-01: User Auth

#### PRD.01.01.01: User Auth

### Event-001: KYC Submission

### EARS.06.25.01: KYC Submission

### TASK-01: Setup

### TASKS.02.18.01: Setup

### Phase-01: Init

### IMPL.02.29.01: Init

### DEC-01: Use PostgreSQL

### ADR.05.10.01: Use PostgreSQL

### ALT-01: MongoDB Option

### ADR.05.12.01: MongoDB Option

7. Threshold Tag Format

Tag Pattern

@threshold: {DOC_TYPE}.{DOC_NUM}.{threshold_key}

Key Format

{category}.{subcategory}.{attribute}[.{qualifier}]

Valid Categories

perf.latency.p99

timeout.api.request

rate.api.requests_per_second

retry.max_attempts

circuit.failure_threshold

alert.error_rate.critical

cache.ttl.session

pool.max_connections

queue.max_size

batch.size.max

Examples

@threshold: PRD.035.timeout.partner.bridge

@threshold: BRD.02.perf.latency.p99

@threshold: ADR.05.circuit.failure_threshold

@threshold: timeout.partner.bridge

@threshold: PRD-035.timeout

Source Documents for Thresholds

8. Validation Examples by Document Type

BRD Examples

### BRD.02.01.01: User Authentication Requirement
### BRD.02.06.01: Login Acceptance Criteria
### BRD.02.23.01: Revenue Growth Objective
### BRD.02.09.01: User Onboarding Story
### BRD.02.10.01: Database Selection Decision
@threshold: BRD.02.perf.response_time.max

PRD Examples

### PRD.01.09.01: User Login Story
### PRD.01.22.01: Dashboard Feature
### PRD.01.06.01: Feature Acceptance Criteria
@threshold: PRD.01.timeout.session.idle

EARS Examples

#### EARS.06.25.01: KYC Submission Event
#### EARS.06.25.02: Pending Status State

ADR Examples

### ADR.05.10.01: Use PostgreSQL Decision
### ADR.05.12.01: MongoDB Alternative
### ADR.05.13.01: Migration Consequence
@threshold: ADR.05.circuit.failure_threshold

SPEC Examples

### SPEC.03.16.01: REST API Interface
### SPEC.03.17.01: User Data Model
### SPEC.03.21.01: Email Validation Rule

CTR Examples

### CTR.02.16.01: Partner API Interface
### CTR.02.17.01: Order Data Model
### CTR.02.20.01: Rate Limit Clause

TASKS Examples

### TASKS.02.18.01: Setup Development Environment
### TASKS.02.30.01: Configure CI Pipeline

IMPL Examples

### IMPL.02.29.01: Foundation Phase
### IMPL.02.29.02: Integration Phase

9. Pre-Flight Checklist

Run this checklist BEFORE creating any SDD document:

Document Setup

• Document ID follows

  TYPE-NN

  format
• Filename follows

  TYPE-NN_descriptive_slug.md

  pattern
• YAML frontmatter includes correct

  artifact_type

  and

  layer

• Not a reserved ID document (TYPE-00_*) requiring exemption

Element IDs

• All element IDs use 4-segment dot notation:

  TYPE.NN.TT.SS

• Element type code (TT) is valid for this document type (see Section 5)
• Sequential numbers (SS) are unique within the document
• No legacy patterns (AC-XXX, FR-XXX, DEC-XXX, etc.) are used

Threshold Tags

• All

  @threshold:

  tags include document reference:

  TYPE.NN.key

• Threshold keys follow category.subcategory.attribute format
• Categories are from the approved list (perf, timeout, rate, etc.)

Cross-References

• Traceability tags use correct prefixes (@brd:, @prd:, @adr:, etc.)
• Referenced document IDs exist
• Element ID references are complete (all 4 segments)

10. Error Recovery

Detecting Legacy Patterns

Use grep to find legacy patterns:

# Find all legacy patterns in a file
grep -E "(AC|FR|BC|BA|QA|BO|RISK|METRIC)-[0-9]+" file.md
grep -E "(Event|State|TASK|Phase|IP|IF|DM|CC)-[0-9]+" file.md
grep -E "(DEC|ALT|CON)-[0-9]+" file.md
grep -E "Feature F-[0-9]+" file.md
grep -E "T-[0-9]+" file.md

Migration Procedure

1. Identify the document type and number from the filename

   • Example:

     BRD-02_requirements.md

     → DOC_TYPE=BRD, DOC_NUM=02

2. Look up the element type code from Section 5

   • Example:

     AC-XXX

     → Acceptance Criteria → Code 06
   • Example:

     DEC-XXX

     → Decision → Code 10

3. Construct the unified ID

   • Pattern:

     {DOC_TYPE}.{DOC_NUM}.{ELEM_TYPE}.{SEQ}

   • Example:

     AC-001

     in BRD-02 →

     BRD.02.06.01

   • Example:

     DEC-01

     in ADR-05 →

     ADR.05.10.01

4. Replace all occurrences

   # Example sed replacement
   sed -i 's/### AC-001:/### BRD.02.06.01:/g' file.md
   sed -i 's/### DEC-01:/### ADR.05.10.01:/g' file.md
   

5. Validate the result

   # Verify no legacy patterns remain
   grep -E "(AC|FR|BC|BA|DEC|ALT|CON)-[0-9]+" file.md
   

Common Migration Errors

BRD..06.01

BRD.02.06.01

BRD-02-06-01

BRD.02.06.01

brd.02.06.01

BRD.02.06.01

11. Source References

Primary Sources

ai_dev_flow/ID_NAMING_STANDARDS.md

ai_dev_flow/THRESHOLD_NAMING_RULES.md

Validation Rules Files

Each document type has validation rules with Element ID compliance checks:

ai_dev_flow/BRD/BRD_VALIDATION_RULES.md

ai_dev_flow/PRD/PRD_VALIDATION_RULES.md

ai_dev_flow/EARS/EARS_VALIDATION_RULES.md

ai_dev_flow/BDD/BDD_VALIDATION_RULES.md

ai_dev_flow/ADR/ADR_VALIDATION_RULES.md

ai_dev_flow/SYS/SYS_VALIDATION_RULES.md

ai_dev_flow/REQ/REQ_VALIDATION_RULES.md

ai_dev_flow/IMPL/IMPL_VALIDATION_RULES.md

ai_dev_flow/CTR/CTR_VALIDATION_RULES.md

ai_dev_flow/SPEC/SPEC_VALIDATION_RULES.md

ai_dev_flow/TASKS/TASKS_VALIDATION_RULES.md

Related Skills

Diagram Standards

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See:

ai_dev_flow/DIAGRAM_STANDARDS.md

mermaid-gen

Version History