docs-submodule-manager_skill

Overview

This skill manages documentation inside a docs/ git submodule, ensuring proper initialization, structure, synchronization, and commits. It enforces a clear directory layout (solutions/, specs/, feature/) under docs/<repo-name>/ and automates safe sync-and-commit steps for both the submodule and the parent repository. Use it to create, update, and track specs, implementation plans, progress, and solutions reliably.

How this skill works

The skill checks whether docs/ is an initialized git submodule and runs setup or git submodule update --init --recursive if needed. It determines the parent repository name and places content under docs/<repo-name>/ using the recommended subdirectories (solutions, specs, feature) and standard files like implementation-plan.md and progress.md. Before writing it fetches and pulls from remote master, stages and commits changes inside the submodule, pushes, then commits the updated submodule reference in the parent repo. It detects common errors (merge conflicts, missing directories) and prompts the user with safe options rather than forcing destructive actions.

When to use it

• When the user asks to add docs, specs, PRDs, or implementation plans.
• When creating or editing files inside the docs/ directory.
• When working on features that need tracked specs or progress updates.
• When documenting solutions for issues, bug workarounds, or architecture notes.
• When you need to ensure the docs submodule is initialized and synced before changes.

Best practices

• Place content under docs/<repo-name>/ and choose the correct category: solutions/, specs/, or feature/.
• Create implementation-plan.md for specs and progress.md for ongoing work with many todos.
• Always fetch and pull from origin master in the submodule before making edits.
• Use clear commit messages (e.g., "doc: added spec for <feature-name>").
• Do not force push or reset submodule history without explicit user approval; surface conflicts for manual resolution.

Example use cases

• Add a technical spec: create docs/<repo-name>/specs/chat-refactor/implementation-plan.md and commit both submodule and parent repo.
• Track feature progress: update docs/<repo-name>/specs/offline-sync/progress.md and push changes.
• Document a bug solution: add docs/<repo-name>/solutions/navigation-crash/README.md and commit.
• Initialize docs submodule in a fresh clone and populate directory structure for a new repo.
• Prepare a PRD: create docs/<repo-name>/feature/voice-messaging/prd.md and follow the sync workflow.