Skills
▥NYC
skills/vladm3105/aidoc-flow-framework/doc-naming

doc-naming

SKILL.md

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 11 SDD documentation artifact types (Layers 1-11):

Layer Document Type Description
1 BRD Business Requirements Document
2 PRD Product Requirements Document
3 EARS Easy Approach to Requirements Syntax
4 BDD Behavior-Driven Development
5 ADR Architecture Decision Record
6 SYS System Requirements
7 REQ Atomic Requirements
8 CTR Data Contracts
9 SPEC Technical Specifications
10 TSPEC Test Specifications (UTEST, ITEST, STEST, FTEST)
11 TASKS AI Task Breakdown

Note: Layers 12-14 (CODE, TESTS, VALIDATION) are execution layers, not documentation artifacts.

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

Scope

Documents with reserved ID 000 are FULLY EXEMPT from standard validation.

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_* pattern.

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

Document ID Valid Reason
BRD-01 ✅ Correct format
PRD-02 ✅ Correct format
ADR-001 ✅ 3-digit ID allowed
TASKS-12 ✅ Correct format
brd-01 ❌ Lowercase not allowed
PRD_02 ❌ Underscore not allowed
BRD-1 ❌ Single digit not allowed
BRD01 ❌ Missing dash separator

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:

Component Pattern Example
H1 ID {TYPE}-REF-NN # BRD-REF-01: Project Overview
Filename {TYPE}-REF-NN_{slug}.md BRD-REF-01_project_overview.md
Location Within parent TYPE directory 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}
Segment Description Format
DOC_TYPE Document type acronym 2-5 uppercase letters
DOC_NUM Document number 2+ digits
ELEM_TYPE Element type code 2+ digits (01-31)
SEQ Sequential number 2+ digits

Validation Regex

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

Examples

Element ID Valid Breakdown
BRD.02.06.01 ✅ BRD doc 02, Acceptance Criteria (06), item 01
PRD.01.09.03 ✅ PRD doc 01, User Story (09), item 03
ADR.05.10.01 ✅ ADR doc 05, Decision (10), item 01
SPEC.03.16.02 ✅ SPEC doc 03, Interface (16), item 02
AC-001 ❌ Legacy pattern - use TYPE.NN.06.SS
FR-01 ❌ Legacy pattern - use TYPE.NN.01.SS
BRD-02-06-01 ❌ Wrong separator (use dots)
brd.02.06.01 ❌ Lowercase not allowed

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

Active element type codes with document type applicability:

Code Element Type Applicable Document Types
01 Functional Requirement BRD, PRD, SYS, REQ
02 Quality Attribute BRD, PRD, SYS
03 Constraint BRD, PRD
04 Assumption BRD, PRD
05 Dependency BRD, PRD, REQ
06 Acceptance Criteria BRD, PRD, REQ
07 Risk BRD, PRD
08 Metric BRD, PRD
09 User Story PRD, BRD
10 Decision ADR, BRD
11 Use Case PRD, SYS
12 Alternative ADR
13 Consequence ADR
14 Test Scenario BDD
15 Step BDD, SPEC
16 Interface SPEC, CTR
17 Data Model SPEC, CTR
18 Task TASKS
20 Contract Clause CTR
21 Validation Rule SPEC
22 Feature Item BRD, PRD
23 Business Objective BRD
24 Stakeholder Need BRD, PRD
25 EARS Statement EARS
26 System Requirement SYS
27 Atomic Requirement REQ
28 Specification Element SPEC
30 Task Item TASKS
32 Architecture Topic BRD
33 Benefit Statement BRD
40 Unit Test Case TSPEC (UTEST)
41 Integration Test Case TSPEC (ITEST)
42 Smoke Test Case TSPEC (STEST)
43 Functional Test Case TSPEC (FTEST)

Quick Lookup by Document Type

Document Common Element Codes
BRD 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 22, 23, 24, 32, 33
PRD 01, 02, 03, 04, 05, 06, 07, 08, 09, 11, 22, 24
EARS 25
BDD 14, 15
ADR 10, 12, 13
SYS 01, 02, 11, 26
REQ 01, 05, 06, 27
CTR 16, 17, 20
SPEC 15, 16, 17, 21, 28
TSPEC 40 (UTEST), 41 (ITEST), 42 (STEST), 43 (FTEST)
TASKS 18, 30

6. Removed/Legacy Patterns

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

