← Troubleshooting guides

How to debug spec resolution problems

How-To Troubleshooting Intermediate 1191006HOWTO-1191006

HOWTO-1191006TroubleshootingIntermediate

This guide shows you how to debug SpecDD resolution problems when the wrong specs appear to apply, expected specs are missing, or an agent cannot explain the governing context.

SpecDD resolution is path-based. Parent specs are inherited automatically. Sibling specs are not inherited unless a governing spec references them.

Short answer

Start from the concrete target path. Confirm the selected content root, walk ancestor specs from root to target, include directory-level specs, include same-directory same-basename specs, follow explicit References, Can read, or other relevance links only where appropriate, then compare your expectation with specdd resolve output.

Steps

1. Identify the target

Resolution starts from a target:

src/trips/itinerary.js

Do not start from a vague feature name if the problem is path resolution. Pick the file, directory, or .sdd target that should be governed.

2. Confirm the content root

The selected content root controls:

For a project named:

travel-planner/

the root spec should be:

travel-planner/travel-planner.sdd

If the agent or editor opens only src/, the root chain may be wrong.

3. Walk ancestor specs

For:

travel-planner/src/trips/itinerary.js

the expected chain might be:

travel-planner.sdd
src/trips.sdd
src/trips/trips.sdd
src/trips/itinerary.sdd

Parent-held and local directory specs are cumulative context, not alternatives.

4. Check directory specs

A directory can be described by a same-basename spec inside the directory or by a parent-held spec:

src/trips.sdd
src/trips/trips.sdd

If a directory-level rule is missing, check whether the spec is in the expected place and has the expected name.

5. Check same-basename matching

For an ordinary file:

itinerary.js

the local same-basename spec is:

itinerary.sdd

Same-basename matching is explicit SpecDD behavior. Similar names in other directories, symbols in code, or test names do not create authority.

6. Check explicit references and globs

Sibling specs need explicit references:

References:
  ../storage/trip-storage.sdd

Non-glob directory links should not recursively include every descendant spec. Use a deliberate glob only when broad recursive context is needed:

References:
  ../storage/**/*.sdd

7. Use specdd resolve

Run:

specdd resolve src/trips/itinerary.js --sections Spec,Purpose,Owns,Can modify,Can read,References,Must,Must not,Tasks

Use the output to see which specs are included. Then read the exact spec files when authority or wording matters.

Common causes

How to verify the fix

Resolution is fixed when:

← Troubleshooting guides