Skip to content

Conversation

@jmagly
Copy link

@jmagly jmagly commented Dec 11, 2025

Summary

This PR adds completeness checks to quality_checker.py, addressing G2.3 and G2.4 from the roadmap.

What's Included

New _check_skill_completeness() method that validates:

  1. Prerequisites/Verification Sections

    • Patterns: prerequisites, requirements, before you start, verify that
    • Helps Claude check conditions before proceeding
  2. Error Handling/Troubleshooting Guidance

    • Patterns: troubleshooting, common issues, if ... fails
    • Helps users recover from errors
  3. Workflow Steps

    • Patterns: step 1, first, then, next, finally
    • Clear sequential guidance improves Claude's execution

Design Decisions

  • Info-level messages only: These checks produce info messages, not warnings/errors
  • This avoids penalizing existing skills while still providing helpful guidance
  • Maintainers can later decide if any should become warnings

Roadmap Alignment

  • G2.3: Add readability scoring → Workflow step detection addresses this
  • G2.4: Add completeness checker ✅

Tests Included

4 new unit tests in TestCompletenessChecks:

  • test_checker_detects_prerequisites_section
  • test_checker_detects_troubleshooting_section
  • test_checker_detects_workflow_steps
  • test_checker_suggests_adding_prerequisites

Example Output (verbose mode)

ℹ️  INFO (completeness):
   ✓ Found verification/prerequisites section (SKILL.md)
   ✓ Found error handling/troubleshooting guidance (SKILL.md)
   ✓ Found clear workflow indicators (4 step markers) (SKILL.md)

Code Style

Follows existing patterns:

  • Same _check_* method naming convention
  • Same regex-based pattern matching approach
  • Same report.add_info() call pattern
  • 100 char lines, type hints, Google-style docstrings

This PR builds on the Best Practices Guide (#206) - the patterns checked here match what that guide recommends.

Contributed by the AI Writing Guide project.

Add _check_skill_completeness() method to quality checker that validates:
- Prerequisites/verification sections (helps Claude check conditions first)
- Error handling/troubleshooting guidance (common issues and solutions)
- Workflow steps (sequential instructions using first/then/next/finally)

This addresses G2.3 and G2.4 from the roadmap:
- G2.3: Add readability scoring (via workflow step detection)
- G2.4: Add completeness checker

New checks use info-level messages (not warnings) to avoid affecting
quality scores for existing skills while still providing helpful guidance.

Includes 4 new unit tests for completeness checks.

Contributed by the AI Writing Guide project.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant