Document the Work Skill

Document the Work Skill

Purpose

Keep project documentation accurate and useful by updating it when setup, architecture, APIs, environment variables, scripts, or important decisions change — without over-documenting the obvious.

When to Use

• Setup steps changed (new env vars, new install/run steps).
• Architecture or folder conventions changed or were newly established.
• API behavior (request/response shape, new endpoints) changed.
• A non-obvious tradeoff or decision was made that future developers/agents should know about.

When Not to Use

• The change is self-explanatory from clear code and existing docs remain accurate.
• Documenting would just restate what the code already makes obvious.

Required Inputs

• The change made and its user/developer-facing impact.
• Existing documentation: README, /docs, architecture notes, decision logs, inline comments.

Assumptions

• Documentation should reflect the current state of the code — outdated docs are worse than no docs.
• Decision records are for non-obvious tradeoffs, not routine implementation details.

Step-by-Step Workflow

1. Identify what changed that affects documentation:
   • Setup/run instructions (new dependency, new env var, new script).
   • Architecture/conventions (new folder pattern, new shared module's purpose).
   • API contracts (new/changed endpoints, request/response shapes).
   • Decisions with tradeoffs (why X was chosen over Y).
2. Find the right existing location for each update — README section, /docs file, architecture notes, inline comment near the relevant code. Don't create a new doc file if an existing one is the natural home.
3. Update concisely:
   • Setup docs: add/update the specific step (e.g. new env var with description, new script usage).
   • Architecture notes: describe the new pattern/convention and where it applies.
   • API docs: document new/changed endpoints (method, path, request/response shape, auth requirements, errors).
   • Decision records: short entry — what was decided, why, and what alternatives were considered, if the project keeps such a log.
4. Update inline comments only where code isn't self-explanatory (non-obvious "why", not "what").
5. Check for drift: if this change makes an existing doc statement false, update or remove that statement — don't leave contradictions.

Rules and Best Practices

• Keep docs concise and accurate; don't pad with obvious explanations.