update-claude-documentation

name	update-claude-documentation
description	Use when significant implementation, architecture, API, database, routing, or planning changes require aligned project documentation and verified examples.
metadata	{"portable":true,"compatible_with":["claude-code","codex"]}

Platform Notes

• Optional helper plugins may help in some environments, but they must not be treated as required for this skill.

Update Codex Documentation

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, [phone].

Use When

• Update project documentation files (README.md, PROJECT_BRIEF.md, TECH_STACK.md, ARCHITECTURE.md, docs/API.md, docs/DATABASE.md, AGENTS.md, docs/plans/NEXT_FEATURES.md) when significant changes occur. MANDATORY at end of each work session to...

Evidence Produced

Category	Artifact	Format	Example
Release evidence	Documentation update record	Markdown doc tracking changes made to README.md, PROJECT_BRIEF.md, TECH_STACK.md, ARCHITECTURE.md, docs/API.md, and docs/DATABASE.md	docs/updates/doc-update-2026-04-16.md

References

• Use the references/ directory for deep detail after reading the core workflow below.

Update project documentation systematically after significant changes. Keep all files consistent and accurate.

Core Principle: Documentation tells one cohesive story. Each file serves a specific audience but must reflect the same reality.

Deployment Context: Project runs across Windows dev, Ubuntu staging, and Debian production (all MySQL 8.x). Documentation must reflect this 3-environment setup. When updating AGENTS.md or TECH_STACK.md, always include the deployment environment table and cross-platform rules.

Style Rule: Be precise and concise. Do not add verbose or unnecessary text to any documentation file.

Documentation Standards (MANDATORY): ALL markdown files (.md) must follow strict formatting rules:

• 500-line hard limit - no exceptions
• Two-tier structure: High-level TOC docs + Deep dive topic docs
• Smart subdirectory grouping for related documentation
• See doc-standards.md for complete requirements

Modularize Instructions (Token Economy): Avoid packing everything into a single AGENTS.md. Prefer multiple focused docs (e.g., docs/setup.md, docs/api.md, docs/workflows.md) and reference them only when needed to reduce context bloat.

AGENTS.md as Navigation Hub (CRITICAL): Keep AGENTS.md under 10k characters as a quick-reference hub with links to detailed documentation. Move verbose sections (detailed workflows, extensive examples, module-specific guides) to appropriate docs/ subdirectories. AGENTS.md should provide essential patterns and pointers, not duplicate comprehensive content that exists elsewhere. This reduces AI context window usage by 80%+ and makes information easier to maintain.

Docs Organization Rule (Required): All documentation markdown now lives under docs/ plus a semantic subdirectory (overview, architecture, pharmacy, localization, etc.). Do not add new files directly to the repo root—move existing root markdown into the appropriate docs/<module> folder before editing, then update docs/agents/AGENTS.md and always update docs/plans/AGENTS.md when plans are added or their status changes. The canonical landing doc is now docs/overview/README.md, and the root README.md should only point people into docs/.

Codex-Ready Module Headers (Required): Updating documentation now includes refreshing AGENTS.md and the hero portion of each touched skill (*/SKILL.md). Codex relies on the YAML name/description pair and the opening markdown (hero title, quick summary, when-to-use bullets) for each skill, so keep that block aligned with the module-header template in references/module-header-template.md. The template spells out the Codex-friendly structure with a checklist for ensuring the front-matter description triggers the right use cases and the leading sections stay concise yet informative.

When to Use

✅ Adding/removing features ✅ Architecture or design pattern changes ✅ Dependency or tech stack updates ✅ API endpoints or database schema changes ✅ Project directory restructuring ✅ Development workflow changes ✅ End of work session - User says "update project documentation", "update docs", or "close for the day"

❌ Typo fixes (do directly) ❌ Code comments ❌ WIP features not yet merged

End-of-Session Documentation (CRITICAL)

When user says "update project documentation", "update docs", or "close for the day":

MANDATORY Steps:

1. Create completion document - docs/plans/YYYY-MM-DD-[feature-name]-completion.md

   • Detailed technical report
   • All features and bug fixes
   • Code examples and patterns
   • Key learnings

