Documentation Sync Skill

Keep the AILANG website in sync with actual implementation by checking design docs, validating examples, and tracking feature status.

Quick Start

# After a release - full sync check
# User: "sync docs for v0.5.6" or "run docs-sync"

# Check specific area
# User: "verify landing pages" or "check working examples"

When to Use This Skill

Invoke this skill when:

• After any release (post-release should trigger this)
• User questions website accuracy
• Features move from planned → implemented
• Examples may be broken or outdated
• Version constants need updating

Workflow

1. Pre-flight Checks

Run all diagnostic scripts to understand current state:

# Check design docs status
.claude/skills/docs-sync/scripts/audit_design_docs.sh

# Check version constants
.claude/skills/docs-sync/scripts/check_versions.sh

# Validate working examples
.claude/skills/docs-sync/scripts/check_examples.sh

2. Review Feature Themes

Features are grouped into themes (see resources/feature_themes.md):

3. Fix Priority Order

1. Version Constants - Update docs/src/constants/version.js
2. Landing Pages - intro.mdx, vision.mdx, why-ailang.mdx
3. Working Examples - Ensure examples use raw-loader, all pass
4. Status Banners - Add "PLANNED" banners to future features
5. Feature Docs - Create missing docs for implemented features
6. Roadmap Section - Move theoretical pages to roadmap

4. Update Checklist

After fixing, verify:

# Rebuild and check
cd docs && npm run build

# Verify no broken links
npm run serve  # Manual check

# Commit changes
git add docs/
git commit -m "docs: sync website with v0.X.X implementation"

Scripts

CLI Example Verification (External)

The Makefile provides CLI example verification that complements this skill:

# Verify all CLI examples documented in examples/cli_examples.txt
make verify-cli-examples

# Full verification: code examples + CLI examples
make verify-examples && make verify-cli-examples

CLI Examples File Format (examples/cli_examples.txt):

# Comment explaining the example
$ ailang run --caps IO --entry main examples/runnable/hello.ail
Hello, AILANG!

This ensures CLI syntax in documentation matches actual behavior.

Version Derivation Script

# List all planned features with derived target versions
.claude/skills/docs-sync/scripts/derive_roadmap_versions.sh

# Full lifecycle: planned + implemented features
.claude/skills/docs-sync/scripts/derive_roadmap_versions.sh --full

# Check website consistency (exits 1 if mismatches)
.claude/skills/docs-sync/scripts/derive_roadmap_versions.sh --check

# JSON output for automation
.claude/skills/docs-sync/scripts/derive_roadmap_versions.sh --json --full

# Full validation: all features + website check
.claude/skills/docs-sync/scripts/derive_roadmap_versions.sh --full --check

Resources

Integration with Post-Release

The post-release skill should invoke docs-sync automatically:

# In post-release workflow after eval baselines
# Run docs-sync to update website

Key Principles

1. Theoretical is OK - Future features can be documented, but must:
   • Link to design docs on GitHub
   • Have clear status banner (e.g., "PLANNED FOR v0.6.0")
   • Be in roadmap section, not current features

2. Examples Must Work - Every code example should:

   • Use raw-loader to import from examples/
   • Be tested with ailang run or ailang test
   • Never embed code directly in MDX
   • CLI commands must be added to examples/cli_examples.txt and verified with ./tools/verify_cli_examples.sh
   • Default entrypoint is main - don't use --entry main unless showing non-main entry
   • Test all commands before documenting: ./bin/ailang run --caps IO examples/runnable/hello.ail

   Exception for Reference Documentation:

   • Reference pages (e.g., language-syntax.md, effects.md) may use inline syntax snippets
   • These are small patterns showing language constructs, not complete runnable programs
   • Tutorial pages (examples.mdx, getting-started.mdx, guides/) must always import from files
   • Rule: If the code snippet is a complete runnable program, it MUST be imported

3. Design Docs = Ultimate Source of Truth - The folder structure tracks complete feature lifecycle:

   Planned features:

   • design_docs/planned/v0_6_0/foo.md → Feature targets v0.6.0
   • Website pages must match: PLANNED FOR v0.6.0 banner
   • Website MUST link to design doc on GitHub as ultimate reference
   • OVERDUE = design doc folder version ≤ current release but not implemented

   Implemented features:

   • design_docs/implemented/v0_5_6/foo.md → Feature shipped in v0.5.6
   • Website reference pages can link to implemented design docs
   • Moving planned/ → implemented/ = feature is done

   Validation:

   • Run ./scripts/derive_roadmap_versions.sh --check to validate website
   • Run ./scripts/derive_roadmap_versions.sh --full to see complete lifecycle
   • Script checks for GitHub links in roadmap pages
4. One Source of Truth - Version comes from:
   • git describe --tags → actual version
   • prompts/versions.json → latest syntax prompt (ailang prompt)
   • prompts/devtools/versions.json → latest dev tools prompt (ailang devtools-prompt)
   • These feed into docs/src/constants/version.js
   • Website should reference both prompts and explain when to use each
5. Themes Over Changelog - Group features by theme, not by version. Users care about "how do effects work?" not "what changed in v0.5.3?"
6. Evolving Themes - Themes should evolve as the language grows:
   • When a feature doesn't fit existing themes, consider a new theme
   • New themes warrant new landing pages
   • Update resources/feature_themes.md when adding themes
   • Current themes: Core Language, Type System, Effect System, Module System, Go Codegen, Arrays, Testing, AI Integration, Developer Experience
   • Roadmap themes: Execution Profiles, Deterministic Tooling, Shared Semantic State

Theme Evolution Guidelines

When reviewing new features, ask:

1. Does this fit an existing theme? → Add to that theme's page
2. Is this a major new capability? → Consider a new theme
3. Is this cross-cutting? → May need multiple mentions but one authoritative page

Signals for a New Theme

• 3+ related features with no natural home
• A new design doc folder (e.g., v0_7_0/) with a coherent focus
• User questions consistently asking "how do I do X?" where X isn't covered
• A planned feature graduating to implemented that's substantial

Creating a New Theme

1. Add entry to resources/feature_themes.md
2. Create website page at appropriate location
3. Update sidebar in docs/sidebars.js
4. Cross-link from related themes
5. Update this skill's theme table above