name	doc-naming
description	Enforces unified ID naming standards and threshold naming rules for all SDD documentation artifacts
tags	sdd-workflow, shared-architecture, quality-assurance, required-both-approaches
custom_fields	[object Object]

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:

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	IMPL	Implementation Approach
9	CTR	Data Contracts
10	SPEC	Technical Specifications
11	TASKS	AI Task Breakdown
12	IPLAN	Implementation Plans

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

Scope

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

Pattern

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

Document Types

Index documents (e.g., BRD-000_index.md, REQ-000_index.md)
Traceability matrix templates (e.g., SPEC-000_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}-000_* 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

All 31 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
19	Command	IPLAN
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
29	Implementation Phase	IMPL
30	Task Item	TASKS
31	Plan Step	IPLAN

Quick Lookup by Document Type

Document	Common Element Codes
BRD	01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 22, 23, 24
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
IMPL	29
CTR	16, 17, 20
SPEC	15, 16, 17, 21, 28
TASKS	18, 30
IPLAN	19, 31

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
`Phase-XXX`	`TYPE.NN.29.SS`	IMPL
`IP-XXX`	`TYPE.NN.29.SS`	IMPL
`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
`CMD-XXX`	`TYPE.NN.19.SS`	IPLAN
`STEP-XXX`	`TYPE.NN.31.SS`	IPLAN

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`
`### 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`
`### CMD-01: Install deps`	`### IPLAN.01.19.01: Install deps`

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

IPLAN Examples

### IPLAN.01.19.01: Initialize Repository
### IPLAN.01.31.01: Deploy to Staging

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-000_*) 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, CMD-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|CMD|STEP)-[0-9]+" file.md
grep -E "Feature F-[0-9]+" file.md
grep -E "T-[0-9]+" file.md

Migration Procedure

Identify the document type and number from the filename
- Example: BRD-02_requirements.md → DOC_TYPE=BRD, DOC_NUM=02
Look up the element type code from Section 5
- Example: AC-XXX → Acceptance Criteria → Code 06
- Example: DEC-XXX → Decision → Code 10
- Example: CMD-XXX → Command → Code 19
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
- Example: CMD-01 in IPLAN-01 → IPLAN.01.19.01

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
sed -i 's/### CMD-01:/### IPLAN.01.19.01:/g' file.md

Validate the result

# Verify no legacy patterns remain
grep -E "(AC|FR|BC|BA|DEC|ALT|CON|CMD|STEP)-[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`
Wrong IPLAN code	Using 15 (Step) for Plan Step	Use code 31 for Plan Step

11. 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/BRD/BRD_VALIDATION_RULES.md`
PRD	`ai_dev_flow/PRD/PRD_VALIDATION_RULES.md`
EARS	`ai_dev_flow/EARS/EARS_VALIDATION_RULES.md`
BDD	`ai_dev_flow/BDD/BDD_VALIDATION_RULES.md`
ADR	`ai_dev_flow/ADR/ADR_VALIDATION_RULES.md`
SYS	`ai_dev_flow/SYS/SYS_VALIDATION_RULES.md`
REQ	`ai_dev_flow/REQ/REQ_VALIDATION_RULES.md`
IMPL	`ai_dev_flow/IMPL/IMPL_VALIDATION_RULES.md`
CTR	`ai_dev_flow/CTR/CTR_VALIDATION_RULES.md`
SPEC	`ai_dev_flow/SPEC/SPEC_VALIDATION_RULES.md`
TASKS	`ai_dev_flow/TASKS/TASKS_VALIDATION_RULES.md`
IPLAN	`ai_dev_flow/IPLAN/IPLAN_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.1.0	2025-12-29	Added Reserved ID Exemption, REF document pattern, ADR/IPLAN removed patterns, fixed element type codes for BRD
1.0.0	2025-12-19	Initial release with all 31 element codes and 18 removed patterns

Install Skill

SKILL.md

doc-naming Skill

1. Purpose & Scope

When to Invoke

Coverage

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

Scope

Pattern

Document Types

Rationale

Validation Behavior

3. Document ID Format (TYPE-NN)

Pattern

Validation Regex

Examples

Filename Convention

REF Document Pattern

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

Pattern

Validation Regex

Examples

Heading Format

5. Element Type Codes Table

Quick Lookup by Document Type

6. Removed/Legacy Patterns

Migration Examples

7. Threshold Tag Format

Tag Pattern

Key Format

Valid Categories

Examples

Source Documents for Thresholds

8. Validation Examples by Document Type

BRD Examples

PRD Examples

EARS Examples

ADR Examples

SPEC Examples

CTR Examples

TASKS Examples

IMPL Examples

IPLAN Examples

9. Pre-Flight Checklist

Document Setup

Element IDs

Threshold Tags

Cross-References

10. Error Recovery

Detecting Legacy Patterns

Migration Procedure

Common Migration Errors

11. Source References

Primary Sources

Validation Rules Files

Related Skills

Diagram Standards

Version History