wahidyankf Validating Software Engineering Documentation Separation
This Skill provides comprehensive guidance for validating the separation between repository-specific style guides (docs/explanation/software-engineering/) and educational content (apps/ayokoding-www/), as defined in the Programming Language Documentation Separation Convention.
Purpose
Use this Skill when:
- Implementing style guide separation validation in checker agents
- Validating docs/explanation content doesn't duplicate AyoKoding educational content
- Ensuring prerequisite knowledge statements exist and are correct
- Checking style guides focus on repository-specific conventions only
- Understanding content separation patterns
Validation Scope
Lifecycle Delegation
For a quality-gate handoff, accept exact delegated-gate-ids and lifecycle-evidence. When
md-links is delegated, do not resolve, re-check, fix, or AI-rederive paths/fragments; retain the
semantic correctness of prerequisite relationships and all separation checks. Checkers preserve
the ledger; fixers return a scope-intersected updated-lifecycle-evidence. Omitted delegation
preserves standalone full behaviour.
CRITICAL: Only validate relationships explicitly listed in the Software Design Reference prerequisite table.
Authoritative Source: Software Design Reference - Specific Prerequisites
Current explicit relationships to validate:
- docs/explanation/programming-languages/java/ ↔ ayokoding-web/.../java/
- docs/explanation/programming-languages/golang/ ↔ ayokoding-web/.../golang/
- docs/explanation/programming-languages/elixir/ ↔ ayokoding-web/.../elixir/
- docs/explanation/platform-web/tools/jvm-spring/ ↔ ayokoding-web/.../jvm-spring/
- docs/explanation/platform-web/tools/jvm-spring-boot/ ↔ ayokoding-web/.../jvm-spring-boot/
DO NOT validate languages/frameworks not in this table (TypeScript, Python, etc.) until they are explicitly added to the Software Design Reference.
Core Validation Principle
CRITICAL: docs/explanation/ content MUST NOT duplicate AyoKoding educational content.
Separation Pattern:
- AyoKoding = Educational (language syntax, by-example tutorials, generic patterns)
- docs/explanation/ = Style guides (OSE Platform naming, framework choices, repository patterns)
See Programming Language Documentation Separation Convention for complete rules.
What to Validate
See What to Validate and Validation Workflow for the five validation checks (prerequisite mapping, prerequisite statements, content duplication, AyoKoding completeness, cross-reference links) and the three-step validation workflow.
Common Separation Violations
See Common Separation Violations for worked FAIL/PASS examples of duplicated educational content and missing prerequisite statements.
Criticality Levels
CRITICAL:
- Prerequisite mapping missing from Software Design Reference table
- Prerequisite statement missing in docs/explanation README
- Content duplication detected (educational content in style guides)
HIGH:
- Wrong AyoKoding path in prerequisite statement
- Style guide content lacks OSE Platform context
- Required AyoKoding content missing
MEDIUM:
- Prerequisite statement poorly formatted
- Cross-reference links suboptimal
LOW:
- Enhanced prerequisite explanations
- Additional cross-references
Fixing Violations
Guidance for docs-software-engineering-separation-fixer: see
Fixing Separation Violations — Confidence and What to Fix
and Fixing Separation Violations — Workflow and Patterns.
Related Conventions
Primary: Programming Language Documentation Separation Convention
Supporting:
Related Skills
- repo-assessing-criticality-confidence
- repo-applying-maker-checker-fixer
- repo-generating-validation-reports
- apps-ayokoding-www-developing-content
Related Agents
- docs-software-engineering-separation-checker - Validates explicit relationships
- docs-software-engineering-separation-fixer - Fixes violations
- docs-maker - Creates style guide content
- apps-ayokoding-www-general-maker - Creates educational content