skilld
All skills
oaustegard avatar

/verifying-claims

@4b31e7d
by Oskar Austegardoaustegard/claude-skills150 stars
6

Check that a document's claims about code are actually true by reading the prose, the code, and the tests and reporting (or fixing) where they disagree. Use whenever the user wants to verify a README, guide, spec, or docstring still matches the code; whenever they mention documentation drift, doc-code sync, "is this still accurate", stale docs, or keeping docs/tests/code consistent; before publishing or merging a docs change; or as a periodic doc-accuracy sweep. The agent reads the prose's meaning directly — there is no claim-comment DSL to maintain. Pairs with TDD — the test suite is the deterministic behavioral gate, this skill is the semantic prose-vs-reality review.

Ask your Agent

Use this Skill: https://skilld.dev/gh/oaustegard/claude-skills/verifying-claims

This session only. Nothing lands on disk.

CHANGELOG.md

≈440 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Changelog

0.2.0 — 2026-06-07

Pivot: from a claim-comment DSL to an agent-driven review.

The v0.1 model stapled a <!-- claim: ... --> comment beside prose and checked the comment against the code. That left the prose — the half humans actually read — unverified, and was out-engineered on both flanks (Gherkin binds executable scenarios; Lean's Verso transcludes facts; TDD couples code to tests). v0.2 fills the remaining slot — free-prose documentation — by having the agent read the prose's meaning and compare it to the code and the tests directly. No DSL, no shadow copy.

  • Removed: scripts/verify_claims.py (the comment parser + signature/ command-output resolvers), assets/verify-claims.yml, assets/ test_verify_claims.py, references/example-spec.md. The CI/pytest forcing functions belonged to the DSL approach; the deterministic gate now lives where it should — the project's own test suite (TDD).
  • Added: scripts/gather_context.py — deterministic input bundler (document + ast-parsed API surface + test inventory), no imports, no execution.
  • Added verdict UNSUPPORTED — claim matches code but no test backs it (a missing test, surfaced as such).
  • Reframed as a triggered review, not a merge gate; the division of labor with TDD is now explicit in SKILL.md.

0.1.0 — 2026-06-06

Initial skill (working title "verso"). Claim-comment DSL with signature and command-output resolvers, --watch, import allowlist, and CI/pytest integration templates. Superseded by 0.2.0.

[0.2.0] - 2026-06-13

Fixed

  • valid YAML frontmatter — colon-space in description broke parsing (#692)

Other

  • verifying-claims v0.2: pivot from claim-DSL to agent-driven doc/code/test review (#691)

Source: SKILL.md on GitHub

Third-party checks

1 warning2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill is well-implemented and uses safe techniques like AST parsing to inspect code without execution. However, it is susceptible to indirect prompt injection because it ingests untrusted documentation and source code into the agent's context without explicit security boundaries or sanitization. Mitigations include adding human review checkpoints and explicit instructions for the agent to ignore any commands found within the analyzed documentation.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: MEDIUM · 1 issue

Provenance

Signed by skilld at 4b31e7d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 months ago

Capability

metadata
{
  "version": "0.2.0"
}

README badge

README badge for oaustegard/claude-skills/verifying-claims