validate-requirements

Validate Requirements — Semantic + Structural Review

NON-NEGOTIABLE (read first)

1. Never skip a check. Mark unavailable checks as SKIPPED with reason.
2. Show evidence for every finding — problematic text + source quote.
3. Don't fix — flag. This skill identifies issues, never modifies the document.
4. Dual output is mandatory: chat summary + saved report file + next steps.
5. Incremental mode: when in doubt, RE-RUN. Stale carry-forward is worse than a redundant re-run.
6. Canonical report path — overwrite {reports_dir}/Validation-Report-{INIT}.md only. Never create *-revN, *-v2, or dated siblings. See prayog-skills/references/artifact-write-contract.md.
7. Stable finding ids — every finding row uses VF-{nn} per prayog-skills/references/id-conventions.md. Carry forward keeps the same id.
8. Prefer targeting product ids (REQ-*, CAP-*, OQ-*) in Location when present; legacy FR-* maps to REQ-* (same number).

Purpose

Catches both semantic inaccuracies (factually wrong, unsourced, over-generalized, solution-prescriptive, untestable content) and structural issues (stale placeholders, contradictions, broken cross-references, completeness gaps) in a single pass.

This skill replaces the need to run validate-requirements and document-audit separately on requirements documents. The standalone document-audit skill remains available for non-requirements documents (PRDs, meeting notes, design specs).

Critical Rules

1. Never skip a check. If inputs are missing for a check, mark it SKIPPED with an explanation — do not silently omit it. In incremental mode, CARRY FORWARD is not "skipped" — the check ran in the prior report and its results are being reused because inputs haven't changed.
2. Show evidence, not just verdicts. For every finding, show the problematic text and (for source checks) what the source actually says. Critical rows must include enough evidence for a review decision brief (Source Says / Doc Claims or concrete example).
3. Severity matters. Group findings by severity in the report, not by check number. A single finding may fail multiple checks — list it once under its highest severity with all applicable check numbers.
4. Dual output + next steps are mandatory. Always produce the chat summary, the full report file, and prioritized next steps. The chat summary is for quick triage; the report file is for persistent reference; the next steps tell the user exactly what to do next and in what order.
5. Be conservative with PASS. A check PASSes only if zero findings — including carried-forward findings. A carried-forward finding still counts.
6. Don't fix — flag. This skill identifies issues; it does not modify the requirements document. Fixes are applied separately (by the user or by the pipeline).
7. Type column is mandatory. Every finding row must include the Type column (Semantic / Structural) so findings from both dimensions are clearly distinguished in severity-sorted tables.
8. Read the FULL document. Structural checks are only effective when cross-referencing the entire document. Never audit from a partial read. In incremental mode, the full document is still read in Phase 1 — only source documents may be skipped if unchanged.
9. Never invent answers. If a [PENDING] marker exists and the answer is NOT in the document or conversation, leave it as-is. Report it as "unresolved — still needs input."
10. Incremental mode: when in doubt, re-run. If it is unclear whether a change affects a check, classify it as RE-RUN. The cost of re-running an unnecessary check is low; the cost of carrying forward a stale finding is high.
11. Incremental mode: Check 11 and S1–S4 always re-run. These are the consistency safety net. Any edit — even one that fixes a finding — can introduce new contradictions, stale references, or consistency gaps in other sections. Never carry these checks forward.
12. Incremental mode: tag carried-forward findings. Every finding reused from a prior report must include (carried from [date]) in its Finding cell and keep the same VF-* id.
13. Checklist is mandatory. Every run must maintain the six-item control loop (T0 Gather, T1 Understand, T2 Analyze, T3 Plan, T4 Execute, T5 Verify) with explicit status transitions. Do not skip directly from analysis to output.
14. Product ids. When the PRD lacks CAP-* / REQ-*, Gaps may suggest assigning them (do not invent requirement text). Prefer citing existing ids in Location.
15. No revision siblings. If a non-canonical Validation-Report-*-revN.md exists, migrate into the canonical path, bump report_revision, and stop writing the sibling (do not delete without authorization).