sync-docs

name	sync-docs
description	Use when synchronizing codebase documentation after code changes. Triggers on "sync docs", "update documentation", "regenerate docs", or after significant implementation work.

Sync Documentation

Analyze codebase and generate structured documentation to docs/.

Output Documents

Document	Purpose	Audience
docs/stack.md	Technology stack, dependencies, build system	Humans
docs/architecture.md	System structure, data flow, modules	Humans
docs/concerns.md	Tech debt, known issues, fragile areas	Humans
docs/structure.md	Where to add new code	Claude
docs/conventions.md	Coding patterns and style rules	Claude

Why This Matters

These documents are consumed by:

• Humans read stack.md, architecture.md, concerns.md for orientation
• Claude instances reference structure.md and conventions.md when writing code
• Feature planning loads architecture.md and structure.md for context

What this means for output:

1. File paths are critical - src/render/shader_setup.cpp not "the shader setup code"
2. Patterns matter more than lists - Show HOW with code examples, not just WHAT exists
3. Be prescriptive - "Use PascalCase for functions" not "PascalCase is sometimes used"
4. CONCERNS.md drives priorities - Issues identified may become future work

Philosophy

Document quality over brevity: Include enough detail to be useful as reference.

Always include file paths: Every finding needs a file path in backticks. No exceptions.

Write current state only: Describe what IS, never what WAS. No temporal language.

Be prescriptive, not descriptive: "Use X pattern" is more useful than "X pattern is used."

---

Git-Based Change Detection

Each document header contains:

> Last sync: YYYY-MM-DD | Commit: <short-sha>

Before syncing:

1. Read docs/stack.md and extract lastSyncCommit SHA from header
2. Run git diff <lastSyncCommit>..HEAD --name-only to list changed files
3. Map changed files to document types using table below
4. Only regenerate documents with relevant changes

If no lastSyncCommit exists: First run - generate all 5 documents.

Change-to-Document Mapping

Changed Files	Documents to Update
CMakeLists.txt, vcpkg.json, *.cmake	stack.md
src/*/ new directories	architecture.md, structure.md
src/**/*.h (interface changes)	architecture.md, structure.md, conventions.md
src/**/*.cpp content	concerns.md (rescan TODOs)
shaders/*	structure.md
CLAUDE.md	conventions.md

After syncing: Update header in each regenerated doc:

git rev-parse --short HEAD  # Get current SHA

---

Process

Phase 1: Detect Changes

1. Check if docs/stack.md exists (first-run vs incremental)
2. If incremental:
   • Extract lastSyncCommit from header: grep "Commit:" docs/stack.md
   • Run git diff <lastSyncCommit>..HEAD --name-only
   • Map changed files to documents using table above
3. Report which documents will be generated vs skipped

First run: Generate all 5 documents.

Phase 2: Generate Documents

Spawn agents with run_in_background: true for each document type needed.

Agent prompt format:

Generate docs/<name>.md for this codebase.

Template: Read .claude/skills/sync-docs/templates/<name>.md
Output: Write to docs/<name>.md

[Include relevant exploration commands from below]

Fill template with findings. Use "Not detected" for missing items.
Always include file paths in backticks.

Return only confirmation: document path and line count.

Phase 3: Finalize

1. Wait for agents with TaskOutput
2. Verify documents exist
3. Report summary

---

Exploration Commands by Document Type

stack (tech focus)

# Build system
cat CMakeLists.txt 2>/dev/null | head -100
cat vcpkg.json 2>/dev/null

# Config files
ls -la *.cmake .clang-* 2>/dev/null

# Compiler/standard detection
grep -i "CMAKE_CXX_STANDARD\|set(CMAKE" CMakeLists.txt 2>/dev/null

architecture (arch focus)

# Directory structure
find . -type d -not -path '*/.git/*' -not -path '*/build/*' | head -50

# Entry points
ls src/main.* src/*/main.* 2>/dev/null

# Module discovery
ls -d src/*/ 2>/dev/null

# Header analysis for interfaces
find src/ -name "*.h" | head -20

structure (arch focus)

# File counts per directory
find src/ -type f \( -name "*.cpp" -o -name "*.h" \) | head -100

# Shader file counts by type
find shaders/ -name "*.fs" 2>/dev/null | wc -l
find shaders/ -name "*.glsl" 2>/dev/null | wc -l

# Config patterns
find src/ -name "*_config.h" 2>/dev/null

# Codebase size — run cloc, use exact numbers, NEVER estimate or round
cloc src/ shaders/ --force-lang="GLSL,fs" 2>/dev/null

Important: For src/effects/ and shaders/, report file count + category names only. Do NOT enumerate individual file names or "key files" — the naming conventions make paths derivable. For smaller directories, key files are appropriate.

conventions (quality focus)

# Sample source files for pattern analysis
ls src/*.cpp src/*/*.cpp 2>/dev/null | head -10

# Read CLAUDE.md for authoritative rules
cat CLAUDE.md 2>/dev/null

# Formatting config
ls .clang-format .editorconfig 2>/dev/null

concerns (concerns focus)

# TODO/FIXME comments
grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.cpp" --include="*.h" 2>/dev/null | head -50

# Large files (line count hotspots)
find src/ -name "*.cpp" -exec wc -l {} \; 2>/dev/null | sort -rn | head -10

# Complexity hotspots (CCN > 15, sorted by complexity, top 10)
lizard src/ -l cpp -w -s cyclomatic_complexity 2>/dev/null | head -10

# Incomplete implementations
grep -rn "// TODO\|NotImplemented\|assert(false)" src/ --include="*.cpp" 2>/dev/null | head -30

---

Critical Rules

WRITE DOCUMENTS DIRECTLY. Agents write to docs/, not return content.

ALWAYS INCLUDE FILE PATHS. Every finding needs a path in backticks.

USE THE TEMPLATES. Fill the template structure from .claude/skills/sync-docs/templates/.

BE THOROUGH. Explore deeply. Read actual files. Don't guess.

PRESERVE EXISTING CONTENT. Read the existing doc first. Only update sections with actual changes. Don't rephrase working content.

RETURN ONLY CONFIRMATION. Agent responses should be ~10 lines max.

---

Success Criteria

• All requested documents written to docs/
• Documents follow template structure
• File paths included throughout
• Agents completed without errors