2. Update docs/plans/INDEX.md

   • Move completed work to "Completed Plans"
   • Add completion date
   • Update status

3. Update docs/plans/NEXT_FEATURES.md (MANDATORY)

   • Mark completed features in "Recently Completed"
   • Update priority levels
   • Adjust effort estimates
   • Update recommended next steps

4. Update MEMORY.md

   • Critical patterns discovered
   • Common mistakes to avoid
   • API response structures
   • Key file references

5. Create end-of-day summary (Optional but recommended)

   • docs/YYYY-MM-DD-END-OF-DAY-SUMMARY.md
   • Quick reference for accomplishments
   • Next session priorities

This workflow ensures:

• Continuity between sessions
• Knowledge preservation
• Clear priorities for next session
• Reduced context loss

Documentation Files

File	Audience	Purpose	Update Frequency
PROJECT_BRIEF.md	Stakeholders, new devs	30-sec overview	Major changes
README.md	Developers	Setup, usage guide	Feature additions
TECH_STACK.md	Developers, DevOps	Tech inventory	Stack changes
ARCHITECTURE.md	Senior devs, architects	System design	Architecture changes
docs/API.md	API consumers	API reference	API changes
docs/DATABASE.md	Backend devs, DBAs	Schema docs	Schema changes
AGENTS.md	Codex	Dev patterns	Pattern changes
docs/plans/NEXT_FEATURES.md	Team, Codex	Priority roadmap	Every session
docs/plans/INDEX.md	Team, Codex	Plans index	Plan status changes
MEMORY.md	Codex	Session memory, learnings	End of each session

Change → File Mapping

New Feature:

• README.md (usage)
• docs/API.md (if adds endpoints)
• docs/DATABASE.md (if adds tables)
• ARCHITECTURE.md (if adds components)
• AGENTS.md (if changes patterns)
• PROJECT_BRIEF.md (if significant)
• docs/plans/NEXT_FEATURES.md (MANDATORY - mark as completed, update priorities)
• docs/plans/INDEX.md (update status)
• MEMORY.md (capture key learnings)
• Each affected */SKILL.md front-matter and hero section should follow the module-header template above so Codex sees the change immediately and can re-trigger the skill with the new context.

Tech Stack Change:

• TECH_STACK.md (always)
• README.md (setup instructions)
• ARCHITECTURE.md (if affects design)
• AGENTS.md (if affects workflows)

Architecture Change:

• ARCHITECTURE.md (always)
• README.md (overview section)
• AGENTS.md (patterns)
• PROJECT_BRIEF.md (if major)

API/Database Change:

• docs/API.md or docs/DATABASE.md (always)
• ARCHITECTURE.md (if changes contracts)
• AGENTS.md (if affects patterns)
• README.md (if affects usage)

Update Workflow

1. Understand Change (2-5 min)

Document:

• Type: Feature/Architecture/Tech Stack/API/Database
• What: One sentence description
• Impact: Who/what affected
• Breaking: Yes/No (what breaks)

2. Map to Files (1-2 min)

Order: Specific → General

1. Technical Specs (API.md, DATABASE.md)
2. Architecture (ARCHITECTURE.md, TECH_STACK.md)
3. AI Instructions (AGENTS.md)
4. User Guides (README.md)
5. Overview (PROJECT_BRIEF.md)
6. Priority Roadmap (docs/plans/NEXT_FEATURES.md) - MANDATORY every session

3. Read Current State (2-3 min)

Read all affected files in parallel.

3.a. Review Module Headers (1-2 min)

Open every impacted */SKILL.md and verify the hero name/description plus the opening sections line up with the Codex-friendly template. Capture the new feature/behavior in the quick summary and ## When to Use bullets before editing the downstream docs.

4. Update Systematically (10-20 min)

Per-file checklist:

• Update primary section
• Update related sections
• Update examples/code snippets
• Add migration notes if breaking

5. Verify Consistency (2-3 min)

Check across all files:

• Terminology consistent
• Version numbers match
• File paths consistent
• Component names consistent
• Features described consistently

