agentleFS
drivestream-labdrivestream-lab/prayog-skills/skills/requirements/validate-requirements/SKILL.md

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.

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
  1. Distinctive:

    Never skip a check. Mark unavailable checks as SKIPPED with reason.

    line 9
  2. Distinctive:

    Don't fix — flag. This skill identifies issues, never modifies the document.

    line 11
  3. Very specific:

    Prefer targeting product ids (REQ-*, CAP-*, OQ-*) in Location when present.

    line 20
  4. Distinctive:

    Type column is mandatory: Every finding row must include the Type column (Semantic / Structural) so findings from both dimensions are …

    line 37
  5. Very specific:

    Never invent answers: If a [PENDING] marker exists and the answer is NOT in the document or conversation, leave it as-is.

    line 39
  6. Distinctive:

    Incremental mode: when in doubt, re-run: If it is unclear whether a change affects a check, classify it as RE-RUN.

    line 40
  7. Very specific:

    Incremental mode: tag carried-forward findings: Every finding reused from a prior report must include (carried from [date]) in its Finding …

    line 42
  8. Very specific:

    Checklist is mandatory: Every run must maintain the six-item control loop (T0 Gather, T1 Understand, T2 Analyze, T3 Plan, T4 Execute, T5 …

    line 43
  9. Very specific:

    Product ids: When the PRD lacks CAP-* / REQ-*, Gaps may suggest assigning them (do not invent requirement text).

    line 44
  10. Very specific:

    No revision siblings: If a non-canonical Validation-Report-*-revN.md exists, migrate into the canonical path, bump report_revision, and …

    line 45
  11. Distinctive:

    After generating requirements (as part of the pipeline at Stage 9, or standalone)

    line 49
  12. Distinctive:

    When reviewing an existing requirements doc before sharing with stakeholders

    line 50
  13. Distinctive:

    When the user suspects inaccuracies, over-prescription, or unsourced claims

    line 51
  14. Very specific:

    After update-documents propagates changes (in the verify step)

    line 53
  15. Distinctive:

    If source documents are not available, Checks 1 (Source Accuracy) and 4 (Over-Generalization) will be marked SKIPPED with a note explaining …

    line 65
  16. Distinctive:

    Before beginning, determine which mode to use:

    line 71
  17. Distinctive:

    Before Phase 0/1 begins, create and maintain a todo list.

    line 88
  18. Very specific:

    Every item must transition pending → in_progress → completed (or cancelled if truly not applicable).

    line 102
  19. Very specific:

    Never start T1 Understand until T0 Gather is completed.

    line 103
  20. Very specific:

    Never publish final output until T5 Verify is completed.

    line 105
  21. Very specific:

    If interrupted, keep the active item in_progress and explicitly resume from it.

    line 106
  22. Very specific:

    Checklist bootstrap (mandatory): Before Phase 0/1, set T0 Gather to in_progress, collect and inventory all provided/discovered inputs, mark …

    line 112
  23. Distinctive:

    Follow that file's instructions completely.

    line 122
  24. Distinctive:

    Read the requirements document end-to-end.

    line 126
  25. Distinctive:

    Full mode: Run all 11 checks (1–11) in order.

    line 140
  26. Distinctive:

    Run all 4 checks (S1–S4) in order.

    line 167
  27. Very specific:

    all required checks are represented as PASS/FAIL/SKIPPED with rationale,

    line 174
  28. Distinctive:

    Follow that file's instructions to produce both the chat summary and the full report file.

    line 185
  29. Very specific:

    When the invocation binds handoff_path (orchestrator / AgentRunner baton), also overwrite that path with the same handoff: envelope before …

    line 202
  30. Very specific:

    Follow prayog-skills/references/forge-side-effects.md#content-producers when this stage's pin has forge.commit_workspace other than …

    line 206

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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).

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-documents propagates changes (in the verify step)

Inputs

Gather these before starting:

  1. Requirements document — the file to validate (REQUIRED)
  2. Source documents folder — meeting summaries, client docs, design descriptions, transcripts (REQUIRED for Checks 1, 2, 4, 10)
  3. Sibling requirements docs — other feature requirement docs in the same folder (OPTIONAL — needed for Check 5: Scope Boundary)
  4. Stage User Flows artifact — Stage6_User_Flows.md or 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.
  5. 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 *-revN sibling.

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:

ConditionModeBehavior
No prior report providedFullRun all 15 checks from scratch
Prior report providedIncrementalDetect changes, selectively re-run checks, carry forward valid prior findings
User says "run full" or "full validation"FullIgnore any prior report, run all 15 checks from scratch
First run in the pipeline (Stage 9)FullNo prior report exists yet
Re-run after fixes or update-documentsIncremental (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

  1. T0 Gather — Build input inventory (requirements doc, source folder/docs, sibling docs, stage artifacts, prior report if any); list missing inputs and availability
  2. T1 Understand — Confirm validation objective and mode selection basis (Full vs Incremental)
  3. T2 Analyze — Gather evidence (document read, sources, sibling docs, stage artifacts, change detection in incremental mode)
  4. T3 Plan — Build check execution plan (which checks run, scoped re-runs, carried-forward findings)
  5. T4 Execute — Run semantic + structural checks and capture findings with evidence
  6. T5 Verify — Validate output quality and completeness, save report, publish summary + next steps

Checklist status rules

  • Exactly one item is in_progress at a time.
  • Every item must transition pending → in_progress → completed (or cancelled if truly not applicable).
  • Never start T1 Understand until T0 Gather is completed.
  • Never start T4 Execute until T3 Plan is completed.
  • Never publish final output until T5 Verify is completed.
  • If interrupted, keep the active item in_progress and 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.md

Follow that file's instructions completely. When Phase 0 is complete, return here and proceed to Phase 1.

Phase 1: Setup

  1. Read the requirements document end-to-end. Do not skim.
  2. 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.
  3. Identify sibling requirements docs (if any, in the same folder)
  4. 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).
  5. Locate stage artifacts: scan for Stage4_Scenario_Matrix.md and Stage6_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.md

Full 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.md

Run 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.md

Follow that file's instructions to produce both the chat summary and the full report file.


Integration with Other Skills

ContextModeHow it's called
Standalone (first run)FullRun against any requirements doc + its source folder. No prior report exists.
Standalone (re-run)IncrementalUser provides the prior validation report. Skill detects changes and selectively re-runs.
Pipeline (Stage 9)FullCalled 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 updatesIncrementalCalled 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

  1. Append/emit the envelope from prayog-skills/references/handoff-envelope.md to the saved validation report. Use stage validate-requirements.
  2. When the invocation binds handoff_path (orchestrator / AgentRunner baton), also overwrite that path with the same handoff: envelope before exit. Leaving the baton empty is a failed stage for automated consumers. artifact.path remains the workspace skill output, not the baton path. See prayog-skills/references/handoff-envelope.md (Orchestrator baton).
  3. Derive next_candidates and human_checkpoint from pinned root workflow.yaml for (stage: validate-requirements, outcome) per prayog-skills/references/handoff-envelope.md (Derive from pinned workflow). Set human_checkpoint: true only when the resolved next node's type is human-checkpoint — never because the artifact "should be reviewed."
  4. Follow prayog-skills/references/forge-side-effects.md#content-producers when this stage's pin has forge.commit_workspace other than disabled or next is an external-action with forge.requires — fill handoff.forge / recommend the matching /forge skill; 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.