How to use paths in SpecDD sections

How-To Use spec sections Intermediate 1061023HOWTO-1061023

HOWTO-1061023Use spec sectionsIntermediate

This guide shows you how to use paths in SpecDD .sdd sections.

Explicit paths matter because path references can affect context, ownership, write authority, and review. SpecDD treats unprefixed filenames as text, not path references.

Short answer

Use ./, ../, or / when you mean a file or directory path. ./ and ../ resolve relative to the current .sdd file directory. / resolves relative to the selected content root. Put paths in sections that match intent: Owns or Can modify for authority, Can read or References for context, Forbids for blocked paths, and Structure for layout.

Path prefixes

Use:

./local-file.js
../sibling-area/spec.sdd
/docs/adr/storage-boundary.md

Meaning:

./ is relative to the directory containing the current .sdd file.
../ is relative to the directory containing the current .sdd file.
/ is relative to the selected content root.
~/ is not a supported path prefix.

Unprefixed text is not an explicit path:

Depends on:
  TripStorage

TripStorage is dependency text, not a file path.

Steps

1. Choose the section by intent

Layout:

Structure:
  ./src: Source code

Ownership:

Owns:
  ./itinerary.js

Write authority:

Can modify:
  ./itinerary.js
  ./itinerary.test.js

Read-only context:

Can read:
  ../storage/trip-storage.sdd

Blocked path:

Forbids:
  ../booking/*

2. Use `/` paths for content-root references

Use / when the reference should be stable from the selected content root:

References:
  /docs/adr/storage-boundary.md

The content root is selected by tooling or project setup. In a single repository, it is usually the repository root. In a monorepo, it may be the monorepo root or an explicitly configured project root.

3. Avoid unprefixed filenames

Weak:

Can modify:
  itinerary.js

Good:

Can modify:
  ./itinerary.js

Unprefixed filenames are plain text, not explicit path references.

4. Understand path-bearing sections

Tools may extract explicit paths from:

Structure
Owns
Can modify
Can read
References
Depends on
Forbids
Exposes

Path-bearing does not mean path-only. These sections may still contain prose.

5. Review path authority

Paths in different sections mean different things.

Can modify:

Can modify:
  ./itinerary.js

means writable under this spec.

Can read:

Can read:
  ./itinerary.js

means read context only.

Do not treat every path as permission to edit.

Common mistakes

Writing unprefixed filenames when explicit paths were intended.
Using / without knowing the selected content root.
Treating paths in Can read or References as writable.
Putting blocked paths in Must not instead of Forbids.
Assuming a directory path recursively includes every descendant spec.

How to verify the result

Path usage is clear when:

explicit paths use ./, ../, or /
the section matches the intended meaning
write authority paths are separated from read context
content-root paths are intentional
reviewers can explain why each path appears

Language reference

← Use spec sections guides