semantic-git

semantic-git

Generate *.semantic.md documentation that serves as an alternative to reading source code. Someone unfamiliar with the repo should understand the system's purpose, architecture, data flow, and key decisions just from these files.

Output Location — Colocated with Code

Documentation files live next to the code they describe, not in a separate directory. This makes them discoverable in the IDE file tree — you see the explanation right next to the source.

Naming Convention

Scope	File name	Example
Whole repo overview	OVERVIEW.semantic.md at repo root	OVERVIEW.semantic.md
Whole repo architecture	ARCHITECTURE.semantic.md at repo root	ARCHITECTURE.semantic.md
A directory/module	.semantic.md inside that directory	src/lib/offline/.semantic.md
A specific file	<filename>.semantic.md next to that file	src/lib/notes.semantic.md next to notes.ts

Placement Rules

1. If a doc explains a directory (a group of files working together), place .semantic.md inside that directory. This appears at the top of the file tree for that folder.
2. If a doc explains a single file, place <filename>.semantic.md next to it. This sorts adjacent to the source file in the IDE (e.g., notes.semantic.md appears right next to notes.ts).
3. Repo-wide docs (OVERVIEW.semantic.md, ARCHITECTURE.semantic.md) go at the repo root.
4. The manifest (.semantic-manifest.json) goes at the repo root. It tracks all generated doc locations.

Example Layout

OVERVIEW.semantic.md                           # Repo entry point
ARCHITECTURE.semantic.md                       # System architecture
.semantic-manifest.json                        # Tracks all docs
apps/
├── web/src/lib/
│   ├── notes.ts
│   ├── notes.semantic.md                      # Explains notes.ts specifically
│   ├── sentence-generation.ts
│   ├── sentence-generation.semantic.md        # Explains sentence-generation.ts
│   ├── review.ts
│   ├── review.semantic.md                     # Explains review.ts
│   └── offline/
│       ├── idb.ts
│       ├── sync.ts
│       └── .semantic.md                       # Explains the offline module
└── extension/src/
    └── .semantic.md                           # Explains the extension module

These files are committed to the repo (not gitignored) so they render on GitHub and version alongside code.

How to Decide What Gets Documented

Scan the repo and identify logical boundaries. A "module" is a directory or group of files serving a cohesive purpose. Signs: shared imports, a clear public API, an index/barrel file, a distinct subdirectory.

Apply these rules:

Situation	Action
Directory with 1-3 small files	Mention in parent directory's .semantic.md
Directory with 4-15 files or >500 total lines	Gets a .semantic.md inside that directory
Directory with >15 files or >2000 lines	Directory .semantic.md + individual <file>.semantic.md for complex files
Single complex file (>300 lines, non-trivial logic)	Gets its own <filename>.semantic.md next to it
Config/build files	Document in OVERVIEW.semantic.md unless unusually complex
Test directories	Document what is tested and testing approach, not individual test files

Complexity overrides size. A 50-line file implementing a non-obvious algorithm deserves more explanation than a 500-line file of repetitive CRUD handlers.

For detailed guidance, read references/granularity.md.

What NOT to Document

Never generate *.semantic.md files for:

Gitignored files and directories

Before documenting anything, check the repo's .gitignore (and any nested .gitignore files). If a file or directory is gitignored, do not create a semantic doc for it. Common gitignored paths include node_modules/, dist/, build/, .env, __pycache__/, .next/, coverage/, etc.

Utility and config files

These files are self-explanatory or too generic to warrant their own semantic doc:

• Package manifests: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock, go.sum, Gemfile.lock, requirements.txt, poetry.lock
• Dotfiles and config: .gitignore, .gitattributes, .editorconfig, .prettierrc, .eslintrc, tsconfig.json, jest.config.*, vite.config.*, next.config.*, webpack.config.*, babel.config.*, .env.example
• Manifests and metadata: manifest.json (browser extensions), Dockerfile, docker-compose.yml, .github/, .gitlab-ci.yml
• Lock files and generated files: anything auto-generated by tooling
• License and legal: LICENSE, LICENSE.md

These files should be mentioned in OVERVIEW.semantic.md or a parent .semantic.md where relevant (e.g., "the project uses TypeScript — see tsconfig.json"), but they do not get their own <filename>.semantic.md.

The semantic docs themselves

Never create *.semantic.semantic.md or document .semantic-manifest.json.

Document Content Format

Each *.semantic.md file follows this structure. For full templates, read references/output-format.md.

Every generated file starts with this header:

<!-- Generated by semantic-git. Do not edit manually -- regenerate with /semantic-git -->

Required Sections

1. Title and one-paragraph summary — what this module/system does in plain English
2. Why it exists — the problem it solves or role it plays
3. How it works — step-by-step explanation of the main flow using numbered lists
4. Key concepts — define domain terms or abstractions the code introduces
5. Diagram — mermaid for anything with >3 nodes, ASCII for simple linear flows
6. Data flow — what goes in, how it transforms, what comes out (if relevant)
7. Important files — the 3-7 most important source files with one-line descriptions. These are "if you must read code, start here" pointers.
8. Edge cases and gotchas — anything surprising, non-obvious, or historically tricky
9. Dependencies — internal and external dependencies

OVERVIEW.semantic.md (Special)

Always generated first. Lives at the repo root. Contains:

• What the project is and who it's for
• How to get started (build, run, test)
• High-level structure map
• Reading guide: which *.semantic.md files to read for which topics, with relative paths

ARCHITECTURE.semantic.md (Special)

Lives at the repo root. The system-level view:

• Mermaid diagram showing all major subsystems and relationships
• Data flow across the full system
• Key architectural decisions and rationale (if inferable)
• Technology choices

