aiskillstore/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

```python
# 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"
  }
}