Removed Pattern Migration Path Applies To
AC-XXX TYPE.NN.06.SS BRD, PRD, REQ
FR-XXX TYPE.NN.01.SS BRD, PRD, SYS, REQ
BC-XXX TYPE.NN.03.SS BRD, PRD
BA-XXX TYPE.NN.04.SS BRD, PRD
QA-XXX TYPE.NN.02.SS BRD, PRD, SYS
BO-XXX TYPE.NN.23.SS BRD
RISK-XXX TYPE.NN.07.SS BRD, PRD
METRIC-XXX TYPE.NN.08.SS BRD, PRD
Feature F-XXX TYPE.NN.22.SS BRD, PRD
Event-XXX TYPE.NN.25.SS EARS
State-XXX TYPE.NN.25.SS EARS
TASK-XXX TYPE.NN.18.SS TASKS
T-XXX TYPE.NN.18.SS TASKS
IF-XXX TYPE.NN.16.SS CTR
DM-XXX TYPE.NN.17.SS CTR
CC-XXX TYPE.NN.20.SS CTR
DEC-XXX TYPE.NN.10.SS ADR
ALT-XXX TYPE.NN.12.SS ADR
CON-XXX TYPE.NN.13.SS ADR

Migration Examples

Legacy Unified Format
### 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
### 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

Category Description Example Keys
perf Performance metrics perf.latency.p99
timeout Timeout values timeout.api.request
rate Rate limits rate.api.requests_per_second
retry Retry policies retry.max_attempts
circuit Circuit breaker circuit.failure_threshold
alert Alerting thresholds alert.error_rate.critical
cache Cache settings cache.ttl.session
pool Connection pools pool.max_connections
queue Queue settings queue.max_size
batch Batch processing batch.size.max

Examples

Threshold Tag Valid Breakdown
@threshold: PRD.035.timeout.partner.bridge ✅ PRD doc 035, timeout category
@threshold: BRD.02.perf.latency.p99 ✅ BRD doc 02, performance category
@threshold: ADR.05.circuit.failure_threshold ✅ ADR doc 05, circuit breaker
@threshold: timeout.partner.bridge ❌ Missing doc reference
@threshold: PRD-035.timeout ❌ Wrong separator (dash vs dot)

Source Documents for Thresholds

Doc Type Threshold Scope
BRD Business-level thresholds (SLAs, business rules)
PRD Product-level thresholds (user experience, product metrics)
ADR Technical thresholds (architecture decisions, system limits)

8. ISO 8601 Datetime Format Standard

Purpose

All date and time fields in SDD documentation MUST use ISO 8601 datetime format for:

  • Accurate upstream drift detection (same-day change tracking)
  • Consistent timestamp comparison across tools
  • Timezone-aware change tracking
  • File system mtime compatibility

Format Specification

Required Format: YYYY-MM-DDTHH:MM:SS (ISO 8601 with time)

Component Format Example
Date YYYY-MM-DD 2026-02-10
Separator T T
Time HH:MM:SS 14:30:00
Timezone (optional) Z or ±HH:MM Z (UTC) or +05:00

Full Format Options

Format Example Use Case
Local time 2026-02-10T14:30:00 Default for most documents
UTC 2026-02-10T14:30:00Z Cross-timezone systems
With offset 2026-02-10T14:30:00+05:00 Explicit timezone

YAML Frontmatter Fields

All datetime fields in YAML frontmatter use ISO 8601:

---
title: "BRD-01: Example Document"
custom_fields:
  created_date: "2026-02-10T09:15:00"
  last_updated: "2026-02-10T14:30:00"
  review_date: "2026-02-10T16:45:00"
  fix_date: "2026-02-10T17:00:00"
  approval_date: "2026-02-11T10:00:00"
---

Affected Fields

Field Description Location
last_updated Document last modification time YAML frontmatter
created_date Document creation time YAML frontmatter
fix_date Fix report creation time Fix reports
review_date Review execution time Review reports
approval_date Document approval time Document control
decision_date ADR decision time ADR documents
release_date Release/deployment time CTR, SPEC

Migration from Date-Only Format

Deprecated (date-only):

last_updated: "2026-02-10"

Required (ISO 8601 datetime):

last_updated: "2026-02-10T14:30:00"

Validation Regex

^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})?$

Placeholder Format

For templates, use YYYY-MM-DDTHH:MM:SS as placeholder:

# Template placeholder (to be replaced during generation)
last_updated: "YYYY-MM-DDTHH:MM:SS"