6. Update NEXT_FEATURES.md (MANDATORY - 5 min)

CRITICAL: This MUST be done at the end of every work session, even if no other docs changed.

When user says "update project documentation" or "close for the day":

1. Mark completed work:

   • Move completed features from "Active" to "Recently Completed"
   • Add completion date
   • Add brief summary of what was delivered

2. Update priorities:

   • Adjust priority levels based on new information
   • Add newly identified features
   • Remove obsolete features

3. Update effort estimates:

   • Revise estimates based on recent work velocity
   • Add new estimates for newly identified work

4. Update recommended next steps:

   • Reflect current project state
   • Consider dependencies and urgency
   • Update "Recommended Next Session Plan"

Template structure:

## 🔴 CRITICAL PRIORITY
[Feature name] - Why critical, effort estimate, start point

## 🟠 HIGH PRIORITY
[Feature name] - Why high priority, effort estimate, start point

## 🟡 MEDIUM PRIORITY
[Feature name] - Why medium priority, effort estimate, start point

## ✅ Recently Completed
[Feature name] - Completion date, brief summary

Location: docs/plans/NEXT_FEATURES.md

7. Final Review (1 min)

• New dev can understand from README
• AGENTS.md has context
• Breaking changes marked
• Examples work
• No contradictions
• NEXT_FEATURES.md updated with session changes

Total: 20-35 minutes (includes NEXT_FEATURES.md update)

Common Mistakes

❌ Updating only one file

# Updated README but forgot AGENTS.md

# Result: AI doesn't know new pattern

❌ Inconsistent terminology

# README.md: "Authentication Service"

# ARCHITECTURE.md: "Auth Module"

# AGENTS.md: "Login System"

# Pick ONE term everywhere

❌ Forgetting breaking changes

# Renamed API endpoint but README examples still use old path

# Add migration notes EVERYWHERE affected

❌ General → Specific order

# BAD: Update BRIEF first, then API.md

# GOOD: Update API.md first (precise), then BRIEF (summary)

❌ Bloated AGENTS.md with duplicate content

# BAD: 40k+ character AGENTS.md with detailed implementation guides

# GOOD: 6k character AGENTS.md hub linking to docs/coding/UI_DEVELOPMENT_GUIDE.md

# Result: 84% reduction in AI context usage, easier maintenance

Quick Reference

Update Order:

API/DB Specs → Architecture → Codex → README → BRIEF

Consistency Checks:

Terminology, Versions, Paths, Names, Features

Time Budget:

Small change: 5-10 min
Medium change: 15-30 min
Major refactor: 45-60 min

Summary

Process: Understand → Map → Read → Update → Verify → Review

Key Rules:

1. Update specific docs first, general last
2. Read all affected files before editing
3. Keep terminology consistent
4. Mark breaking changes everywhere
5. Test examples before committing
6. One reality, multiple perspectives

Remember: Documentation debt compounds fast. Update immediately when making changes.

Capability contract

Require read and search access to code, diffs, and current documentation. Editing follows the documentation scope. Execute example checks when available; otherwise mark examples unverified.

Degraded mode

Fallback when source access is unavailable: draft a change plan rather than asserting current behaviour. Without execution, list examples requiring verification.

Decision rules

Change	Documentation action	Failure avoided
Behaviour or interface changed	Update user and technical truth sources	Stale operating guidance
Internal refactor with no observable effect	Update architecture only if boundaries changed	Churn without information gain
Routing or skill policy changed	Align router, index, fixtures, and update note	Contradictory discovery rules

Domain anti-patterns

• Updating the README but not architecture truth. Fix: align every affected canonical document.
• Copying implementation details without verification. Fix: inspect code and tests first.
• Changing examples without running them. Fix: execute or mark them unverified.
• Recording plans as completed behaviour. Fix: separate current state from roadmap.
• Rewriting unrelated documentation for style. Fix: keep the change scoped to the actual delta.

Inputs

Artefact	Required?	Purpose
Implementation diff, current documents, architecture truth, and verified examples	yes	Align documentation with reality

Outputs

• Produce aligned documentation changes, verification results, and remaining update gaps.