Writing Style

• Explain as if to a new team member on their first day
• Avoid jargon unless you define it immediately
• Use concrete examples over abstract descriptions
• Prefer "This module takes X and produces Y" over "This module is responsible for the transformation pipeline"
• Use present tense ("handles", "sends", "validates")
• Keep paragraphs short (2-4 sentences max)

Running Modes

Full Generation (first run or explicit request)

Run this when the user invokes /semantic-git or when no *.semantic.md files exist yet.

1. Scan the entire repo. Read .gitignore first and skip all gitignored paths. Also skip .git/ and any *.semantic.md files.
2. Read project metadata files (package.json, Cargo.toml, go.mod, pyproject.toml, README.md, etc.) to understand project intent — but do not create semantic docs for these files themselves.
3. Build a mental model of the repo structure. Identify logical modules using the granularity framework.
4. Generate OVERVIEW.semantic.md at the repo root first — this forces you to understand the whole system before diving into parts.
5. Generate ARCHITECTURE.semantic.md at the repo root with system-level diagrams.
6. Generate colocated module/file docs in dependency order (document dependencies before dependents). Place each doc next to the code it describes per the naming convention.
7. Generate .semantic-manifest.json at the repo root tracking all doc locations and their commit SHAs.

Incremental Update (on commit)

Run this when code changes and *.semantic.md files already exist.

1. Run python <skill-path>/scripts/diff_analyzer.py or inspect git diff HEAD~1 --name-status to identify changed files.
2. Read .semantic-manifest.json to see what was previously documented.
3. For each changed file, identify which *.semantic.md doc covers it (the manifest maps source paths to doc paths).
4. Re-read the changed source files and the existing doc. Update only affected sections.
5. If new directories/modules appeared, decide whether they need a new colocated doc or belong in an existing one.
6. If a module was deleted, remove its colocated doc.
7. Update OVERVIEW.semantic.md and ARCHITECTURE.semantic.md if structural changes occurred (new modules, renamed directories, changed architecture).
8. Update .semantic-manifest.json with new commit SHAs and any new doc paths.

PR Mode

When running for a PR (user opened or is reviewing a PR):

1. Do everything in incremental update mode.
2. Additionally, output a plain-English summary of what changed and how it affects the documented architecture. This summary goes directly in your response (not in a file).

The Manifest File

.semantic-manifest.json at the repo root enables efficient incremental updates. Since docs are colocated throughout the repo, the manifest is the single index that tracks where all docs live.

{
  "version": 1,
  "last_full_generation": "<commit-sha>",
  "generated_by": "semantic-git",
  "docs": {
    "OVERVIEW.semantic.md": {
      "covers": ["."],
      "last_updated_commit": "<sha>"
    },
    "ARCHITECTURE.semantic.md": {
      "covers": ["."],
      "last_updated_commit": "<sha>"
    },
    "src/auth/.semantic.md": {
      "covers": ["src/auth/"],
      "last_updated_commit": "<sha>"
    },
    "src/lib/notes.semantic.md": {
      "covers": ["src/lib/notes.ts"],
      "last_updated_commit": "<sha>"
    }
  }
}

Doc paths in the manifest are relative to the repo root. Compare manifest SHAs against current HEAD to determine which docs are stale.

Git Hook Auto-Setup

After generating or updating docs, set up a post-commit hook so future commits trigger incremental updates automatically.

Setup Steps

1. Check if .git/hooks/post-commit exists.
2. If it does not exist, create it:

#!/bin/sh
# semantic-git: auto-update documentation on commit
echo "[semantic-git] Docs may need updating. Run: claude -p 'update semantic-git docs for the latest commit'"

3. If it already exists, check if it already contains a semantic-git section. If not, append the reminder block above.
4. Ensure the hook file is executable (chmod +x).
5. Tell the user the hook was set up and what it does.

The hook prints a reminder rather than auto-running Claude, since auto-running an AI agent in a git hook could be surprising. The user can upgrade this to auto-run if they prefer.

Language-Agnostic Analysis

This skill works on any language. Use these heuristics:

• File extensions identify languages, but don't rely on language-specific parsing.
• Barrel files: index.*, __init__.py, mod.rs, lib.rs indicate module entry points.
• Test directories: test/, spec/, __tests__/, *_test.*, *.spec.* are test suites.
• Config files: *.config.*, .env*, docker-compose.*, Makefile, Dockerfile.
• Project metadata: package.json, Cargo.toml, go.mod, pyproject.toml, pom.xml, build.gradle reveal project structure and dependencies.
• Import/require statements reveal dependency graphs even without AST parsing.
• README files provide intent context — read them if they exist.

Protecting Manual Edits

Before overwriting any *.semantic.md file:

1. Check if the file's content differs from what semantic-git last wrote (compare against manifest commit).
2. If the file was modified outside of semantic-git (manual edits), warn the user and ask before overwriting.
3. If the user approves, overwrite. If not, skip that file and note it in the manifest as "manually maintained".

Mermaid Diagram Guidelines

Use mermaid for architecture and data flow diagrams because it renders natively on GitHub.

• Use graph TD (top-down) for hierarchical relationships
• Use graph LR (left-right) for data flow / pipelines
• Use sequenceDiagram for request/response flows
• Keep diagrams under 15 nodes — split into multiple diagrams if larger
• Label edges with the action or data being passed
• Use subgraphs to group related components

Example:

graph TD
    A[HTTP Request] --> B[Router]
    B --> C[Auth Middleware]
    C --> D[Controller]
    D --> E[Service Layer]
    E --> F[(Database)]

For platforms that don't render mermaid, also include a brief ASCII description below the diagram as a fallback.