Plan Path Validator

Overview

An implementation plan often names concrete file paths, scripts, tools, and directories as edit targets, rollback mechanisms, or supporting evidence. When a plan is drafted from memory or a stale reflection, some references point at paths that were renamed, moved, or deleted since the memory was formed. A plan built on a phantom path surfaces the defect only at /dr-do implementation time — after a full pipeline stage has been spent — and forces a mid-build re-plan. This Reference skill provides the deterministic exists-check contract for path references a /dr-plan output carries. It is the path-oriented companion to the Symbol Existence Check already prescribed in dr-plan § 6.5: symbol-existence greps the code for a named function/flag/env var; path-existence probes the filesystem (and git index) for a named file/script/directory, and additionally flags paths that resolve but are marked deprecated.

When To Use

Load this skill when a /dr-plan output (or a plan-shaped section of a PRD) names a file path as an edit/read/rollback target, a script or tool invoked by an Implementation Step or Validation row, a directory cited as a destination or scan root, or a supporting-evidence path cited in Rollback Strategy, Testing Strategy, or the Validation Checklist. NOT for purely conceptual plans with no concrete filesystem references, or symbol-only references already covered by dr-plan § 6.5.

The Contract

For every path reference the plan carries, apply a deterministic ladder — no LLM judgement, no fabrication:

1. Collect the referenced paths. Extract slash-bearing tokens in backticks, code fences, or Validation-row commands. Deduplicate. Always quote and terminate option parsing with -- before passing to a shell tool (untrusted-input hygiene).
2. Existence probe. Disambiguate git-tracked vs non-git paths. Inside a working tree, prefer git cat-file -e HEAD:$p (tracked) or git ls-files --error-unmatch (staged-but-uncommitted), falling back to test -e (untracked-but-present). Outside a working tree, use test -e directly. A token failing all checks is a phantom path.
3. Deprecation probe. A path existing is not the same as being current. Flag a resolved path as deprecated when the path or its nearest README/index carries a deprecated/retired/obsolete/superseded marker, matches a known-retired ecosystem surface (cite the source-of-truth line), or a live replacement exists at a sibling path.
4. Report. Emit a compact block: checked count, present count, MISSING paths, DEPRECATED paths with replacements — folded into the plan's Validation Checklist or the reviewer's QA report.

Verdicts

• A MISSING path is a planning defect: redirect the reference to the real surface, or mark it [to-be-created] with a one-sentence justification.
• A DEPRECATED path is a staleness defect: swap it for the live replacement before the plan is executed.
• An all-present, no-deprecated result is a clean pass — no plan change needed.

Relationship To Existing Gates

Complements dr-plan § 6.5's Symbol Existence Check (source-code symbols) and Git Topology Probe (gitignored-vs-non-git disambiguation, reused here). Distinct from check-doc-refs.sh, a CI linter that resolves markdown links post-hoc on committed docs — this skill runs at plan-draft time on any path-shaped token, before /dr-do.

Anti-Patterns

• Asserting a path is deprecated from memory without citing a source-of-truth line.
• Treating a symbol-existence grep hit as a path-existence pass.
• Running test -e unquoted or without -- on a planner-emitted path.