validate-requirements
Skill2 starsChanged 4 months agoMITView on GitHub
Validates requirements documents using 15 checks across 2 dimensions: semantic accuracy (11 checks — source truth, inference detection, requirement purity, over-generalization, scope boundaries, testability, ambiguity, assumption dependencies, negative paths, actor capability, intra-document consistency) and structural integrity (4 checks — staleness, contradictions, cross-references, completeness). Supports incremental mode: when a prior validation report is provided, only re-runs checks whose inputs have changed, carries forward findings that remain valid, and detects resolved findings — cutting re-validation effort by 40-60%. Produces a unified report with clear Semantic vs Structural grouping. Use after generating requirements, before sharing with stakeholders, when suspecting inaccuracies, or as a periodic quality sweep.
In this repository22 other files it gives its agents.
- ground-specSkill
- initiative-feasibilitySkill
- learning-extractSkill
- loop-specSkill
- pre-implementSkill
- purge-initiative-artifacts-appSkill
- spec-draftSkill
- spec-implementation-planSkill
- spec-technical-reviewSkill
- ensure-repo-graphSkill
- post-product-questionsSkill
- prd-codebase-mapSkill
- review-product-questionsSkill
- commit-workspaceSkill
- create-board-ticketsSkill
- open-draft-prSkill
- prd-impact-mapSkill
- prd-qualitySkill
- prd-thinkSkill
- purge-initiative-artifacts-metaSkill
- review-findingsSkill
- update-documentsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
30 rules. About 0 are common, 15 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Never skip a check. Mark unavailable checks as SKIPPED with reason.
- Distinctive: line 11
Don't fix — flag. This skill identifies issues, never modifies the document.
- Very specific: line 20
Prefer targeting product ids (REQ-*, CAP-*, OQ-*) in Location when present.
- Distinctive: line 37
Type column is mandatory: Every finding row must include the Type column (Semantic / Structural) so findings from both dimensions are …
- Very specific: line 39
Never invent answers: If a [PENDING] marker exists and the answer is NOT in the document or conversation, leave it as-is.
- Distinctive: line 40
Incremental mode: when in doubt, re-run: If it is unclear whether a change affects a check, classify it as RE-RUN.
- Very specific: line 42
Incremental mode: tag carried-forward findings: Every finding reused from a prior report must include (carried from [date]) in its Finding …
- Very specific: line 43
Checklist is mandatory: Every run must maintain the six-item control loop (T0 Gather, T1 Understand, T2 Analyze, T3 Plan, T4 Execute, T5 …
- Very specific: line 44
Product ids: When the PRD lacks CAP-* / REQ-*, Gaps may suggest assigning them (do not invent requirement text).
- Very specific: line 45
No revision siblings: If a non-canonical Validation-Report-*-revN.md exists, migrate into the canonical path, bump report_revision, and …
- Distinctive: line 49
After generating requirements (as part of the pipeline at Stage 9, or standalone)
- Distinctive: line 50
When reviewing an existing requirements doc before sharing with stakeholders
- Distinctive: line 51
When the user suspects inaccuracies, over-prescription, or unsourced claims
- Very specific: line 53
After update-documents propagates changes (in the verify step)
- Distinctive: line 65
If source documents are not available, Checks 1 (Source Accuracy) and 4 (Over-Generalization) will be marked SKIPPED with a note explaining …
- Distinctive: line 71
Before beginning, determine which mode to use:
- Distinctive: line 88
Before Phase 0/1 begins, create and maintain a todo list.
- Very specific: line 102
Every item must transition pending → in_progress → completed (or cancelled if truly not applicable).
- Very specific: line 103
Never start T1 Understand until T0 Gather is completed.
- Very specific: line 105
Never publish final output until T5 Verify is completed.
- Very specific: line 106
If interrupted, keep the active item in_progress and explicitly resume from it.
- Very specific: line 112
Checklist bootstrap (mandatory): Before Phase 0/1, set T0 Gather to in_progress, collect and inventory all provided/discovered inputs, mark …
- Distinctive: line 122
Follow that file's instructions completely.
- Distinctive: line 126
Read the requirements document end-to-end.
- Distinctive: line 140
Full mode: Run all 11 checks (1–11) in order.
- Distinctive: line 167
Run all 4 checks (S1–S4) in order.
- Very specific: line 174
all required checks are represented as PASS/FAIL/SKIPPED with rationale,
- Distinctive: line 185
Follow that file's instructions to produce both the chat summary and the full report file.
- Very specific: line 202
When the invocation binds handoff_path (orchestrator / AgentRunner baton), also overwrite that path with the same handoff: envelope before …
- Very specific: line 206
Follow prayog-skills/references/forge-side-effects.md#content-producers when this stage's pin has forge.commit_workspace other than …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Validate Requirements — Semantic + Structural Review
NON-NEGOTIABLE (read first)
- Never skip a check. Mark unavailable checks as SKIPPED with reason.
- Show evidence for every finding — problematic text + source quote.
- Don't fix — flag. This skill identifies issues, never modifies the document.
- Dual output is mandatory: chat summary + saved report file + next steps.
- Incremental mode: when in doubt, RE-RUN. Stale carry-forward is worse than a redundant re-run.
- Canonical report path — overwrite
{reports_dir}/Validation-Report-{INIT}.mdonly. Never create*-revN,*-v2, or dated siblings. Seeprayog-skills/references/artifact-write-contract.md. - Stable finding ids — every finding row uses
VF-{nn}perprayog-skills/references/id-conventions.md. Carry forward keeps the same id. - Prefer targeting product ids (
REQ-*,CAP-*,OQ-*) in Location when present; legacyFR-*maps toREQ-*(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
- 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.
- 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).
- 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.
- 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.
- Be conservative with PASS. A check PASSes only if zero findings — including carried-forward findings. A carried-forward finding still counts.
- 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).
- 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.
- 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.
- 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." - 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.
- 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.
- 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 sameVF-*id. - 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. - Product ids. When the PRD lacks
CAP-*/REQ-*, Gaps may suggest assigning them (do not invent requirement text). Prefer citing existing ids in Location. - No revision siblings. If a non-canonical
Validation-Report-*-revN.mdexists, migrate into the canonical path, bumpreport_revision, and stop writing the sibling (do not delete without authorization).
When to Use
- After generating requirements (as part of the pipeline at Stage 9, or standalone)
- When reviewing an existing requirements doc before sharing with stakeholders
- When the user suspects inaccuracies, over-prescription, or unsourced claims
- As a periodic quality sweep across a set of feature docs
- After
update-documentspropagates changes (in the verify step)
Inputs
Gather these before starting:
- Requirements document — the file to validate (REQUIRED)
- Source documents folder — meeting summaries, client docs, design descriptions, transcripts (REQUIRED for Checks 1, 2, 4, 10)
- Sibling requirements docs — other feature requirement docs in the same folder (OPTIONAL — needed for Check 5: Scope Boundary)
- Stage User Flows artifact —
Stage6_User_Flows.mdor equivalent stage artifact (OPTIONAL — needed for Check 11 cross-check). If not provided, scan for it in the project's Artifacts or stage folders. If found, use it. If not found, note it as unavailable and skip that sub-check only. - Prior validation report — canonical
{reports_dir}/Validation-Report-{INIT}.md(OPTIONAL). When provided, the skill enters incremental mode. When absent or when the user says "run full", run all 15 checks (full mode). Prefer the canonical path over any legacy*-revNsibling.
If source documents are not available, Checks 1 (Source Accuracy) and 4 (Over-Generalization) will be marked SKIPPED with a note explaining why.
Mode Selection
Before beginning, determine which mode to use:
| Condition | Mode | Behavior |
| No prior report provided | Full | Run all 15 checks from scratch |
| Prior report provided | Incremental | Detect changes, selectively re-run checks, carry forward valid prior findings |
| User says "run full" or "full validation" | Full | Ignore any prior report, run all 15 checks from scratch |
| First run in the pipeline (Stage 9) | Full | No prior report exists yet |
Re-run after fixes or update-documents | Incremental (if prior report available) | Typical incremental use case |
Mandatory Todo / Checklist Control Loop
This skill must run with a mandatory checklist that enforces: Gather → Understand → Analyze → Plan → Execute → Verify.
Before Phase 0/1 begins, create and maintain a todo list. This is not optional.
Required checklist items
T0 Gather— Build input inventory (requirements doc, source folder/docs, sibling docs, stage artifacts, prior report if any); list missing inputs and availabilityT1 Understand— Confirm validation objective and mode selection basis (Full vs Incremental)T2 Analyze— Gather evidence (document read, sources, sibling docs, stage artifacts, change detection in incremental mode)T3 Plan— Build check execution plan (which checks run, scoped re-runs, carried-forward findings)T4 Execute— Run semantic + structural checks and capture findings with evidenceT5 Verify— Validate output quality and completeness, save report, publish summary + next steps
Checklist status rules
- Exactly one item is
in_progressat a time. - Every item must transition
pending→in_progress→completed(orcancelledif truly not applicable). - Never start
T1 UnderstanduntilT0 Gatheriscompleted. - Never start
T4 ExecuteuntilT3 Planiscompleted. - Never publish final output until
T5 Verifyiscompleted. - If interrupted, keep the active item
in_progressand explicitly resume from it.
Execution Workflow
Checklist bootstrap (mandatory): Before Phase 0/1, set T0 Gather to in_progress, collect and inventory all provided/discovered inputs, mark T0 Gather completed, then set T1 Understand to in_progress. Mark T1 Understand completed only after mode (Full vs Incremental) is explicitly justified from gathered inputs.
Phase 0: Change Detection (incremental mode only)
Skip this phase entirely in full mode — proceed directly to Phase 1.
Read the file:
incremental-detection.mdFollow that file's instructions completely. When Phase 0 is complete, return here and proceed to Phase 1.
Phase 1: Setup
- Read the requirements document end-to-end. Do not skim.
- Identify and read all source documents (from the provided folder path). Incremental mode optimization: if Phase 0.3 determined sources are unchanged AND only CARRY FORWARD checks need them, skip re-reading source files — they are only needed for checks that are actually running.
- Identify sibling requirements docs (if any, in the same folder)
- Build a source index: map each SRC-N to its file and key content. Incremental mode: build only for sources referenced by checks that are RE-RUN or RE-RUN (scoped).
- Locate stage artifacts: scan for
Stage4_Scenario_Matrix.mdandStage6_User_Flows.md(or equivalent) in the project's Artifacts or stage folders. Note whether each is found or unavailable.
Checklist update: In full mode (where Phase 0 is skipped), set T2 Analyze to in_progress at Phase 1 start and mark completed after setup evidence collection is finished. Then set T3 Plan to in_progress and completed once the check run plan is explicit (all checks in full mode; selective plan in incremental mode).
Phase 2a: Semantic Checks (content accuracy)
Read and follow:
checks/semantic-checks.mdFull mode: Run all 11 checks (1–11) in order.
Incremental mode: For each check, consult the execution plan from Phase 0.4:
- RE-RUN — run the check fully, as in full mode
- RE-RUN (scoped) — run the check only on changed FRs/sections; merge results with SURVIVING findings carried from the prior report for unchanged FRs/sections
- CARRY FORWARD — do not run the check; use SURVIVING findings from Phase 0.5 as the check's results
For each finding (whether new or carried forward), record:
- Location in doc (section + line)
- The problematic text
- The verdict
- The recommendation
Classify severity:
- Critical — factually wrong or misleading (must fix before sharing)
- Should Fix — reframe, relocate, or make precise (improves quality)
- Verify — needs user confirmation (may be correct, can't determine automatically)
- Gap — missing coverage (negative paths, uncovered scenarios)
Checklist update: Set T4 Execute to in_progress before running Check 1 and keep it active through Phase 2b.
Phase 2b: Structural Checks (document integrity)
Read and follow:
checks/structural-checks.mdRun all 4 checks (S1–S4) in order. Structural checks always run in both full and incremental mode — they are cheap, operate on the document alone, and catch editing artifacts that are invisible to the change manifest. Use the same severity classifications as Phase 2a.
Phase 3: Generate Output
Produce two outputs: a chat summary and a full report file.
Checklist update: Set T5 Verify to in_progress before composing outputs. Verify that:
- all required checks are represented as PASS/FAIL/SKIPPED with rationale,
- severity tables include required columns (including Type),
- carried-forward findings are tagged (incremental mode),
- output file path rules were followed.
Mark T5 Verify as completed only after report is saved and chat summary is published.
Read the file:
output-templates.mdFollow that file's instructions to produce both the chat summary and the full report file.
Integration with Other Skills
| Context | Mode | How it's called |
| Standalone (first run) | Full | Run against any requirements doc + its source folder. No prior report exists. |
| Standalone (re-run) | Incremental | User provides the prior validation report. Skill detects changes and selectively re-runs. |
| Pipeline (Stage 9) | Full | Called by requirements-pipeline as the combined accuracy + integrity review. No prior report exists at this stage. The report it produces becomes the prior report for future incremental runs. |
| After updates | Incremental | Called by update-documents in its Phase 3 verify step. The pre-update validation report serves as the prior report. |
| Interactive resolution | — | After report is generated, user invokes review-findings with the report file to walk through findings and collect decisions |
Workflow handoff
- Append/emit the envelope from
prayog-skills/references/handoff-envelope.mdto the saved validation report. Use stagevalidate-requirements. - When the invocation binds
handoff_path(orchestrator / AgentRunner baton), also overwrite that path with the samehandoff:envelope before exit. Leaving the baton empty is a failed stage for automated consumers.artifact.pathremains the workspace skill output, not the baton path. Seeprayog-skills/references/handoff-envelope.md(Orchestrator baton). - Derive
next_candidatesandhuman_checkpointfrom pinned rootworkflow.yamlfor(stage: validate-requirements, outcome)perprayog-skills/references/handoff-envelope.md(Derive from pinned workflow). Sethuman_checkpoint: trueonly when the resolved next node'stypeishuman-checkpoint— never because the artifact "should be reviewed." - Follow
prayog-skills/references/forge-side-effects.md#content-producerswhen this stage's pin hasforge.commit_workspaceother thandisabledor next is anexternal-actionwithforge.requires— fillhandoff.forge/ recommend the matching/forgeskill; do not treat local CLI as skill success.
Transitions: pinned root workflow.yaml for this stage (SSOT). Do not
hardcode divergent next nodes. Human or agent may run this skill; legality and
orchestrator auto-dispatch follow dispatch + delivery contract + latest
handoff (invocation-mode-is-not-an-exemption).
Populate the artifact path/digest and stable finding ids (VF-*) under
blockers when outcome is findings. next_candidates are hints only — they
never authorize invoke.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

