---
_version: '1'
uuid: 0e6e65f9-2bdd-4b9a-a013-87d9d58882e4
created: 2025-11-14T12:01:44.761061039Z
parents:
- uuid: 3f8b9d42-7e1c-4a93-9f6d-2e4a5b8c1d3f
fingerprint: 54bdd9bcfdead6b9fd2bba80521067ba9c24858d83823167be5f79750932913c
hrid: SYS-016
---
# SYS-023 Path Diagnostics Command
## Statement
The tool shall provide a `req diagnose paths` command that validates requirement file paths against the configured directory structure mode, reports mismatches, and suggests remediation steps.
## Rationale
When migrating between directory organization modes or when files are manually moved, requirements may end up in incorrect locations. A diagnostic command helps users identify and fix path inconsistencies, ensuring the repository structure remains consistent with the configured mode.
This is particularly important for:
- Migrating from filename mode to path mode (or vice versa)
- Detecting files that were manually moved incorrectly
- CI/CD validation to prevent merging incorrectly placed files
- Onboarding new team members who may not understand the path conventions
## Implementation Notes
- Command: `req diagnose paths`
- Validates each requirement file's path matches the expected location based on:
- The requirement's HRID
- The `subfolders_are_namespaces` configuration setting
- Reports each mismatch with:
- Current file path
- Expected file path based on configuration
- The requirement's HRID
- Exits with non-zero status code if mismatches found (useful for CI)
- Implemented in `src/cli.rs` lines 984-1058
- Uses `PathParser` to compute expected paths
## Verification
- Run `req diagnose paths` in a repository with all files correctly placed
- Command exits with status 0
- Reports "All paths are correct" or similar success message
- Manually move a requirement file to incorrect location
- Command exits with non-zero status
- Reports the specific mismatch with current and expected paths
- Verify CI integration: command can be used in CI pipeline to prevent merging incorrectly placed files