Ground README — Audit or generate honest project listings

You are either auditing an existing README/marketplace listing for overpromise and unbacked claims, or generating a new one from actual code with grounding controls.

This is the README-shaped version of the rad-explain principle: every substantive claim in a project's outward-facing copy should be checkable against source, and nothing should use marketing/sensational language. The principle is the same one the rad-claude-skills marketplace applied to its own listings post-audit.

Foundational rules

1. Grounded. Every claim about what the project does must trace to code, docs, or test evidence. The check-grounding.py validator runs against the output.
2. Not overpromising. No "the only" / "world-class" / "revolutionary" / "production-grade" without evidence. The check-overpromise.py validator runs against the output.

These are non-negotiable. If they fail, the skill surfaces findings and offers revision before finalizing.

Modes

audit (most common)

Review an existing README, marketplace listing, plugin.json description, or similar outward-facing copy. Produce a findings report.

Workflow:

1. Read the target file (default: README.md at repo root)
2. Run check-overpromise.py against it
3. Run check-grounding.py against the repo
4. Read the actual code/docs to verify capability claims
5. Surface findings with line numbers + suggested rewrites
6. Optionally write a revised version

Output: a findings report (Markdown) listing:

generate

Create a new README / marketplace listing from actual code with grounding controls.

Workflow:

1. Read the codebase structure (top-level files, directory layout)
2. Read package.json / pyproject.toml / equivalent for description, dependencies, entry points
3. Read docs/vision.md if present (highest-signal for project intent)
4. Identify capabilities by walking source (public exports, CLI entry points, documented commands)
5. Identify dependencies and external requirements
6. Draft the README with sections grounded in actual source
7. Run validators
8. Write the output

Output: a Markdown README following the standard shape (Install, Usage, Features, Examples, License) but constrained to what the code actually supports.

Workflow

Step 1: Determine mode and target

If --mode was passed, use it. Otherwise infer:

• If there's an existing README.md and the user said "audit" / "review" / "check" → audit
• If they said "generate" / "create" / "write" → generate
• If ambiguous, ask

Default target for audit: README.md at repo root. Otherwise the user can specify a marketplace listing JSON path or plugin.json or similar.

Step 2 (audit only): Read target + run validators

Read the target file. Run both validators:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/check-overpromise.py <target> --json
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/check-grounding.py <target> --repo <repo-root> --json

Capture results.

Step 2 (generate only): Read source

In parallel:

• Project manifest (package.json / pyproject.toml / Cargo.toml / go.mod / etc.)
• docs/vision.md / docs/README.md / docs/getting-started.md if present
• Top-level directory structure
• Source files for public-API surfaces (e.g., index.ts, __init__.py, lib.rs)
• Test directory (signal for what's actually verified)
• CHANGELOG.md if present
• Any existing README (to migrate or replace)

Step 3 (audit only): Cross-check capability claims

For each capability claim in the target (e.g., "supports X", "integrates with Y", "validates Z"):

1. Extract the claim's substantive terms (X, Y, Z)
2. Grep the repo for those terms in source files
3. Read the matched contexts to verify the capability is actually implemented
4. Classify each claim:

• Backed: source supports the claim
• Unbacked-token-absent: claim's terms not in source at all
• Unbacked-token-present-but-no-implementation: terms appear (often in commit messages or unrelated docs) but implementation isn't there
• Stale: source had this once but no longer does

Step 4 (audit only): Identify under-promising

Walk the source for capabilities the README doesn't mention:

• Public exports / CLI commands / API endpoints not documented in README
• Configuration options not documented
• Test coverage / supported platforms / dependency requirements that would be useful for users

Flag these as info-severity "missing claim" findings. (Some are intentional omissions; some are real gaps.)

Step 5 (generate only): Draft section by section

Standard README sections (skip any without source backing):

1. Title (project name, from manifest)
2. One-line description (from manifest description field, refined for accuracy)
3. What it does (from vision.md or inferred from source — public API surface)
4. Install (from manifest install command + any setup steps in docs/getting-started.md)
5. Usage (concrete example using actual public API; pulled from existing tests or README, NOT invented)
6. Configuration (only if present in source — flag found options)
7. Requirements (dependencies from manifest)
8. Development (commands from scripts in package.json or similar; tests, build, lint commands)
9. License (from LICENSE file)

For each section, the substantive content must come from a specific file. If a section has no source, omit it.

Step 6: Run validators on the output

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/check-overpromise.py <output-path> --json
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/check-grounding.py <output-path> --repo <repo-root> --json

Step 7: Revise based on findings

If either validator surfaces critical/warning findings:

For each finding:

1. Show the user the flagged phrase + suggested replacement
2. Default: replace. User can accept the original.
3. Re-run validators after revision until clean (or user accepts remaining findings)

Step 8: Write output and surface summary

For audit mode, write a findings report (or print to stdout if no --output):

# README Audit: {target-file}

## Overpromise findings

[N critical, M warning, K info]

### Critical: line N "{matched phrase}"
**Suggested rewrite:** "..."

### Warning: line N "{matched phrase}"
**Suggested rewrite:** "..."

...

## Grounding findings

[N unbacked claims]

### Line N: "{claim text}"
Unbacked tokens: {list}
**Suggestion:** {drop | add evidence | rephrase}

...

## Capability mismatches

[N claims source doesn't support]

...

## Missing claims (under-promising)

[N capabilities the source has but README doesn't mention]

...

For generate mode, write the README to <output-path> (default README.md) and surface:

README generated and written to {path}.

Sections written: {list}
Sections skipped (no source backing): {list with reason}
Validators: grounding {pass|N flagged}, overpromise {pass|N flagged}

If you want to add unbacked content (vision-aspirational, marketing context),
add it manually and re-run /rad-explain:ground-readme --mode audit to keep it
in check.

Rendering rules

• Concrete capability claims only ("supports X" must mean source supports X)
• Comparisons must be named ("unlike Y" with Y being a real, named alternative)
• No "the only" / "the first" / "the best" without evidence
• Version numbers, capability counts, and dependency lists must trace to manifest or code
• Examples in Usage section must use actual public API (no invented method names)

Cross-plugin notes

• For a longer project narrative (much more than a README), use narrate-project in this plugin.
• For pitches (different shape — persuasive vs informational), use elevator-pitch or draft-pitch.
• For interpreting a specific file (not generating one), use explain-document.
• Both validators live in this plugin's scripts/ dir.