KEY FEATURES:

• Codebase scanning for accurate facts
• 5-layer anti-hallucination validation
• Script execution testing
• Citation tracking for all claims
• Template-based structure selection

DIFFERENTIATOR: Every claim verified against actual codebase. No assumptions, no hallucinations. Script execution testing ensures examples work.

README Expert

Create comprehensive README.md files grounded in codebase reality.

Overview

README Expert uses validation-first methodology to generate accurate, comprehensive README files by:

1. Scanning actual codebase - Extract facts from real files (no assumptions)
2. Verifying every claim - 5-layer validation ensures accuracy
3. Testing all scripts - Execute commands/examples to ensure they work
4. Tracking citations - Every statement traceable to source files
5. Quality standards - Follows standard-readme and Google style guides

Anti-Hallucination Core: Research shows AI README hallucinations occur in 3-27% of outputs. This skill reduces that to near-zero through systematic verification.

Workflow Decision Tree

Choose workflow based on task:

┌─────────────────────────────────────┐
│   What is your README task?         │
└───────────┬─────────────────────────┘
            │
    ┌───────┴───────┐
    │               │
    ▼               ▼
┌─────────┐   ┌──────────┐
│ CREATE  │   │ VALIDATE │
│   NEW   │   │ EXISTING │
└────┬────┘   └────┬─────┘
     │             │
     ▼             ▼
  Section 1     Section 2
  (Full Flow)  (Validation Only)

Decision Criteria:

Section 1: Full README Creation Workflow

Use when: Creating new README or major overhaul.

Time: 3-5 minutes with automation Output: Complete, validated README.md Quality Target: 95%+ accuracy, 0 hallucinations

Phase 1: Codebase Scanning (2 min)

Goal: Extract accurate project facts from actual files.

Load Knowledge: knowledge/foundation/codebase-scanner.md

Steps:

1. Detect Project Type

   # Find config files
   Glob: pattern="{package.json,pyproject.toml,Cargo.toml,go.mod}"
   # Read detected file
   Read: file_path="<detected_config>"
   

2. Extract Metadata

   • Project name, version, description (exact quotes)
   • Dependencies (actual, not assumed)
   • Entry points / CLI commands
   • Author, license, repo URL

3. Scan Structure

   # Find source directories
   Glob: pattern="src/**/*.{py,js,ts,go,rs}"
   Glob: pattern="lib/**/*.{py,js,ts}"
   # Find tests
   Glob: pattern="{tests,test,__tests__}/**/*"
   # Find docs
   Glob: pattern="docs/**/*.md"
   

4. Discover Features

   # Find public API
   Grep: pattern="^(export|class|def)\s+\w+" output_mode="content"
   # Find CLI commands
   Grep: pattern="(scripts|entry_points|bin)" path="<config_file>"
   # Find environment variables
   Grep: pattern="(process\.env|os\.environ|os\.Getenv)"
   

Output: Verified project facts with source citations.

Anti-Hallucination Check: Every fact must have source file reference.

Phase 2: Template Selection (30 sec)

Goal: Choose appropriate README structure.

Load Knowledge: knowledge/application/template-library.md

Templates by Project Type:

Selection Criteria:

• Check package.json "bin" field → CLI template
• Check pyproject.toml [project.scripts] → CLI template
• Check "dependencies" with "express|fastify|flask" → API template
• Check "src/components" or "react|vue|svelte" → Web App template
• Default: Library template

Output: Selected template structure.

Phase 3: README Generation (1 min)

Goal: Write README sections with verified content.

Standard Structure:

1. Title & Badges

   # {project_name}
   
   > {description from package metadata - EXACT quote}
   
   ![CI Status](badge_url) ![Version](badge_url) ![License](badge_url)
   

   Verification:

   • Name from package.json:name
   • Description from package.json:description (exact)
   • Badge URLs verified against .github/workflows/ files

2. Installation

   ## Installation
   
   ```bash
   npm install {exact_package_name}
   

   
   **Verification:**
   - Package name from metadata (exact)
   - Installation command matches package manager detected
   - Prerequisites from "engines" field
   
   

3. Usage Examples

   ## Usage
   
   ```javascript
   import { functionName } from 'package-name'
   
   // Example verified from examples/ directory or tests/
   const result = functionName(input)
   

   
   **Verification:**
   - Imports verified: Grep for actual exports
   - Function signatures extracted from actual code
   - Examples copied from examples/ or tests/ directories
   
   

