gh-dhofheinz-open-plugins-plugins-marketplace-validator-plugin/commands/documentation-validation/check-readme.md

## Operation: Check README Completeness

Validate README.md completeness, structure, and quality against OpenPlugins standards.

### Parameters from $ARGUMENTS

- **path**: Target plugin/marketplace path (required)
- **sections**: Comma-separated required sections (optional, defaults to standard set)
- **min-length**: Minimum character count (optional, default: 500)
- **strict**: Enable strict validation mode (optional, default: false)

### README Requirements

**Required Sections** (case-insensitive matching):
1. **Overview/Description**: Plugin purpose and functionality
2. **Installation**: How to install and configure
3. **Usage**: How to use the plugin with examples
4. **Examples**: At least 2-3 concrete usage examples
5. **License**: License information or reference

**Quality Criteria**:
- Minimum 500 characters (configurable)
- No excessive placeholder text
- Proper markdown formatting
- Working links (if present)
- Code blocks properly formatted

### Workflow

1. **Locate README File**
   ```
   Check for README.md in plugin root
   If not found, check for README.txt or readme.md
   If still not found, report critical error
   ```

2. **Execute README Checker Script**
   ```bash
   Execute .scripts/readme-checker.py with parameters:
   - File path to README.md
   - Required sections list
   - Minimum length threshold
   - Strict mode flag

   Script returns JSON with:
   - sections_found: Array of detected sections
   - sections_missing: Array of missing sections
   - length: Character count
   - quality_score: 0-100
   - issues: Array of specific problems
   ```

3. **Analyze Results**
   ```
   CRITICAL (blocking):
   - README.md file missing
   - Length < 200 characters
   - Missing 3+ required sections

   WARNING (should fix):
   - Length < 500 characters
   - Missing 1-2 required sections
   - Missing examples section

   RECOMMENDATION (nice to have):
   - Add troubleshooting section
   - Expand examples
   - Add badges or visual elements
   ```

4. **Calculate Section Score**
   ```
   score = 100
   score -= (missing_required_sections × 15)
   score -= (length < 500) ? 10 : 0
   score -= (no_examples) ? 15 : 0
   score = max(0, score)
   ```

5. **Format Output**
   ```
   Display:
   - ✅/❌ File presence
   - ✅/⚠️/❌ Each required section
   - Length statistics
   - Quality score
   - Specific improvement recommendations
   ```

### Examples

```bash
# Check README with defaults
/documentation-validation readme path:.

# Check with custom sections
/documentation-validation readme path:./my-plugin sections:"overview,installation,usage,examples,contributing,license"

# Strict validation with higher standards
/documentation-validation readme path:. min-length:1000 strict:true

# Check specific plugin
/documentation-validation readme path:/path/to/plugin sections:"overview,usage,license"
```

### Error Handling

**Error: README.md not found**
```
❌ CRITICAL: README.md file not found in <path>

Remediation:
1. Create README.md in plugin root directory
2. Include required sections: Overview, Installation, Usage, Examples, License
3. Ensure minimum 500 characters of meaningful content
4. See https://github.com/dhofheinz/open-plugins/blob/main/README.md for example

This is a BLOCKING issue - plugin cannot be submitted without README.
```

**Error: README too short**
```
⚠️ WARNING: README.md is only <X> characters (minimum: 500)

Current length: <X> characters
Required: 500 characters minimum
Gap: <500-X> characters

Remediation:
- Expand installation instructions with examples
- Add 2-3 usage examples with code blocks
- Include configuration options
- Add troubleshooting section
```

**Error: Missing required sections**
```
❌ ERROR: Missing <N> required sections

Missing sections:
- Installation: How to install the plugin
- Examples: At least 2 concrete usage examples
- License: License information or reference to LICENSE file

Remediation:
Add each missing section with meaningful content.
See CONTRIBUTING.md for section requirements.
```

### Output Format

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
README VALIDATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

File: ✅ README.md found

Required Sections:
✅ Overview/Description
✅ Installation
✅ Usage
⚠️  Examples (found 1, recommended: 3+)
✅ License

Length: <X> characters (minimum: 500) ✅

Quality Score: <0-100>/100

Issues Found: <N>

Critical (blocking): <count>
Warnings (should fix): <count>
Recommendations: <count>

Top Recommendations:
1. Add 2 more usage examples with code blocks [+15 pts]
2. Expand installation section with configuration options [+5 pts]
3. Include troubleshooting section [+5 pts]

Overall: <PASS|WARNINGS|FAIL>
```

### Integration

This operation is invoked by:
- `/documentation-validation readme path:.` (direct)
- `/documentation-validation full-docs path:.` (as part of complete validation)
- `/validation-orchestrator comprehensive path:.` (via orchestrator)

Results feed into quality-analysis scoring system.

**Request**: $ARGUMENTS