spec-grounding

Ground acceptance criteria against codebase evidence and recall with citations.

1|Updated Mar 15, 2026
One-click install
npx skills add https://github.com/paulingham/.claude --skill spec-grounding
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spec-grounding
Source: https://github.com/paulingham/.claude/tree/main/skills/spec-grounding
Command: npx skills add https://github.com/paulingham/.claude --skill spec-grounding

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Ground raw acceptance criteria against codebase evidence and recall to verify that plans are grounded in verifiable sources.

Core Features & Use Cases

  • Ground ACs against codebase evidence and recall to produce citations.
  • Detect grounding gaps where no evidence exists, enabling architect review.
  • Flag potential contradictions between ACs for non-blocking advisory guidance.

Quick Start

Run the grounding workflow by supplying the intake ACs and the repository root to the grounding helper to produce a spec-grounding.md report.

Frequently Asked Questions about spec-grounding

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

FAQPage Schema
How do I ground acceptance criteria against codebase evidence in a large monorepo?

Grounding acceptance criteria involves verifying raw ACs against codebase evidence by traversing up to 5000 files in large monorepos. The Skill reads intake.md and outputs a spec-grounding.md report containing per-AC citations and a final verdict.

What happens when acceptance criteria have no grounding evidence in the codebase?

When acceptance criteria lack grounding evidence, the Skill detects these grounding gaps and flags them in the spec-grounding.md report. This highlights missing evidence to enable necessary architect review before proceeding.

Can I use recall integration to verify acceptance criteria grounding?

Yes, recall integration is optionally supported to verify acceptance criteria grounding by setting the CLAUDE_RECALL_DB_PATH environment variable. This supplements codebase traversal to recall evidence and generate grounded ACs.

How does the grounding process handle contradictions between acceptance criteria?

When contradictions exist between acceptance criteria, the grounding process flags them for non-blocking advisory guidance. This helps architects review conflicting ACs without halting the overall codebase grounding workflow.

Does the codebase grounding workflow work effectively for large monorepos?

Codebase grounding works for large monorepos by applying bounded traversal to read up to 5000 files. This constrains the search scope while extracting sufficient evidence to generate grounded acceptance criteria and identify gaps.