aspiers/documentation-updates

Documentation Updates

Update documentation based on lessons learned from the conversation.

When to Use This Skill

Use this skill when:

• You made a mistake or misunderstanding that could have been prevented
• You discovered something that should be documented for future reference
• The user asks you to "reflect" on what happened
• After completing work where documentation gaps were discovered

Process

Momentarily pause any other actions to review the conversation and reflect on any mistakes or misunderstandings. Update any/all of the following as appropriate:

Files to Update

1. Project-level documentation:

   • AGENTS.md in the current project
   • CLAUDE.md in the current project
   • Any project-specific documentation

2. Global documentation:

   • Global AGENTS.md (~/.claude/AGENTS.md or similar)
   • Global CLAUDE.md

3. Agent settings:

   • Per-project settings (.claude/settings.json, opencode.json)
   • Per-project agent skills in .agents/skills
   • Global settings (~/.config/opencode/opencode.json, ~/.claude/settings.json)
   • Global agent skills in ~/.agents/skills

4. Other project documentation:

   • README.md
   • Design documents
   • Architecture guides

Bear in mind that many global files for agent config and skills are stowed via GNU Stow using symlinks which point back to a git repo somewhere.

What to Document

• Common pitfalls encountered and how to avoid them
• Important constraints or requirements discovered
• Useful patterns or approaches found effective
• Mistakes made and what should have been done differently
• Configuration or setup nuances

Important Rule

Do NOT resume ANY previous actions until the user is satisfied that the docs have been appropriately updated.

Output

After updating documentation:

• List the files that were modified
• Summarize the changes made
• Confirm with the user that the updates are adequate