verify-openspec-docs

fission-ai/openspec

Fact-checks OpenSpec documentation by re-running commands and verifying claims against source.

What is verify-openspec-docs?

Manually-triggered verification skill that spawns a fresh-context subagent to review finished documentation prose. The subagent re-executes commands, validates examples, and checks factual claims against the repository to catch errors the original author might have missed.

Re-runs terminal commands shown in docs to verify output blocks match reality
Validates example specs and changes using openspec validate
Checks all command flags, paths, config keys, and behavior claims against source
Verifies CLI names and behavior against --help and skill sources
Flags structural issues, vague claims, hype language, and trust problems

How to install verify-openspec-docs

npx skills add https://github.com/fission-ai/openspec --skill verify-openspec-docs

Prerequisites

OpenSpec repository with docs tree and README.md
Access to run read-only commands and validate specs
Absolute paths to repo root and docs tree

Claude Code

Cursor

Windsurf

Cline

How to use verify-openspec-docs

1.Confirm the target: a full page, one section (##), or a list of specific claims
2.Provide the absolute path to the docs tree and repo root
3.The skill spawns a subagent that reads the docs README and writing rules
4.The subagent re-runs commands, validates examples, and checks facts
5.Review the report ranked by severity; each finding includes the quoted line and one-line fix
6.Apply fixes only if you approve them or requested verify-and-fix mode
7.If factual claims changed, request a second verification pass

Use cases

Good for

Verify a single documentation page before publishing
Fact-check a specific section or set of changed claims
Validate example code and terminal output in docs
Review documentation for accuracy before handoff to docs owner
Catch factual errors and vague language that cold readers would notice

Who it's for

Documentation authors and reviewers
Technical writers maintaining OpenSpec docs
Teams doing peer review of user-facing documentation
Anyone ensuring docs accuracy before publication

verify-openspec-docs FAQ

When should I use this vs. the write-openspec-docs skill?

Use write-openspec-docs for drafting new docs. Use verify-openspec-docs only when you want to fact-check finished prose—it's manually triggered and not part of the drafting loop.

Can the subagent modify the docs directly?

No. The default is report-only: you see findings ranked by severity with quoted lines and one-line fixes. You approve before any changes are applied.

What if the subagent can't verify a claim?

The report lists any unverifiable claims and why. You can then investigate, update the docs, and request another verification pass.

Does the subagent inherit my skills?

No. The skill passes all needed context by absolute path: the docs README, writing rules, and the target page or section.

What counts as a fact-check failure?

Mismatched command output, invalid example specs, wrong flag names, broken paths, vague claims without evidence, hype language, and structural violations of the docs README rules.

Full instructions (SKILL.md)

Source of truth, from fission-ai/openspec.

name: verify-openspec-docs description: Fact-checks OpenSpec user documentation with a fresh-context subagent that re-runs commands and checks claims against source. Manually triggered; not part of the drafting loop. Use when the user asks to verify, fact-check, or accuracy-check a docs page, section, or set of changed claims. argument-hint: page or section

Verify OpenSpec docs

Check finished docs prose against reality. The point of a fresh context is that the reviewer hasn't watched the prose get written, so it can't be talked into the author's assumptions.

This skill runs only when the user asks for it. Drafting is owned by write-openspec-docs; don't invoke this from inside a drafting session unless the user requests a verification pass.

Scope the run

Confirm the target: a page, one ## section, or a list of changed claims. If invoked without a target, ask.
Read the README at the root of the docs tree the target lives in; its invariants and page map are part of what gets checked.
One subagent per unit (one ## section, or the stated claim list). A full page is several subagents, run in parallel.

Spawn the reviewer

General-purpose subagent. Subagents don't inherit skills, so the prompt hands the reviewer everything by path. Fill every placeholder, make every path absolute, and send:

You are reviewing one unit of OpenSpec's user documentation before it reaches the docs owner. Be the two hardest readers it will meet: a skeptical developer reading it cold, and a fact-checker with the repo open.

Repo root: <ABSOLUTE REPO ROOT>. Use absolute paths with every tool.

Read first:
1. <DOCS TREE ROOT>/README.md: the page map and standing invariants.
2. <ABSOLUTE REPO ROOT>/.agents/skills/write-openspec-docs/writing.md: the house writing rules.
3. <PAGE PATH>: review only <the section "<HEADING>" | these changed claims: <LIST>>; read the rest of the page for context.

Then check, in this order:

1. Facts. Every command, flag, path, config key, output block, default, and behavior claim. Re-run the terminal commands shown: read-only commands anywhere, anything that mutates state in a scratch directory or not at all. Commands for the AI chat surface (like /opsx:propose) can't run in a shell; verify their names and behavior against the skill sources this repo ships. Check names against src/ and the CLI's own --help. An output block must match what the command actually prints.
2. Examples. Any example spec or change must pass `openspec validate`. Run it when the example exists on disk.
3. Structure. Flag anything that re-explains a topic whose canonical home is another page, or breaks a rule the docs tree's README states.
4. Job fit. Does the unit serve the page's stated job (the one-line statement under the title, if present)? Does the arriving reader get what they came for quickly?
5. Trust and slop. Flag: hype or comfort adjectives (easy, simple, powerful, seamless), claims with no shown evidence, vague generalization where a specific fact belongs, binary contrasts ("not X, it's Y"), colon reveals, importance puffery, summary endings, em dashes, bullet lists that should be prose, and three parallel punchy sentences in a row.

Report findings only, most severe first. For each: quote the line, say what is wrong, and give the fix in one line. For every fact you verified, say how (the command you ran, or the file and line you checked). List any claim you could not verify and why. Do not rewrite the unit. If the unit is clean, say so and list exactly what you verified.

Handle the report

Default is report, not rewrite: show the user the findings ranked most severe first, each with the quoted line and one-line fix, plus what was verified and how, and any claim the reviewer couldn't verify.
Apply fixes only when the user asked for a verify-and-fix run or approves the findings. A verifier can also be wrong: rejections go in the report with your reason, so the user can overrule you.
If an applied fix changed a factual claim, verify again, scoped to the changed claims. Typo and wording fixes don't need a second pass.
Two passes without converging means stop and take it to the user. Don't polish in a loop.