greyhaven-ai/claude-code-config

Overview

This skill implements a 6-phase verification system that ensures code matches its documentation by producing an automated alignment score. It identifies signature, type, behavior, error, and example mismatches and generates actionable fixes and a structured alignment report. The result is clearer documentation, fewer onboarding issues, and faster pre-release checks.

How this skill works

The system discovers code and documentation pairs, extracts signatures and examples, and performs automated analyses across six phases: discovery, extraction, analysis, classification, fix generation, and validation. It computes a weighted alignment score (signature 30%, type 25%, behavior 20%, error handling 15%, examples 10%) and classifies results into Perfect, Good, Poor, or Failing. Reports include identified mismatches, suggested fixes, and a verification checklist to guide remediation.

When to use it

• After code changes that might affect public APIs or examples
• During pre-release documentation verification and QA gates
• When onboarding new developers to reduce ramp-up friction
• When a user reports ‘docs out of sync’ or requests documentation verification
• As a periodic audit to detect documentation drift

Best practices

• Run the verification as part of CI for pull requests touching public interfaces
• Prioritize fixes by alignment score component (start with signature and type mismatches)
• Attach the generated alignment report to the related issue or PR for context
• Use the 101-point verification checklist to validate manual and edge-case scenarios
• Re-run validation after applying suggested fixes to ensure score improvement

Example use cases

• Detecting a changed function signature after a refactor and generating a doc update patch
• Verifying example snippets match actual behavior and error conditions before release
• Onboarding: running alignment checks on key libraries to highlight doc gaps for new hires
• Post-merge verification to ensure a hotfix didn’t introduce documentation drift
• Automated gating to block releases when alignment score falls into Poor or Failing ranges