Doc-Sync: Self-Documenting Architecture

This Skill enforces a strict documentation synchronization pattern where code changes automatically update all related documentation.

Core Principle

Documentation = Code: Any functional, architectural, or implementation change MUST update its corresponding documentation immediately after work completes.

Three-Level Documentation Structure

Level 1: Root Documentation (README.md)

Every project root MUST have a README.md that states:

markdown
1# Project Documentation Sync Contract
2
3**CRITICAL**: Any feature, architecture, or implementation update MUST update:
41. This root README.md (high-level changes)
52. The relevant folder's folder.md (structure changes)
63. All affected files' header annotations (implementation changes)
7
8After completing ANY work, update documentation BEFORE committing.

Level 2: Folder Documentation (folder.md)

Every folder MUST contain a folder.md file with:

markdown
1# Folder Architecture
2
3## Overview (max 3 lines)
4[Brief description of this folder's purpose and scope]
5
6## Files
7
8| File | Role | Function |
9|------|------|----------|
10| filename.ext | [role: controller/service/model/util] | [what it does] |
11| filename2.ext | [role] | [what it does] |
12
13---
14**SYNC ALERT**: If this folder changes (files added/removed/renamed), UPDATE THIS FILE.

Example:

markdown
1# src/auth Module
2
3## Overview
4Authentication and authorization layer handling JWT validation, session management, and role-based access control.
5
6## Files
7
8| File | Role | Function |
9|------|------|----------|
10| index.ts | Controller | HTTP routing, request validation |
11| service.ts | Service | Business logic, token generation |
12| model.ts | Model | TypeBox schemas, DTOs |
13| middleware.ts | Middleware | Request interception, guards |
14
15---
16SYNC ALERT: If this folder changes, UPDATE THIS FILE.

Level 3: File Header Annotations

Every source file MUST start with:

typescript
1/**
2 * INPUT: [external dependencies: imports, env vars, services]
3 * OUTPUT: [what this exports/provides: functions, types, values]
4 * POSITION: [local role in system architecture: controller/service/model/util]
5 *
6 * SYNC: If this file changes, UPDATE this header AND the parent folder.md
7 */

Examples:

Controller (index.ts):

typescript
1/**
2 * INPUT: Request (Express/Elysia), body validation schemas
3 * OUTPUT: HTTP responses, status codes, error handlers
4 * POSITION: Entry point - handles HTTP layer only
5 *
6 * SYNC: Update this header and ../folder.md on changes
7 */
8import { service } from './service'
9
10export const handler = (req: Request) => service.process(req)

Service (service.ts):

typescript
1/**
2 * INPUT: Validated request data, database client, external APIs
3 * OUTPUT: Business logic results, domain entities
4 * POSITION: Core logic - decoupled from HTTP, pure business rules
5 *
6 * SYNC: Update this header and ../folder.md on changes
7 */
8export const process = (data: Data) => { /* ... */ }

Model (model.ts):

typescript
1/**
2 * INPUT: TypeBox/T, Zod, or validation library
3 * OUTPUT: Validation schemas, TypeScript types, DTOs
4 * POSITION: Data contract - defines interface between layers
5 *
6 * SYNC: Update this header and ../folder.md on changes
7 */
8import { t } from 'elysia'
9
10export const UserSchema = t.Object({ /* ... */ })

Workflow

When creating or modifying code:

1. Before coding: Read existing folder.md to understand context
2. During coding: Focus on implementation
3. After coding (MANDATORY):
   • Update file header (INPUT/OUTPUT/POSITION)
   • Update folder.md if structure changed
   • Update README.md if architecture changed
   • Commit ONLY after all docs updated

Commands

Create new file with template:

bash
1# Creates file with doc-sync header
2cat > src/newFile.ts << 'EOF'
3/**
4 * INPUT: [TODO]
5 * OUTPUT: [TODO]
6 * POSITION: [TODO]
7 *
8 * SYNC: Update this header and ../folder.md on changes
9 */
10EOF

Check documentation coverage:

bash
1# Find folders missing folder.md
2find . -type d -not -path "*/node_modules/*" -not -path "*/.git/*" | while read dir; do
3  if [ ! -f "$dir/folder.md" ]; then
4    echo "Missing: $dir/folder.md"
5  fi
6done
7
8# Find files missing header annotations
9grep -rL "INPUT:" src/ || echo "All files have headers"

Validation Checklist

Before committing, verify:

• Root README.md updated (for architectural changes)
• Every affected folder has folder.md
• Every folder.md lists all files with roles
• Every file has INPUT/OUTPUT/POSITION header
• SYNC reminders present in all folder.md and file headers
• No "TODO" in INPUT/OUTPUT/POSITION fields

Examples

See examples/ for complete project structures:

• basic-auth/ - Simple auth module with full doc-sync
• ecommerce/ - Multi-module project
• api-service/ - Layered architecture

Best Practices

• Update immediately: Don't batch doc updates
• Be specific: INPUT should list actual imports, not "various"
• Keep POSITION brief: One line describing architectural role
• Folder overview max 3 lines: Keep it scannable
• Use tables: folder.md files section MUST use markdown table
• No exceptions: Even test files need headers

Anti-Patterns

❌ Don't:

• Leave "TODO" in headers
• Update docs in separate PR
• Skip folder.md for "simple" folders
• Copy-paste headers without updating INPUT/OUTPUT
• Write POSITION as "utility file" (be specific: "validation utility for user input")

✅ Do:

• Update docs as part of the same commit
• Run validation checklist before push
• Treat docs as code, not comments
• Review folder.md changes in code review

Advanced: Nested Folder Sync

For deep hierarchies, each level updates its parent:

src/
├── folder.md (mentions modules/ as subdirectory)
└── modules/
    ├── folder.md (lists auth/, user/ subdirs)
    └── auth/
        ├── folder.md (lists index.ts, service.ts, model.ts)
        └── index.ts (has INPUT/OUTPUT/POSITION)

When auth/index.ts changes:

1. Update its header
2. Update auth/folder.md
3. Update modules/folder.md
4. Update src/folder.md (if role changed)