akshay-babbar/doc-sync
Auto-syncs stale docstrings and README when function signatures change. Detects documentation drift after refactors, parameter additions, or return type changes. Dry-run by default — proposes before writing.
87
1.59x
Quality
100%
Does it follow best practices?
Impact
86%
1.59xAverage score across 17 eval scenarios
Securityby
Passed
No known issues
doc-sync
Auto-syncs docstrings when code changes. Proposes README updates — never auto-writes.
The Mental Model
CODE CHANGE ──► doc-sync ──► Docstring: auto-write (after you confirm)
│
└─► README: propose only (you decide)One rule: If documentation already exists for a symbol, keep it in sync. If not, report missing coverage — don't create from scratch.
Quick Start
# Install
npx tessl install akshay-babbar/doc-sync
# Preview what would change
/doc-sync --dry-run
# Apply changes (asks for confirmation first)
/doc-sync --apply
# Check last 3 commits
/doc-sync --dry-run HEAD~3..HEADWhat Gets Updated
| Target | Behavior |
|---|---|
| Docstrings | Auto-written after you confirm the report |
| README mentions | Proposed only — never auto-applied |
| CHANGELOG / ADRs | Never touched |
The Trust Model
┌─────────────────────────────────────────────────┐
│ YOUR DOCUMENTATION │
├─────────────────────────────────────────────────┤
│ DOCSTRINGS │ README / MARKDOWN │
│ ─────────── │ ───────────────── │
│ Auto-write │ Propose only │
│ (after confirm) │ (you approve) │
├─────────────────────────────────────────────────┤
│ PROTECTED: CHANGELOG, ADRs, LICENSE, SECURITY │
│ ───────────────────────────────────────────── │
│ Never modified. Period. │
└─────────────────────────────────────────────────┘Example
Code change:
- def fetch_user(user_id: int) -> User:
+ def fetch_user(user_id: int, include_profile: bool = False) -> User:What doc-sync does:
- Detects the new parameter
- Finds the docstring for
fetch_user - Shows you: "Will add
include_profileto docstring" - After you confirm, adds:
Args: user_id: The user's unique identifier. + include_profile: Whether to include profile data. Defaults to False.
Supported Languages
Python, TypeScript/JavaScript, Go, Rust, Ruby, Java, Kotlin
Philosophy
| We do | We don't |
|---|---|
| Update existing docs | Create new docs from scratch |
| Flag ambiguity | Guess and silently fix |
| Ask before writing | Auto-commit changes |
| Minimal surgical edits | "Improve" surrounding content |
Platforms
| Platform | Status |
|---|---|
| Claude Code | ✅ |
| Windsurf | ✅ |
| Cursor | ✅ |
| OpenCode | ✅ |
Why trust this tool? See TRUST.md for what we protect and why.
- Workspace
- akshay-babbar
- Visibility
- Public
- Created
- Last updated
- Publish Source
- CLI
- Badge