lindoelio/spec-driven-steroids/quality-grading

Quality Grading Skill

Evaluate and improve code, specifications, or design documents across four quality dimensions with calibrated scoring and auto-fix capabilities.

Overview

This skill provides a multi-dimensional quality grading system for any artifact type:

• Code: Implementation files, modules, functions
• Specifications: Requirements documents, README, acceptance criteria
• Designs: Architecture documents, system designs, technical specifications

It supports two invocation modes:

• evaluate: Score the artifact and return structured JSON results
• grade-and-fix: Score the artifact, then auto-fix dimensions scoring below 5, re-grade, and provide final results

The skill targets score 5+ as the quality bar. Auto-fix attempts are limited to 3 per dimension to keep improvements pragmatic and avoid unnecessary complexity.

Invocation

Load this skill when:

• You want quality feedback on code or implementation
• You want quality feedback on design or architecture documents
• You want quality feedback on specifications or requirements
• You want to improve artifacts scoring below 5 automatically
• You need consistent, calibrated quality assessments

Input

• artifact: Path to the file, directory, or snippet to grade (required)
• mode: evaluate or grade-and-fix (default: evaluate)

Process

1. Load artifact: Read the target file, all files in the directory, or parse the snippet
2. Detect artifact type: Determine if this is code, a specification, or a design document
3. Apply dimension rubrics: Score each of the four dimensions independently, adapting criteria to artifact type
4. Use calibration examples: Compare against few-shot examples for consistency
5. If grade-and-fix mode and score < 5: Apply targeted auto-fix, re-grade, repeat up to 3 times
6. Generate JSON output: Return structured results with scores, justifications, and suggestions

Grading Dimensions

1. Design Quality

Measures: Architecture clarity, scalability, and separation of concerns

For Code: Module structure, dependency management, separation of concerns For Designs: Architecture clarity, module boundaries, scalability patterns, diagram quality For Specifications: Logical organization, traceability, clarity of structure

What to look for:

• Clear module boundaries and logical file organization
• Proven scalability patterns appropriate to the problem
• Strong separation of concerns (no intermingled responsibilities)
• Clean dependency flow

Scoring Rubric:

Auto-Fix (score < 5):

• Add missing module boundaries or clear separation between concerns
• Consolidate tangled dependencies into logical modules
• Simplify overly complex architectural patterns

2. Originality

Measures: Avoidance of generic boilerplate and tailoring to the problem

For Code: Problem-specific solutions vs copy-paste patterns For Designs: Domain-specific architecture vs generic templates For Specifications: Tailored requirements vs boilerplate language

What to look for:

• Problem-specific terminology and approach
• Contextual examples that map to the domain
• Removal of irrelevant template content
• Novel solutions rather than copy-paste patterns

Scoring Rubric:

Auto-Fix (score < 5):

• Replace generic boilerplate with problem-specific terminology
• Add context-specific examples or patterns
• Remove irrelevant template content

3. Craft

Measures: Code cleanliness, error handling, and documentation

For Code: Clean code, error handling, comments, documentation For Designs: Diagram clarity, consistent formatting, completeness For Specifications: Clear writing, consistent terminology, proper structure

What to look for:

• Clean, consistent formatting and naming
• Comprehensive error handling for edge cases
• Clear documentation (doc comments, README, inline explanations)
• No obvious bugs or security issues

Scoring Rubric:

Auto-Fix (score < 5):

• Add missing error handling for edge cases
• Clean up inconsistent formatting or naming
• Add doc comments to undocumented functions

4. Functionality

Measures: Feature completeness and edge case handling

For Code: Features work, edge cases handled For Designs: All requirements covered, feasibility, completeness For Specifications: Complete requirements, clear acceptance criteria, no gaps

What to look for:

• All specified features are implemented
• Edge cases are identified and handled
• Requirements or acceptance criteria are covered
• No broken references or incomplete specifications

Scoring Rubric:

Auto-Fix (score < 5):

• Add missing functionality or requirements coverage
• Address identified edge cases in the implementation
• Fix broken references or incomplete specifications

Self-Healing Behavior

When invoked in grade-and-fix mode:

1. Trigger: Auto-fix activates for any dimension scoring below 5
2. Fix Strategy: Apply minimal, targeted changes that address the specific gap without introducing unnecessary complexity
3. Re-grade: After each fix, re-score to verify improvement
4. Attempts: Maximum 2 auto-fix attempts per dimension
5. Fallback: If auto-fix fails to achieve score 5+, record actionable suggestions instead of blocking
6. Principle: Prioritize pragmatic simplicity over exhaustive perfection

Few-Shot Calibration

Use the examples in references/ directories to calibrate your scoring:

• design-quality/: Examples of architecture quality at each score level
• originality/: Examples of boilerplate vs tailored solutions
• craft/: Examples of code cleanliness and documentation quality
• functionality/: Examples of feature completeness

Compare the artifact you're grading against these examples for consistent calibration.

Output Format

The skill produces JSON output:

{
  "artifact": "<path-to-graded-file>",
  "artifactType": "code | specification | design",
  "timestamp": "<ISO-8601 timestamp>",
  "mode": "evaluate | grade-and-fix",
  "dimensions": {
    "designQuality": {
      "score": 1-5,
      "justification": "<brief explanation of the score>",
      "improved": "<null | description of auto-fix applied>"
    },
    "originality": {
      "score": 1-5,
      "justification": "<brief explanation of the score>",
      "improved": "<null | description of auto-fix applied>"
    },
    "craft": {
      "score": 1-5,
      "justification": "<brief explanation of the score>",
      "improved": "<null | description of auto-fix applied>"
    },
    "functionality": {
      "score": 1-5,
      "justification": "<brief explanation of the score>",
      "improved": "<null | description of auto-fix applied>"
    }
  },
  "overallScore": "<average of dimensions, displayed as X.Y>",
  "summary": "<overall assessment text>",
  "suggestions": {
    "<dimension>": "<actionable improvement if score < 5 and auto-fix failed>"
  }
}

Glossary

Examples

Example: Evaluate Code Quality

User: Grade this implementation using quality-grading skill
Artifact: src/services/auth.ts
Mode: evaluate

Example: Grade Design Document

User: Assess the quality of this architecture design
Artifact: docs/architecture/system-design.md
Mode: grade-and-fix

Example: Evaluate Specification

User: Grade this requirements document
Artifact: .specs/changes/feature/requirements.md
Mode: evaluate

Example: Grade and Fix

User: Grade and improve this module
Artifact: src/utils/
Mode: grade-and-fix