Decision 02: Naming Convention
Status
Accepted
Date
2026-02-18
Context
When a project has multiple documents (PAD, OAD, SDD, and potentially multiple SDDs per use case), file explorers display them in alphabetical order. Without a deliberate naming strategy, related documents (e.g. the OAD and SDD for the same use case) may not appear next to each other, making it harder for users to navigate the document set.
Several naming approaches were considered:
- Sequential numbering (001, 002, 003): Simple but implies ordering/priority rather than hierarchy
- Hierarchy-level codes (00, 01, 02): Groups by hierarchy but adds cognitive overhead — users must learn that codes represent hierarchy levels, not sequence numbers
- Descriptive codes with document type suffix: Groups related documents naturally by shared use case name, with a clear document type suffix (PAD, OAD, SDD) at the end
The hierarchy-level codes approach was initially adopted but later superseded by the descriptive approach. The numeric codes were unnecessary because documents naturally group together by their shared project and use case code prefix, and the document type suffix (PAD, OAD, SDD) is clearer than a numeric hierarchy indicator.
Decision
Adopt the following naming convention:
| Document | Pattern |
|---|---|
| PAD | PROJECT CODE – AI PLATFORM CODE – PAD.md |
| OAD | PROJECT CODE – USE CASE CODE – OAD.md |
| SDD | PROJECT CODE – USE CASE CODE – SDD.md |
| SDD (multi) | PROJECT CODE – USE CASE CODE – SDD – SOLUTION CODE.md |
Each segment is separated by an em dash (–) with spaces. The document type suffix (PAD, OAD, SDD) always appears at the end.
Rationale
- Natural grouping: Documents for the same use case sort together because they share the same project and use case code prefix — no numeric codes needed.
- Clear document type: The suffix (PAD, OAD, SDD) immediately communicates what the document is, without requiring users to memorise numeric codes.
- Multi-SDD support: When a use case has multiple SDDs, the descriptive solution code suffix differentiates them while keeping them grouped.
- Simplicity: No special codes to learn — the naming convention is self-documenting.
Consequences
- The em dash (
–) character in filenames may cause issues on some systems — an en dash or regular hyphen can be substituted if needed. - The PAD uses “AI PLATFORM CODE” as its descriptive segment (e.g. “GenAI Platform”) rather than a use case name, reflecting its platform-level scope.
- Cross-references within document content use PAD/OAD/SDD abbreviations with section numbers, not filenames (see Decision 03).