skills.rest
0xdeafcafe
0xdeafcafeCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

review-spec

Audit Gherkin specs and ADRs for duplication, conflicts, and missing cross-links.

Updated Jun 3, 2026
Search Tags:#adr#spec review#repository analysis#read-only#gherkin#conflict detection#documentation audit
One-click install
npx skills add https://github.com/0xdeafcafe/skills --skill review-spec-0xdeafcafe
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: review-spec
Source: https://github.com/0xdeafcafe/skills/tree/main/skills/review-spec
Command: npx skills add https://github.com/0xdeafcafe/skills --skill review-spec-0xdeafcafe

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you validate a new Gherkin spec or ADR against the documentation that already exists in your repository, so you can catch contradictions, duplicate scenarios, overlapping ownership, and missing architectural links before they create drift.

Core Features & Use Cases

  • Corpus-wide comparison: Searches existing .feature files and ADRs to compare a target spec or decision record against the broader repo.
  • Structured findings by severity: Flags conflicts, duplicates, overlaps, missing cross-links, and orphan decisions with file paths, line numbers, and quoted evidence.
  • Read-only review workflow: Produces an audit report without modifying files, making it safe to run before merging documentation or feature changes.
  • Use cases: Review a newly written feature spec for overlap with existing scenarios, check whether an ADR contradicts accepted decisions, or verify that a PR's changed specs link back to the right architecture records.

Quick Start

Ask the assistant to use review-spec on your new feature file or ADR to audit it against existing specs and architecture decisions in the repository.

Frequently Asked Questions about review-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check a new Gherkin feature file for conflicts with existing scenarios?▼

To detect Gherkin spec conflicts, audit the target feature file against existing repository documentation to flag duplicate scenarios, overlaps, and undocumented assumptions with file paths and line numbers. This read-only review safely prevents documentation drift before merging changes.

What is the best way to validate an ADR against accepted architecture decisions in a repo?▼

Validating an ADR involves searching existing architecture decision records across the repository to flag contradictions, orphan decisions, and missing cross-links. This read-only audit produces an evidence-based report with quoted excerpts to prevent architectural drift.

Can I review ADRs and feature files without modifying my repository?▼

Yes, you can review ADRs and .feature files using a read-only searching workflow that extracts domain signals and produces an audit report. This safe approach flags conflicts and missing cross-links without modifying any markdown or feature files.

How do I find missing cross-links between Gherkin specs and architecture decision records?▼

Finding missing cross-links involves searching markdown and .feature files across the repository to verify that target specs reference the correct architecture decision records. The audit extracts domain signals to report undocumented assumptions with quoted evidence.

Does this documentation audit work for pull request workflows?▼

Yes, this documentation audit applies to pull request workflows by reviewing newly added or modified .feature files and ADRs during planning. It uses read-only searching to catch spec conflicts, overlaps, and undocumented assumptions before changes land.

What are the limitations of automated spec conflict detection?▼

Automated spec conflict detection is limited to read-only searching of markdown and .feature files, meaning it produces an audit report with evidence-based findings rather than automatically resolving conflicts. It does not modify files or fix the detected overlaps and missing cross-links.

Related Skills

Explore More Software Engineering Skills→
aliyunaliyun
580

feature-analysis

Compute descriptive statistics, IV, PSI stability, and Pearson correlation for binary finance datasets.

Official
Advanced
fmflurryfmflurry
171

caveman-review

Generate terse one-line code review findings from pull request diffs.

Community
Intermediate
crgarcia12crgarcia12

test-runner

Execute unit, Gherkin, E2E, and smoke tests with structured results.

Community
Intermediate
striderZAstriderZA
72

skill-test

Validate OpenCode .skil SKILL.md files for compliance and generate deterministic reports.

Community
Advanced