When should I create an ADR?

When a code change involves non-trivial, non-obvious decisions and multiple alternatives.

Where should ADRs be stored?

Under /docs/adr to preserve the decision rationale for future reference.

What if no documentation updates are required?

Note the review in the PR description and confirm no changes were needed; the skill still ensures awareness and consistency.

documentation-process

Scanned

npx machina-cli add skill serpro69/claude-starter-kit/documentation-process --openclaw

Files (1)

SKILL.md

746 B

Documentation Process

Guidelines

After completing a new feature, always see if you need to update the Architecture documentation at /docs/contributing/ARCHITECTURE.md and Test documentation in /docs/contributing/TESTING.md for other developers, so anyone could easily pick up the work and understand the project and the feature that was added.
If the code change included prior decision-making out of several alternatives, document an ADR at /docs/adr for any non-trivial/non-obvious decisions that should be preserved.

Source

git clone https://github.com/serpro69/claude-starter-kit/blob/master/.github/templates/claude/skills/documentation-process/SKILL.md

View on GitHub

Overview

After implementing a new feature or fixing a bug, this skill drives documenting the changes in project docs. It guides updating Architecture and Testing docs and, when applicable, recording decisions as ADRs. Clear documentation improves onboarding, maintenance, and knowledge transfer.

How This Skill Works

Identify impacted docs based on the code changes, then update /docs/contributing/ARCHITECTURE.md and /docs/contributing/TESTING.md as needed. If the change involved non-trivial decisions among alternatives, create an ADR under /docs/adr and reference it in the PR. Always finish documentation updates after the implementation phase and tie them to the feature or bug-fix commit.

When to Use It

After delivering a new feature
After fixing a bug that changes behavior or setup
When changes affect architecture or testing requirements
When there were non-trivial design decisions among alternatives
During release readiness or handoff to other teams

Quick Start

Step 1: Review code changes and identify impacted docs
Step 2: Update ARCHITECTURE.md, TESTING.md, and create ADR if needed
Step 3: Commit and reference the documentation updates in the PR

Best Practices

Review and update ARCHITECTURE.md when architecture changes are introduced
Update TESTING.md with new test cases, coverage, and run instructions
Document any non-trivial decisions with an ADR at /docs/adr
Link docs updates to the related commit message and PR
Keep docs concise, timestamped, and easy to navigate for future contributors

Example Use Cases

Feature addition: added OAuth login; updated ARCHITECTURE.md and TESTING.md accordingly
Bug fix: race condition fix; ADR created to capture the decision among alternatives
API change: endpoint behavior updated; docs reflect new input/output and error codes
Refactor with behavior change: logging format changed; updated tests and architecture notes
Documentation-only change: clarified contributor guidelines in ARCHITECTURE.md

Frequently Asked Questions

Add this skill to your agents