semantic-validation
Scannednpx machina-cli add skill akaszubski/autonomous-dev/semantic-validation --openclawSemantic Validation Skill
Purpose: Use GenAI to validate that documentation accurately reflects implementation, catching issues that structural validation misses.
When This Skill Activates
- Keywords:
Core Concepts
Overview
This skill provides comprehensive guidance on semantic validation. For detailed patterns and implementation examples, see the documentation files in docs/.
Key Topics:
- Detailed methodologies and best practices
- Implementation patterns and examples
- Common pitfalls and anti-patterns
- Cross-references to related skills
See: Documentation files in docs/ directory for complete details
Quick Reference
| Topic | Details |
|---|---|
| Detailed Guide 1 | docs/detailed-guide-1.md |
| Detailed Guide 2 | docs/detailed-guide-2.md |
| Detailed Guide 3 | docs/detailed-guide-3.md |
Progressive Disclosure
This skill uses progressive disclosure to prevent context bloat:
- Index (this file): High-level concepts and quick reference (<500 lines)
- Detailed docs:
docs/*.mdfiles with implementation details (loaded on-demand)
Available Documentation:
docs/detailed-guide-1.md- Detailed implementation guidedocs/detailed-guide-2.md- Detailed implementation guidedocs/detailed-guide-3.md- Detailed implementation guide
Cross-References
Related Skills:
- See PROJECT.md for complete skill dependencies
Related Tools:
- See documentation files for tool-specific guidance
Key Takeaways
- Research existing patterns before implementing
- Follow established best practices
- Refer to detailed documentation for implementation specifics
- Cross-reference related skills for comprehensive understanding
Source
git clone https://github.com/akaszubski/autonomous-dev/blob/master/plugins/autonomous-dev/skills/archived/semantic-validation/SKILL.mdView on GitHub Overview
This skill uses GenAI to ensure documentation reflects the implemented system, catching outdated docs, version mismatches, and architectural drift that slip past structural checks. It helps maintain reliable, up-to-date guidance for developers and users alike.
How This Skill Works
The skill analyzes documentation in the repository using GenAI, comparing it against current code, APIs, and architectural references. It flags inconsistencies such as outdated statements, version mismatches, and architectural drift, then surfaces actionable updates. It relies on repository tooling (Read, Grep, Glob) to gather doc sources from the docs/ directory for evaluation.
When to Use It
- After API or component changes that affect user-facing docs
- When docs reference a different version than the code implements
- During architectural refactors to detect drift
- Ahead of release or launch to ensure docs align with implementation
- During periodic audits to catch stale documentation
Quick Start
- Step 1: Run semantic-validation against the repo
- Step 2: Review flagged items and map to doc changes
- Step 3: Update docs and re-run until clean
Best Practices
- Run semantic validation after merges that touch docs or APIs
- Prioritize validating docs in the docs/ directory
- Flag and fix version mismatches and architectural drift promptly
- Incorporate findings into a docs update checklist
- Integrate with CI to trap drift early
Example Use Cases
- Detect outdated API docs after a new endpoint is added
- Catch mismatch between deployed version and docs
- Identify architectural drift when refactoring microservices
- Audit onboarding docs to reflect current implementation
- Spot deprecated references before release
