doc-naming Skill

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

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:

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

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.

Migration Examples

---

7. Threshold Tag Format

Tag Pattern

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

Key Format

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

Valid Categories

Examples

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

---

11. Source References

Primary Sources

Validation Rules Files

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

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 and mermaid-gen skill.

Version History