# After generation
last_updated: "2026-02-10T14:30:00"

Drift Detection Benefit

ISO 8601 datetime enables same-day drift detection:

BRD Modified PRD Created Date-Only Detection Datetime Detection
2026-02-10T10:00:00 2026-02-10T08:00:00 ❌ Same day, no drift ✅ Drift detected (BRD newer)
2026-02-10T08:00:00 2026-02-10T10:00:00 ❌ Same day, no drift ✅ No drift (PRD is newer)

Auto-Generation

When generating documents, use current timestamp:

from datetime import datetime

# Generate ISO 8601 timestamp
timestamp = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
# Result: "2026-02-10T14:30:00"

# With UTC
timestamp_utc = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
# Result: "2026-02-10T09:30:00Z"

9. 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
### BRD.02.32.01: Infrastructure Architecture Topic
### BRD.02.32.02: Data Architecture Topic
### BRD.02.33.01: Cost Reduction Benefit
### BRD.02.33.02: Efficiency Improvement Benefit
@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

TSPEC Examples

### TSPEC.01.40.01: User Authentication Unit Test
### TSPEC.01.41.01: API Integration Test
### TSPEC.01.42.01: Login Flow Smoke Test
### TSPEC.01.43.01: Order Processing Functional Test

TASKS Examples

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

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

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

Error Cause Fix
Wrong element code Using FR code (01) for Acceptance Criteria Use code 06 for AC
Missing document number BRD..06.01 Include document number: BRD.02.06.01
Dash instead of dot BRD-02-06-01 Use dots: BRD.02.06.01
Lowercase type brd.02.06.01 Uppercase: BRD.02.06.01

12. Source References

Primary Sources

Document Location Content
ID Naming Standards ai_dev_flow/ID_NAMING_STANDARDS.md Document IDs, Element IDs, 31 type codes
Threshold Naming Rules ai_dev_flow/THRESHOLD_NAMING_RULES.md Threshold tags, key formats, categories

Validation Rules Files

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

Document Type Validation Rules File
BRD ai_dev_flow/01_BRD/BRD_VALIDATION_RULES.md
PRD ai_dev_flow/02_PRD/PRD_VALIDATION_RULES.md
EARS ai_dev_flow/03_EARS/EARS_VALIDATION_RULES.md
BDD ai_dev_flow/04_BDD/BDD_VALIDATION_RULES.md
ADR ai_dev_flow/05_ADR/ADR_VALIDATION_RULES.md
SYS ai_dev_flow/06_SYS/SYS_VALIDATION_RULES.md
REQ ai_dev_flow/07_REQ/REQ_VALIDATION_RULES.md
CTR ai_dev_flow/08_CTR/CTR_VALIDATION_RULES.md
SPEC ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md
TSPEC ai_dev_flow/10_TSPEC/TSPEC_VALIDATION_RULES.md
TASKS ai_dev_flow/11_TASKS/TASKS_VALIDATION_RULES.md

Related Skills

Skill Purpose
doc-validator Automated validation of SDD documents
doc-flow SDD workflow orchestration
trace-check Traceability validation

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.

Version History

Version Date Changes
1.6 2026-02-10 Added Section 8: ISO 8601 Datetime Format Standard - all date fields now require YYYY-MM-DDTHH:MM:SS format for precise drift detection; Deprecated date-only format
1.5 2026-02-10 Added element code 33 (Benefit Statement) for BRD Section 2.5; Updated BRD Quick Lookup to include code 33; Added BRD examples for code 33
1.4 2026-02-08 Added element code 32 (Architecture Topic) for BRD Section 7.2; Updated BRD Quick Lookup to include code 32; Added BRD examples for code 32
1.3 2026-02-08 Fixed layer assignments per LAYER_REGISTRY v1.6: CTR=8, SPEC=9, TSPEC=10, TASKS=11; Removed deprecated IMPL layer; Added TSPEC element codes 40-43; Updated folder paths to use numbered prefixes
1.2 2026-01-17 Updated to 11 active artifact types; Removed legacy element codes 19, 31
1.1 2025-12-29 Added Reserved ID Exemption, REF document pattern, ADR removed patterns, fixed element type codes for BRD
1.0 2025-12-19 Initial release with all 31 element codes and 18 removed patterns
Weekly Installs
18
Repository
vladm3105/aidoc-flow-framework
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
gemini-cli13
claude-code11
codex11
opencode10
antigravity10
cursor9