Initial commit
This commit is contained in:
Zhongwei Li
337
commands/best-practices/validate-keywords.md
Normal file
337
commands/best-practices/validate-keywords.md
Normal file
@@ -0,0 +1,337 @@
|
||||
## Operation: Validate Keywords
|
||||
|
||||
Validate keyword selection for relevance, count, and quality against OpenPlugins standards.
|
||||
|
||||
### Parameters from $ARGUMENTS
|
||||
|
||||
- **keywords**: Comma-separated keyword list (required)
|
||||
- **min**: Minimum keyword count (optional, default: 3)
|
||||
- **max**: Maximum keyword count (optional, default: 7)
|
||||
- **context**: Plugin context for relevance checking (optional, JSON or description)
|
||||
|
||||
### OpenPlugins Keyword Standards
|
||||
|
||||
**Count Requirements**:
|
||||
- Minimum: 3 keywords
|
||||
- Maximum: 7 keywords
|
||||
- Optimal: 5-6 keywords
|
||||
|
||||
**Quality Requirements**:
|
||||
- Relevant to plugin functionality
|
||||
- Searchable terms users would use
|
||||
- Mix of functionality, technology, and use-case
|
||||
- No generic marketing terms
|
||||
- No duplicate category names
|
||||
|
||||
### Keyword Categories
|
||||
|
||||
**Functionality Keywords** (what it does):
|
||||
- `testing`, `deployment`, `formatting`, `linting`, `migration`
|
||||
- `generation`, `automation`, `analysis`, `monitoring`, `scanning`
|
||||
|
||||
**Technology Keywords** (what it works with):
|
||||
- `python`, `javascript`, `docker`, `kubernetes`, `postgresql`
|
||||
- `react`, `vue`, `typescript`, `bash`, `terraform`
|
||||
|
||||
**Use-Case Keywords** (how it's used):
|
||||
- `ci-cd`, `code-review`, `api-testing`, `performance`
|
||||
- `tdd`, `bdd`, `refactoring`, `debugging`, `profiling`
|
||||
|
||||
### Good Keywords Examples
|
||||
|
||||
**Well-balanced sets**:
|
||||
- `["testing", "pytest", "automation", "tdd", "python"]`
|
||||
- `["deployment", "kubernetes", "ci-cd", "docker", "helm"]`
|
||||
- `["linting", "javascript", "eslint", "code-quality", "automation"]`
|
||||
- `["database", "postgresql", "migration", "schema", "sql"]`
|
||||
|
||||
**Poor keyword sets**:
|
||||
- `["plugin", "tool", "awesome"]` - Generic/marketing terms
|
||||
- `["test", "testing", "tester", "tests"]` - Redundant variations
|
||||
- `["development"]` - Only category name, too few
|
||||
- `["a", "b", "c", "d", "e", "f", "g", "h"]` - Too many, non-descriptive
|
||||
|
||||
### Workflow
|
||||
|
||||
1. **Extract Keywords from Arguments**
|
||||
```
|
||||
Parse $ARGUMENTS to extract keywords parameter
|
||||
Split by comma, trim whitespace
|
||||
Normalize to lowercase
|
||||
Remove duplicates
|
||||
```
|
||||
|
||||
2. **Execute Keyword Analyzer**
|
||||
```bash
|
||||
Execute .scripts/keyword-analyzer.py "$keywords" "$min" "$max" "$context"
|
||||
|
||||
Exit codes:
|
||||
- 0: Valid keyword set
|
||||
- 1: Count violation (too few or too many)
|
||||
- 2: Quality issues (generic terms, duplicates)
|
||||
- 3: Missing required parameters
|
||||
```
|
||||
|
||||
3. **Validate Count**
|
||||
```
|
||||
count = number of keywords
|
||||
IF count < min: FAIL (too few)
|
||||
IF count > max: FAIL (too many)
|
||||
```
|
||||
|
||||
4. **Check for Generic Terms**
|
||||
```
|
||||
Generic blocklist:
|
||||
- plugin, tool, utility, helper, awesome
|
||||
- best, perfect, great, super, amazing
|
||||
- code, software, app, program
|
||||
|
||||
Flag any generic terms found
|
||||
```
|
||||
|
||||
5. **Analyze Quality**
|
||||
```
|
||||
Check for:
|
||||
- Duplicate category names
|
||||
- Redundant variations (test, testing, tests)
|
||||
- Single-character keywords
|
||||
- Non-descriptive terms
|
||||
```
|
||||
|
||||
6. **Calculate Relevance Score**
|
||||
```
|
||||
Base score: 10 points
|
||||
|
||||
Deductions:
|
||||
- Generic term: -2 per term
|
||||
- Too few keywords: -5
|
||||
- Too many keywords: -3
|
||||
- Redundant variations: -2 per redundancy
|
||||
- Non-descriptive: -1 per term
|
||||
|
||||
Final score: max(0, base - deductions)
|
||||
```
|
||||
|
||||
7. **Return Analysis Report**
|
||||
```
|
||||
Format results:
|
||||
- Status: PASS/FAIL/WARNING
|
||||
- Count: <number> (valid range: min-max)
|
||||
- Quality: <score>/10
|
||||
- Issues: <list of problems>
|
||||
- Suggestions: <improved keyword set>
|
||||
- Score impact: +10 points (if excellent), +5 (if good)
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Valid keyword set
|
||||
/best-practices keywords keywords:"testing,pytest,automation,tdd,python"
|
||||
# Result: PASS - 5 keywords, well-balanced, relevant
|
||||
|
||||
# Too few keywords
|
||||
/best-practices keywords keywords:"testing,python"
|
||||
# Result: FAIL - Only 2 keywords (minimum: 3)
|
||||
|
||||
# Too many keywords
|
||||
/best-practices keywords keywords:"a,b,c,d,e,f,g,h,i,j"
|
||||
# Result: FAIL - 10 keywords (maximum: 7)
|
||||
|
||||
# Generic terms
|
||||
/best-practices keywords keywords:"plugin,tool,awesome,best"
|
||||
# Result: FAIL - Contains generic/marketing terms
|
||||
|
||||
# With custom range
|
||||
/best-practices keywords keywords:"ci,cd,docker" min:2 max:5
|
||||
# Result: PASS - 3 keywords within custom range
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Missing keywords parameter**:
|
||||
```
|
||||
ERROR: Missing required parameter 'keywords'
|
||||
|
||||
Usage: /best-practices keywords keywords:"keyword1,keyword2,keyword3"
|
||||
|
||||
Example: /best-practices keywords keywords:"testing,automation,python"
|
||||
```
|
||||
|
||||
**Empty keywords**:
|
||||
```
|
||||
ERROR: Keywords cannot be empty
|
||||
|
||||
Provide 3-7 relevant keywords describing your plugin.
|
||||
|
||||
Good examples:
|
||||
- "testing,pytest,automation"
|
||||
- "deployment,kubernetes,ci-cd"
|
||||
- "linting,javascript,code-quality"
|
||||
```
|
||||
|
||||
### Output Format
|
||||
|
||||
**Success (Excellent Keywords)**:
|
||||
```
|
||||
✅ Keyword Validation: PASS
|
||||
|
||||
Keywords: testing, pytest, automation, tdd, python
|
||||
Count: 5 (optimal range: 3-7)
|
||||
Quality Score: 10/10
|
||||
|
||||
Analysis:
|
||||
✅ Balanced mix of functionality, technology, and use-case
|
||||
✅ All keywords relevant and searchable
|
||||
✅ No generic or marketing terms
|
||||
✅ Good variety without redundancy
|
||||
|
||||
Breakdown:
|
||||
- Functionality: testing, automation, tdd
|
||||
- Technology: pytest, python
|
||||
- Use-case: tdd
|
||||
|
||||
Quality Score Impact: +10 points
|
||||
|
||||
Excellent keyword selection for discoverability!
|
||||
```
|
||||
|
||||
**Failure (Count Violation)**:
|
||||
```
|
||||
❌ Keyword Validation: FAIL
|
||||
|
||||
Keywords: testing, python
|
||||
Count: 2 (required: 3-7)
|
||||
Quality Score: 5/10
|
||||
|
||||
Issues Found:
|
||||
1. Too few keywords (2 < 3 minimum)
|
||||
2. Missing technology or use-case keywords
|
||||
|
||||
Suggestions to improve:
|
||||
Add 1-3 more relevant keywords such as:
|
||||
- Functionality: automation, unit-testing
|
||||
- Use-case: tdd, ci-cd
|
||||
- Specific tools: pytest, unittest
|
||||
|
||||
Recommended: testing, python, pytest, automation, tdd
|
||||
|
||||
Quality Score Impact: 0 points (fix to gain +10)
|
||||
```
|
||||
|
||||
**Failure (Generic Terms)**:
|
||||
```
|
||||
❌ Keyword Validation: FAIL
|
||||
|
||||
Keywords: plugin, tool, awesome, best, helper
|
||||
Count: 5 (valid range)
|
||||
Quality Score: 2/10
|
||||
|
||||
Issues Found:
|
||||
1. Generic terms detected: plugin, tool, helper
|
||||
2. Marketing terms detected: awesome, best
|
||||
3. No functional or technical keywords
|
||||
|
||||
These keywords don't help users find your plugin.
|
||||
|
||||
Better alternatives:
|
||||
Instead of generic terms, describe WHAT it does:
|
||||
- Replace "plugin" → testing, deployment, formatting
|
||||
- Replace "tool" → specific functionality
|
||||
- Replace "awesome/best" → actual features
|
||||
|
||||
Suggested keywords based on common patterns:
|
||||
- testing, automation, ci-cd, docker, python
|
||||
- deployment, kubernetes, infrastructure, terraform
|
||||
- linting, formatting, code-quality, javascript
|
||||
|
||||
Quality Score Impact: 0 points (fix to gain +10)
|
||||
```
|
||||
|
||||
**Warning (Minor Issues)**:
|
||||
```
|
||||
⚠️ Keyword Validation: WARNING
|
||||
|
||||
Keywords: testing, tests, test, automation, ci-cd
|
||||
Count: 5 (valid range)
|
||||
Quality Score: 7/10
|
||||
|
||||
Issues Found:
|
||||
1. Redundant variations: testing, tests, test
|
||||
2. Consider consolidating to single term
|
||||
|
||||
Suggestions:
|
||||
- Keep: testing, automation, ci-cd
|
||||
- Remove: tests, test (redundant)
|
||||
- Add: 2 more specific keywords (e.g., pytest, junit)
|
||||
|
||||
Recommended: testing, automation, ci-cd, pytest, unit-testing
|
||||
|
||||
Quality Score Impact: +7 points (good, but could be better)
|
||||
|
||||
Your keywords are functional but could be more diverse.
|
||||
```
|
||||
|
||||
### Keyword Quality Checklist
|
||||
|
||||
**PASS Requirements**:
|
||||
- 3-7 keywords total
|
||||
- No generic terms (plugin, tool, utility, helper)
|
||||
- No marketing terms (awesome, best, perfect)
|
||||
- No redundant variations
|
||||
- Mix of functionality and technology
|
||||
- Relevant to plugin purpose
|
||||
- Searchable by target users
|
||||
|
||||
**FAIL Indicators**:
|
||||
- < 3 or > 7 keywords
|
||||
- Contains generic terms
|
||||
- Contains marketing fluff
|
||||
- All keywords same type (only technologies, only functionality)
|
||||
- Single-character keywords
|
||||
- Category name duplication
|
||||
|
||||
### Best Practices
|
||||
|
||||
**Do**:
|
||||
- Use specific functionality terms
|
||||
- Include primary technologies
|
||||
- Add relevant use-cases
|
||||
- Think about user search intent
|
||||
- Balance breadth and specificity
|
||||
|
||||
**Don't**:
|
||||
- Use generic words (plugin, tool, utility)
|
||||
- Add marketing terms (best, awesome, perfect)
|
||||
- Duplicate category names exactly
|
||||
- Use redundant variations
|
||||
- Add irrelevant technologies
|
||||
- Use abbreviations without context
|
||||
|
||||
### Quality Scoring Matrix
|
||||
|
||||
**10/10 - Excellent**:
|
||||
- 5-6 keywords
|
||||
- Perfect mix of functionality/technology/use-case
|
||||
- All highly relevant
|
||||
- Great search discoverability
|
||||
|
||||
**7-9/10 - Good**:
|
||||
- 3-7 keywords
|
||||
- Good mix with minor issues
|
||||
- Mostly relevant
|
||||
- Decent discoverability
|
||||
|
||||
**4-6/10 - Fair**:
|
||||
- Count issues OR some generic terms
|
||||
- Imbalanced mix
|
||||
- Partial relevance
|
||||
- Limited discoverability
|
||||
|
||||
**0-3/10 - Poor**:
|
||||
- Severe count violations OR mostly generic
|
||||
- No functional keywords
|
||||
- Poor relevance
|
||||
- Very poor discoverability
|
||||
|
||||
**Request**: $ARGUMENTS
|
||||
Reference in New Issue
Block a user