post-impl-docs

Post-Implementation Documentation Skill

Automatically update repository documentation to reflect code changes. This skill ensures that when code is implemented, the documentation stays in sync with the actual codebase.

Variables

| Variable | Default | Description | |----------|---------|-------------| | UPDATE_README | true | Update README.md for new features/APIs | | UPDATE_CHANGELOG | true | Add entries to CHANGELOG.md | | UPDATE_DOCS_FOLDER | true | Update files in docs/ that reference changed code | | UPDATE_DOCSTRINGS | true | Update inline docstrings for changed functions/classes | | CHANGELOG_FORMAT | conventional | conventional, keep-a-changelog, simple | | COMMIT_DOCS | true | Commit documentation changes with code |

Instructions

MANDATORY - Follow the Workflow steps below in order. Do not skip steps.

1. Analyze what code changes were made (git diff)
2. Determine documentation impact
3. Update README if new features/APIs added
4. Update CHANGELOG with change summary
5. Scan docs/ folder for references to changed symbols
6. Update inline docstrings for modified functions/classes

Red Flags - STOP and Reconsider

If you're about to:

• Update documentation without understanding the code changes
• Add CHANGELOG entries for trivial changes (typos, formatting)
• Update README for internal implementation details
• Modify docstrings without verifying the behavior changed

STOP -> Review the diff -> Understand the impact -> Then document

Workflow

1. Gather Change Context

Analyze what was changed in the current implementation:

# Get changed files
git diff --name-only HEAD~1 HEAD

# Get change summary
git diff --stat HEAD~1 HEAD

# Get detailed changes for documentation
git diff HEAD~1 HEAD -- "*.py" "*.ts" "*.js" "*.go" "*.rs"

2. Classify Changes

Determine the type and scope of changes:

| Change Type | README Impact | CHANGELOG Entry | Docs Update | |-------------|---------------|-----------------|-------------| | New feature | Add to Features section | feat: entry | If documented | | Bug fix | No change | fix: entry | If affects behavior | | Breaking change | Update usage examples | BREAKING: entry | Update all refs | | API addition | Add to API section | feat: entry | Add API docs | | Deprecation | Add deprecation note | deprecate: entry | Update examples | | Performance | No change | perf: entry | No | | Refactor | No change | refactor: entry | No | | Docs only | N/A | No entry | N/A | | Tests only | No change | test: entry | No |

3. Update README.md

Only update README for significant changes:

Add new feature to Features section:

## Features

- **New Feature Name** - Brief description of what it does

Add new API to API/Usage section:

## API

### `newFunction(param: Type): ReturnType`

Description of the function and its purpose.

Update usage examples if API changed:

## Usage

Updated example reflecting new API

result = module.new_function(param="value")

### 4. Update CHANGELOG.md

Add entry following the project's format:

**Conventional Changelog:**

[Unreleased]

Added

• Add user authentication endpoint (#123)

Changed

• Update database connection pool size for better performance

Fixed

• Fix race condition in async queue processor (#124)

Deprecated

• Deprecate old_function() in favor of new_function()

Removed

• Remove support for Python 3.8

Security

• Fix XSS vulnerability in user input handling

**Keep a Changelog format:**

[Unreleased]

Added

• New feature description

Changed

• Change description

### 5. Update docs/ Folder

Scan documentation files for references to changed symbols:

Find docs that reference changed functions/classes

grep -r "changed_function\|ChangedClass" docs/

For each match:
1. Verify if the documentation is still accurate
2. Update parameter descriptions if signature changed
3. Update examples if behavior changed
4. Update cross-references if file moved

### 6. Update Inline Docstrings

For each modified function/class with docstrings:

**Python:**

def function(param: str) -> bool: """Updated description reflecting new behavior.

Args: param: Updated parameter description.

Returns: Updated return value description.

Raises: ValueError: If param is invalid (new error case). """

**TypeScript/JavaScript:**

/**

• Updated description reflecting new behavior.

*

• @param param - Updated parameter description
• @returns Updated return value description
• @throws {Error} If param is invalid (new error case)

*/ function func(param: string): boolean {

## Cookbook

### README Updates
- IF: Adding new public feature
- THEN: Read `cookbook/readme-updates.md`
- RESULT: Updated feature list and examples

### CHANGELOG Entries
- IF: Writing CHANGELOG entries
- THEN: Read `cookbook/changelog-formats.md`
- RESULT: Properly formatted entries

### Docstring Standards
- IF: Updating inline documentation
- THEN: Read `cookbook/docstring-standards.md`
- RESULT: Consistent docstring format

## Quick Reference

### What to Document

| Change | README | CHANGELOG | docs/ | Docstrings |
|--------|--------|-----------|-------|------------|
| New public API | Yes | Yes | Yes | Yes |
| New internal function | No | Maybe | No | Yes |
| Bug fix | No | Yes | If behavior docs exist | If signature changed |
| Performance improvement | No | Yes | No | No |
| Breaking change | Yes | Yes | Yes | Yes |
| Deprecation | Yes | Yes | Yes | Yes |

### Conventional Commit to CHANGELOG Mapping

| Commit Type | CHANGELOG Section |
|-------------|-------------------|
| `feat:` | Added |
| `fix:` | Fixed |
| `perf:` | Changed |
| `refactor:` | Changed |
| `deprecate:` | Deprecated |
| `BREAKING CHANGE:` | Changed (with breaking note) |
| `security:` | Security |
| `docs:` | (skip) |
| `test:` | (skip) |
| `chore:` | (skip) |

## Integration Points

This skill is invoked:
1. **By lane-executor**: After completing implementation tasks
2. **By test-engineer**: After significant test additions
3. **Before PR creation**: Ensure docs are current

### Example Integration in Lane Executor

Post-Implementation Steps

After completing implementation:

1. Run dependency-sync skill to update manifests
2. Run post-impl-docs skill to update documentation
3. Verify build/tests still pass
4. Commit all changes together

## Output

### Documentation Update Report

{ "status": "success", "updates": { "readme": { "updated": true, "sections_modified": ["Features", "API"] }, "changelog": { "updated": true, "entries_added": [ {"type": "feat", "description": "Add user authentication endpoint"} ] }, "docs_folder": { "files_updated": ["docs/api.md", "docs/getting-started.md"], "references_fixed": 3 }, "docstrings": { "functions_updated": 5, "classes_updated": 2 } }, "commit_sha": "abc123" }

### No Changes Report

{ "status": "no_changes", "reason": "Changes are internal implementation only", "analysis": { "change_type": "refactor", "public_api_affected": false, "documentation_impact": "none" } }