Analyze code changes and recommend appropriate documentation. Evaluates git diffs to determine if changes warrant README updates, inline doc additions, or dedicated documentation files. Triggers on: document changes, what should I document, doc writer, write docs for changes, documentation recommendation.
Analyze recent code changes and recommend appropriate documentation. This skill examines git diffs, categorizes changes, and determines the right level of documentation needed - from a simple README bullet point to a full documentation file.
Invoke this skill when:
First, gather the changes to analyze. Run these commands to understand the scope:
# Check uncommitted changes
git status
# View staged changes
git diff --cached --stat
# View unstaged changes
git diff --stat
# View recent commits (last 5)
git log --oneline -5
# View changes from specific commit
git show <commit> --stat
Classify each change into one of these categories:
| Category | Description | Examples |
|---|---|---|
| New Feature | Adds user-facing functionality | New CLI command, new tool support, new config option |
| Enhancement | Improves existing feature | Performance boost, better error messages, UX improvement |
| Bug Fix | Corrects incorrect behavior | Crash fix, logic error, edge case handling |
| Refactor | Internal restructuring | Code reorganization, pattern changes, no behavior change |
| Infrastructure | Build/CI/tooling changes | CI workflows, build scripts, dev tooling |
| Breaking Change | Incompatible API/behavior change | Removed feature, changed defaults, config format change |
Use this decision matrix to determine documentation level:
User-Facing?
/ \
Yes No
/ \
Breaking? Large Refactor?
/ \ / \
Yes No Yes No
| | | |
[MAJOR DOC] [README + [ARCHITECTURE [COMMIT
INLINE] DOC] MSG ONLY]
Documentation Levels:
Based on analysis, provide a structured recommendation:
## Documentation Recommendation
### Changes Analyzed
- [List of files/commits analyzed]
### Change Category
[Category from Step 2]
### Recommended Documentation
**Level:** [Commit Only | Inline | README | Dedicated | Multiple]
**Action Items:**
1. [ ] [Specific documentation task]
2. [ ] [Another task if needed]
**Suggested Content:**
[Draft text or outline for the documentation]
**Location:**
- File: [path/to/doc/file]
- Section: [specific section to update]
For new features, add to the appropriate README section:
### [Feature Name]
[One-sentence description of what it does]
**Usage:**
```bash
jarvy [command] [options]
Example:
# Example showing the feature in action
jarvy setup --feature-flag
### README Configuration Update
For new config options:
```markdown
### [Option Name]
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `option` | string | `"default"` | What this option controls |
**Example:**
```toml
[section]
option = "value"
### Inline Documentation
For code comments explaining complex logic:
```rust
/// Brief description of what this does
///
/// # Arguments
/// * `param` - What this parameter is for
///
/// # Returns
/// What gets returned and when
///
/// # Example
/// ```
/// let result = function(input);
/// ```
fn function(param: Type) -> ReturnType {
// Implementation note: explain WHY, not WHAT
}
For major features, create docs/[feature-name].md:
# [Feature Name]
## Overview
[2-3 sentences explaining the feature and its purpose]
## Prerequisites
- [Required setup or dependencies]
## Usage
### Basic Usage
[Simple example with explanation]
### Advanced Usage
[More complex scenarios]
## Configuration
[Config options specific to this feature]
## Troubleshooting
### [Common Issue]
**Symptom:** [What the user sees]
**Cause:** [Why it happens]
**Solution:** [How to fix it]
## See Also
- [Related documentation links]
| Change Type | Documentation Location | Template |
|---|---|---|
| New CLI command | README + --help text | README Feature Addition |
| New tool support | README tools list + tool's inline docs | README Feature Addition |
| New config option | README config section | README Configuration Update |
| Performance improvement | README or changelog | Brief mention |
| Bug fix | Changelog only (if exists) | None needed |
| Internal refactor | Code comments if complex | Inline Documentation |
| Breaking change | README + MIGRATION.md | Multiple templates |
| New architecture | docs/architecture.md | Dedicated Documentation |
Scenario: Added support for fnm as a Node.js version manager
Analysis:
## Documentation Recommendation
### Changes Analyzed
- src/tools/fnm/fnm.rs (new file)
- src/tools/fnm/mod.rs (new file)
- src/tools/mod.rs (register fnm)
### Change Category
New Feature - Adds user-facing functionality
### Recommended Documentation
**Level:** README Update
**Action Items:**
1. [ ] Add fnm to supported tools list in README
2. [ ] Add fnm configuration example to jarvy.toml docs
3. [ ] Update "Version Managers" section if exists
**Suggested Content:**
- **fnm** - Fast Node.js version manager written in Rust
**Location:**
- File: README.md
- Section: Supported Tools (or create if missing)
Answer these questions:
Does this change how users interact with the tool?
Does this change configuration options?
Does this add a new tool/feature?
Is this a breaking change?
Is this a bug fix users might search for?
Is this internal refactoring only?