doc-naming（文档命名）

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

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,8}-[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.xxxx)

Pattern

{DOC_TYPE}.{DOC_NUM}.{HASH}

Validation Regex

^[A-Z]{2,8}\.[0-9]{2,}\.[a-z0-9]{4,}$

Examples

Heading Format

Element IDs appear as markdown headings:

### BRD.02.0601: User Authentication Acceptance Criteria
#### PRD.01.0903: User Login Story

5. Element Type Codes Table

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

Full Format Options

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

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:

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.0101: User Authentication Requirement
### BRD.02.0601: Login Acceptance Criteria
### BRD.02.2301: Revenue Growth Objective
### BRD.02.0901: User Onboarding Story
### BRD.02.1001: Database Selection Decision
### BRD.02.3201: Infrastructure Architecture Topic
### BRD.02.3202: Data Architecture Topic
### BRD.02.3301: Cost Reduction Benefit
### BRD.02.3302: Efficiency Improvement Benefit
@threshold: BRD.02.perf.response_time.max

PRD Examples

### PRD.01.0901: User Login Story
### PRD.01.2201: Dashboard Feature
### PRD.01.0601: Feature Acceptance Criteria
@threshold: PRD.01.timeout.session.idle

EARS Examples

#### EARS.06.2501: KYC Submission Event
#### EARS.06.2502: Pending Status State

ADR Examples

### ADR.05.1001: Use PostgreSQL Decision
### ADR.05.1201: MongoDB Alternative
### ADR.05.1301: Migration Consequence
@threshold: ADR.05.circuit.failure_threshold

SPEC Examples

### SPEC.03.1601: REST API Interface
### SPEC.03.1701: User Data Model
### SPEC.03.2101: Email Validation Rule

CTR Examples

### CTR.02.1601: Partner API Interface
### CTR.02.1701: Order Data Model
### CTR.02.2001: Rate Limit Clause

TSPEC Examples

### TSPEC.01.4001: User Authentication Unit Test
### TSPEC.01.4101: API Integration Test
### TSPEC.01.4201: Login Flow Smoke Test
### TSPEC.01.4301: Order Processing Functional Test

TASKS Examples

### TASKS.02.1801: Setup Development Environment
### TASKS.02.3001: 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 3-segment dot notation: TYPE.NN.xxxx
• Element hash is 4+ alphanumeric characters (see Section 5)
• Element hashes 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 (COMPREHENSIVE - run ALL commands)

# 1. Simple legacy patterns (e.g., FR-001, AC-002)
grep -E "(AC|FR|BC|BA|QA|BO|NFR|RISK|METRIC)-[0-9]+" file.md

# 2. Compound/domain-prefixed patterns (e.g., FR-CICD-001, NFR-PERF-002)
#    CRITICAL: These patterns have additional components between prefix and number
grep -E "(AC|FR|BC|BA|QA|BO|NFR)(-[A-Za-z0-9]+)+-[0-9]+" file.md

# 3. Other legacy patterns
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

# 4. Combined single-command detection (recommended for automation)
grep -E "(AC|FR|BC|BA|QA|BO|NFR|RISK|METRIC)(-[A-Za-z0-9]+)*-[0-9]+" file.md

Pattern Explanation:

Examples Caught:

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}.{HASH} - Example: AC-001 in BRD-02 → BRD.02.0601 - Example: DEC-01 in ADR-05 → ADR.05.1001

1. Replace all occurrences # Example sed replacement sed -i 's/### AC-001:/### BRD.02.0601:/g' file.md sed -i 's/### DEC-01:/### ADR.05.1001:/g' file.md
2. Validate the result # Verify no legacy patterns remain (COMPREHENSIVE check) # Must return empty for all commands grep -E "(AC|FR|BC|BA|QA|BO|NFR|DEC|ALT|CON)-[0-9]+" file.md grep -E "(AC|FR|BC|BA|QA|BO|NFR)(-[A-Za-z0-9]+)+-[0-9]+" file.md

Common Migration Errors

12. 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_ssd_flow/DIAGRAM_STANDARDS.md and mermaid-gen skill.

Version History