4. API Documentation

   ## API
   
   ### `functionName(param: Type): ReturnType`
   
   Description verified from code comments/docstrings.
   

   Verification:

   • Function signatures extracted with Grep
   • Parameters from actual function definitions
   • Descriptions from docstrings (if present)

5. Configuration

   ## Configuration
   
   Required environment variables:
   - `VAR_NAME` - Description from .env.example
   

   Verification:

   • Variables found in code with Grep
   • Descriptions from .env.example (if exists)

6. Testing

   ## Testing
   
   ```bash
   npm test
   

   
   **Verification:**
   - Test command from package.json scripts.test
   - Test framework detected from dependencies
   
   

7. Contributing, License, Contact

   ## Contributing
   
   See [CONTRIBUTING.md](./CONTRIBUTING.md)
   
   ## License
   
   {license from package.json} - See [LICENSE](./LICENSE)
   

   Verification:

   • CONTRIBUTING.md existence checked
   • LICENSE file existence checked
   • License type from package metadata

Output: Complete README draft with inline citations.

Phase 4: Validation (1-2 min)

Goal: Verify all claims are accurate.

Load Knowledge: knowledge/foundation/validation-checklist.md

Execute 5-Layer Validation:

Layer 1: File Existence

# Verify all referenced files
Read: file_path="<each_referenced_file>"
# Pass: File exists ✅
# Fail: Remove reference from README ❌

Layer 2: Content Accuracy

• Compare README claims against actual file contents
• Verify function signatures match actual code
• Check version numbers match package.json exactly
• Confirm descriptions are exact quotes (not paraphrased)

Layer 3: Execution Validity Load Knowledge: knowledge/application/script-executor.md

# Test installation command (if safe)
# Test CLI commands with --help flag
# Extract code examples to temp files and execute

Layer 4: Link Integrity

# Internal links
Read: file_path="<each_linked_file>"

# External URLs (sample check)
WebFetch: url="<external_url>" prompt="Check accessibility"

# Anchor links
Grep: pattern="^#+\s+{anchor_text}" path="README.md"

Layer 5: Citation Traceability

• Every claim has source file:line reference (internal tracking)
• Confidence scores: 100% (direct quote), 90% (extracted), 70%+ required
• Remove any claim with confidence <70%

Output: Validation report with pass/fail for each layer.

Phase 5: Quality Assessment (30 sec)

Goal: Ensure README meets quality standards.

Load Knowledge: knowledge/application/quality-standards.md

Quality Checklist:

• Completeness: All required sections present
• Accuracy: All claims verified (95%+ confidence)
• Clarity: Readable, concise, well-structured
• Functional: All commands/examples tested
• Standard Compliance: Follows standard-readme spec
• Links: All links valid and working
• Length: Not too short (<50 lines) or too long (>500 lines)
• TOC: Table of contents if >100 lines
• Badges: Relevant and accurate
• License: Clearly stated

Scoring Rubric:

• 9-10/10: Excellent - All criteria met
• 7-8/10: Good - Minor improvements needed
• 5-6/10: Fair - Several issues to fix
• <5/10: Poor - Major revision required

Target: ≥8/10 for publication

Output: Quality score and improvement recommendations.

Phase 6: Final Output

Deliverables:

1. README.md - Complete, validated file
2. Validation Report - Results from 5-layer validation
3. Citation Map (optional) - Source tracking for audit
4. Quality Score - Final assessment

Final Checks Before Delivery:

• No TODOs or placeholder text
• No broken links
• No unverified claims
• All code examples tested (where possible)
• No marketing fluff without evidence

Section 2: Validation-Only Workflow

Use when: README exists, need to verify accuracy.

Time: 2-3 minutes Output: Validation report with pass/fail status

Quick Validation Process

1. Load Knowledge: knowledge/foundation/validation-checklist.md

2. Execute 5-Layer Validation:

   • Layer 1: File Existence (verify all referenced files)
   • Layer 2: Content Accuracy (check claims match reality)
   • Layer 3: Execution Validity (test commands/scripts)
   • Layer 4: Link Integrity (validate all URLs/links)
   • Layer 5: Citation Traceability (audit claim sources)

3. Generate Report:

   README Validation Report
   ========================
   Layer 1: ✅ PASS / ❌ FAIL (details)
   Layer 2: ✅ PASS / ⚠️ WARNING (details)
   Layer 3: ✅ PASS / ❌ FAIL (details)
   Layer 4: ✅ PASS / ❌ FAIL (details)
   Layer 5: ✅ PASS / ⚠️ WARNING (details)
   
   OVERALL: ✅ READY / ⚠️ NEEDS FIXES / ❌ MAJOR ISSUES
   Hallucination Risk: LOW/MEDIUM/HIGH
   Confidence: XX%
   

4. Provide Fix Recommendations:

   • List specific issues found
   • Suggest corrections with source file references
   • Prioritize critical fixes (broken links, false claims)

Anti-Hallucination Principles

Core Rules (Always Follow):

1. ✅ DO: Verify every file reference with Read/Glob

2. ✅ DO: Extract exact quotes from source files

3. ✅ DO: Test commands before documenting them

4. ✅ DO: Link claims to source files (internal tracking)

5. ✅ DO: Acknowledge uncertainty when confidence <90%

6. ❌ DON'T: Assume standard structure without checking

7. ❌ DON'T: Invent features not found in code

8. ❌ DON'T: Copy examples from other projects

9. ❌ DON'T: Paraphrase or "improve" actual descriptions

10. ❌ DON'T: Include marketing claims without evidence

Hallucination Detection Patterns:

Knowledge Base Reference

All detailed guides are in knowledge/ directory.

Quick Access:

• Scanning techniques: knowledge/foundation/codebase-scanner.md
• Validation checklist: knowledge/foundation/validation-checklist.md
• Script testing: knowledge/application/script-executor.md
• Templates: knowledge/application/template-library.md
• Quality standards: knowledge/application/quality-standards.md

Navigation: See knowledge/INDEX.md for complete map.

Best Practices

1. Start with scanning - Gather facts before writing
2. Use templates - Don't reinvent structure
3. Quote exactly - Never paraphrase metadata
4. Test everything - Execute commands where safe
5. Validate thoroughly - All 5 layers, no shortcuts
6. Acknowledge gaps - Mark uncertain info clearly
7. Keep it concise - Link to detailed docs instead of duplicating
8. Update regularly - Validate README on major code changes

Common Use Cases

Use Case 1: New Project README

User: "Create a README for my new npm package"
→ Section 1 (Full Workflow)
→ Scan package.json → Select template → Generate → Validate → Deliver

Use Case 2: Validate Accuracy

User: "Check if my README is still accurate"
→ Section 2 (Validation Only)
→ Run 5-layer validation → Report issues → Suggest fixes

Use Case 3: Update After Refactor

User: "Update README after refactoring API"
→ Section 1 (Focus on API section)
→ Scan new API → Update API section → Validate → Deliver

Use Case 4: Test Examples

User: "Make sure all code examples in README work"
→ Section 2 Layer 3 (Execution Validity)
→ Extract examples → Execute → Report failures → Fix

Technical Notes

Token Efficiency:

• P0 knowledge files: ~530 tokens
• P1 knowledge files: ~830 tokens
• Total knowledge: ~1,360 tokens (well under 5k limit)
• On-demand loading: Load only sections needed

Confidence Scoring:

• 100%: Direct file quote
• 90%: Extracted from code analysis
• 80%: Inferred from multiple sources
• 70%: Based on conventions
• <70%: Reject (too risky)

Script Execution Safety:

• Always ask permission before executing destructive commands
• Safe: --help, --version, --list
• Risky: install, build, deploy
• Dangerous: rm, drop, delete

Version

Current Version: 1.0 Last Updated: 2025-11-13 Status: Production Ready

Changelog:

• v1.0: Initial release with validation-first approach
• Added script execution testing
• 5-layer anti-hallucination validation
• Citation tracking system