document-us

Generates detailed EXPLAINED.md documentation for User Stories from git diffs.

Updated May 1, 2026
One-click install
npx skills add https://github.com/ricardoo022/4dill --skill document-us-ricardoo022
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: document-us
Source: https://github.com/ricardoo022/4dill/tree/main/.gemini/skills/document-us
Command: npx skills add https://github.com/ricardoo022/4dill --skill document-us-ricardoo022

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing deep, line-by-line technical documentation for a completed User Story before opening a PR is tedious and often skipped. This Skill automates the creation of a structured EXPLAINED.md file in docs/Epics/ by reading the branch's git diff and following the project's established documentation pattern. ## Core Features & Use Cases - Diff-Driven Documentation: Reads the current branch name, git diff, and commit history to explain only the code that was added or modified. - Strict Pattern Compliance: Enforces the project's Epics doc pattern including Obsidian frontmatter, Portuguese prose, field tables for Pydantic models, ASCII flow diagrams, and mandatory Related Notes wikilinks. - Vault Index Updates: Automatically adds the new doc entry to docs/README.md so the Obsidian vault index stays current. - Use Case: After finishing a feature branch like feature/US-042-docker-client, ask the assistant to document the US before the PR, and it produces docs/Epics/Docker Sandbox/US-042-DOCKER-CLIENT-EXPLAINED.md with full code explanations. ## Quick Start Ask the assistant to document the current branch's User Story and generate the EXPLAINED.md file before opening the pull request.

Frequently Asked Questions about document-us

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate documentation for a User Story from a git diff?▼

Run the skill on a feature branch named feature/US-XXX-description. It reads git diff main...HEAD, the commit log, and docs/USER-STORIES.md, then writes a structured EXPLAINED.md covering every changed file under docs/Epics/<Epic Folder>/.

What documentation format does the EXPLAINED.md file follow?▼

The doc follows the pattern in references/doc-pattern.md: Obsidian frontmatter tags, a Contexto section, per-file sections with actual code blocks and explanation tables, optional PentAGI Go references, and a mandatory Related Notes section using Obsidian wikilinks.

Does the skill work with Obsidian vaults and wikilinks?▼

Yes. The generated docs are designed for Obsidian: they use [[wikilinks]] in the Related Notes section for graph navigation, valid frontmatter tags, and explicit Markdown links only when note names are ambiguous.

What language is the generated documentation written in?▼

Prose and section headings are written in Portuguese, while code, variable names, and comments inside code blocks remain in English, matching the project's established Epics documentation convention.

What are the limitations of diff-based documentation generation?▼

The skill only explains code added or modified in the current branch's diff, so pre-existing code is covered only when essential for context. It also depends on the branch naming convention feature/US-XXX and the presence of docs/USER-STORIES.md to resolve the epic.