Initial commit

skills/insight-skill-generator/data/quality-checklist.md

@@ -0,0 +1,259 @@
+# Quality Validation Checklist
+
+Generated skills must pass all validation criteria before installation. This checklist ensures compliance with Anthropic's skill standards and Connor's quality requirements.
+
+## 1. YAML Frontmatter Validation
+
+### Required Fields
+- [ ] `name` field present and valid
+  - Max 64 characters
+  - Lowercase, numbers, hyphens only
+  - No reserved words (skill, claude, anthropic)
+  - Matches directory name
+
+- [ ] `description` field present and valid
+  - Max 1024 characters
+  - Non-empty
+  - No XML/HTML tags
+  - Action-oriented (starts with verb)
+
+### Description Quality
+- [ ] Contains trigger phrase
+  - "Use PROACTIVELY when..." OR
+  - "Use when..." OR
+  - "Guides..." OR
+  - "Analyzes..." OR
+  - Similar action verb
+
+- [ ] Describes clear value/benefit
+  - What problem does it solve?
+  - What outcome does it produce?
+
+- [ ] Appropriate for skill category
+  - Aligns with insight category
+  - Matches skill type (tooling/analysis/productivity)
+
+### Optional Fields (if present)
+- [ ] `allowed-tools` (Claude Code only)
+  - Valid tool names only
+  - No duplicates
+
+- [ ] Custom fields are reasonable
+  - `version`, `author`, `category` are common
+
+## 2. File Structure Validation
+
+### Required Files
+- [ ] `SKILL.md` exists and is non-empty
+- [ ] `README.md` exists and is non-empty
+- [ ] `plugin.json` exists and is valid JSON
+- [ ] `CHANGELOG.md` exists with v0.1.0 entry
+
+### Optional Files (based on complexity)
+- [ ] `data/` directory if complexity >= standard
+- [ ] `data/insights-reference.md` if multiple insights
+- [ ] `examples/` directory if code examples present
+- [ ] `templates/` directory if actionable checklists exist
+
+### File Size Limits
+- [ ] SKILL.md < 500 lines (recommend splitting if larger)
+- [ ] No single file > 1000 lines
+- [ ] Total skill size < 1MB
+
+## 3. SKILL.md Content Quality
+
+### Structure
+- [ ] Clear heading hierarchy (h1 → h2 → h3)
+- [ ] No skipped heading levels
+- [ ] Consistent formatting throughout
+
+### Required Sections
+- [ ] Overview/Introduction
+  - What the skill does
+  - When to use it
+
+- [ ] Workflow or Phases
+  - Clear step-by-step instructions
+  - Numbered or bulleted steps
+  - Logical progression
+
+- [ ] Examples (if applicable)
+  - Concrete use cases
+  - Expected outputs
+
+### Content Quality
+- [ ] Clear, concise language
+- [ ] No ambiguous pronouns ("it", "this", "that" without context)
+- [ ] Consistent terminology (no mixing synonyms)
+- [ ] Action-oriented instructions (imperative mood)
+
+### Progressive Disclosure
+- [ ] SKILL.md serves as table of contents
+- [ ] Detailed content in separate files (data/, examples/)
+- [ ] References are one level deep (no nested references)
+
+## 4. Insight Integration Quality
+
+### Insight Attribution
+- [ ] Original insights preserved in `data/insights-reference.md`
+- [ ] Insights properly dated and sourced
+- [ ] Session metadata included
+
+### Content Transformation
+- [ ] Insights converted to actionable workflow steps
+- [ ] Problem-solution structure maintained
+- [ ] Code examples extracted to examples/
+- [ ] Best practices highlighted in Important Reminders
+
+### Deduplication
+- [ ] No duplicate content between skill files
+- [ ] Cross-references used instead of duplication
+- [ ] Consolidated similar points
+
+## 5. Pattern Adherence
+
+### Selected Pattern (phase-based/mode-based/validation)
+- [ ] Pattern choice justified by insight content
+- [ ] Pattern correctly implemented
+- [ ] Section structure matches pattern conventions
+
+### Workflow Logic
+- [ ] Phases/modes are sequential or parallel as appropriate
+- [ ] Each phase has clear purpose
+- [ ] Prerequisites stated upfront
+- [ ] Expected outputs defined
+
+### Error Handling
+- [ ] Common pitfalls documented
+- [ ] Troubleshooting guidance included
+- [ ] Failure recovery steps provided
+
+## 6. README.md Quality
+
+### Required Sections
+- [ ] Brief overview (1-2 sentences)
+- [ ] When to use (trigger phrases)
+- [ ] Quick start example
+- [ ] Installation instructions (if not standard)
+
+### Clarity
+- [ ] User-focused (not developer-focused)
+- [ ] Examples are copy-pasteable
+- [ ] Screenshots/diagrams if beneficial
+
+## 7. plugin.json Validation
+
+### JSON Validity
+- [ ] Valid JSON syntax
+- [ ] No trailing commas
+- [ ] Proper escaping
+
+### Required Fields
+- [ ] `name` matches SKILL.md frontmatter
+- [ ] `version` follows semver (0.1.0 for new skills)
+- [ ] `description` matches SKILL.md frontmatter
+- [ ] `type` is "skill"
+
+### Optional Fields (if present)
+- [ ] `author` is reasonable string
+- [ ] `category` is valid (tooling/analysis/productivity/devops)
+- [ ] `tags` are relevant keywords
+
+## 8. Code Quality (if skill includes examples)
+
+### Code Examples
+- [ ] Syntax highlighting specified (```language)
+- [ ] Code is complete and runnable
+- [ ] No placeholder variables (unless clearly marked)
+- [ ] Comments explain non-obvious logic
+
+### Best Practices
+- [ ] Follows language conventions
+- [ ] No security vulnerabilities
+- [ ] No hardcoded credentials
+- [ ] Error handling demonstrated
+
+## 9. Accessibility & Usability
+
+### Trigger Phrases
+- [ ] Multiple trigger phrases provided
+- [ ] Phrases are natural language
+- [ ] Covers different ways users might ask
+- [ ] PROACTIVELY triggers are specific (not too broad)
+
+### Searchability
+- [ ] Skill name reflects function
+- [ ] Description contains relevant keywords
+- [ ] Tags (if present) aid discovery
+
+### User Guidance
+- [ ] Clear next steps after each phase
+- [ ] Decision points clearly marked
+- [ ] Optional vs. required steps distinguished
+
+## 10. Edge Cases & Robustness
+
+### Input Handling
+- [ ] Handles missing/malformed input gracefully
+- [ ] Validates prerequisites before execution
+- [ ] Provides helpful error messages
+
+### Project Variability
+- [ ] Handles different project structures
+- [ ] Works with monorepos and single packages
+- [ ] Adapts to different tech stacks
+
+### Maintenance
+- [ ] No hardcoded paths (use relative or user-provided)
+- [ ] No assumptions about environment
+- [ ] Graceful degradation if optional tools unavailable
+
+## 11. Insight-Specific Validation
+
+### Quality Filter
+- [ ] Only high-quality insights converted
+  - Actionable (not just informational)
+  - Generally applicable (not project-specific)
+  - Valuable (solves real problem)
+
+### Relevance
+- [ ] Skill solves problem not covered by existing skills
+- [ ] No duplication with skill-creator, sub-agent-creator, etc.
+- [ ] Unique value proposition clear
+
+### Scope
+- [ ] Skill is focused (does one thing well)
+- [ ] Not too broad (overwhelming)
+- [ ] Not too narrow (trivial)
+
+## Scoring
+
+### Critical (must pass all)
+All items in sections 1-2 (Frontmatter, File Structure)
+
+### High Priority (must pass 90%+)
+Sections 3-5 (Content Quality, Insight Integration, Pattern Adherence)
+
+### Medium Priority (must pass 80%+)
+Sections 6-9 (README, plugin.json, Code Quality, Usability)
+
+### Optional (nice to have)
+Sections 10-11 (Edge Cases, Insight-Specific)
+
+## Auto-Fix Opportunities
+
+Some issues can be auto-corrected:
+- [ ] Trim description to 1024 chars
+- [ ] Convert skill name to lowercase kebab-case
+- [ ] Add missing CHANGELOG.md with v0.1.0
+- [ ] Generate basic README.md from SKILL.md overview
+- [ ] Validate and pretty-print JSON files
+
+## Manual Review Required
+
+Some issues require user decision:
+- Ambiguous trigger phrases
+- Pattern selection uncertainty
+- Multiple valid skill name options
+- Content organization choices
+- Category assignment conflicts