doc-naming

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 |

---

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.

---

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

```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)

---

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

```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:

```markdown

BRD.02.06.01: User Authentication Acceptance Criteria

#### PRD.01.09.03: User Login Story

```

---

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 |

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

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 |

---

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 |

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 |

---

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

---

BRD Examples

```markdown

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

```markdown

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

```markdown

#### EARS.06.25.01: KYC Submission Event

#### EARS.06.25.02: Pending Status State

```

ADR Examples

```markdown

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

```markdown

SPEC.03.16.01: REST API Interface

SPEC.03.17.01: User Data Model

SPEC.03.21.01: Email Validation Rule

```

CTR Examples

```markdown

CTR.02.16.01: Partner API Interface

CTR.02.17.01: Order Data Model

CTR.02.20.01: Rate Limit Clause

```

TASKS Examples

```markdown

TASKS.02.18.01: Setup Development Environment

TASKS.02.30.01: Configure CI Pipeline

```

IMPL Examples

```markdown

IMPL.02.29.01: Foundation Phase

IMPL.02.29.02: Integration Phase

```

---

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)

---

Detecting Legacy Patterns

Use grep to find legacy patterns:

```bash

# 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

1. Look up the element type code from Section 5

- Example: AC-XXX → Acceptance Criteria → Code 06

- Example: DEC-XXX → Decision → Code 10

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

1. Replace all occurrences

```bash

# 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

```

1. Validate the result

```bash

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

---

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 |

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 | Date | Changes |

|---------|------|---------|

| 1.2.0 | 2026-01-17 | Updated to 11 active artifact types; Removed legacy element codes 19, 31 |

| 1.1.0 | 2025-12-29 | Added Reserved ID Exemption, REF document pattern, ADR 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 |