shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

doc-naming

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

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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 |

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

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 |

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 |

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 |

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

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

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

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 |

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