Documentation Maintenance

Automatically updates project documentation after task completion.

Consolidated Plan Location

All plan updates go to root PLAN.md. This is the single source of truth for project planning. Package-level PLAN.md files should be consolidated into the root PLAN.md.

Trigger Conditions

Invoke after:

• •Completing any task
• •Adding a new feature
• •Fixing a bug
• •Refactoring code
• •Resolving a blocked item

Also invoke explicitly with:

• •/doc-maintenance
• •"update documentation"
• •"sync docs"

Pre-Merge Cleanup

When owner says "clean up before merge" or similar, run this checklist:

# 1. Sync CLAUDE.md with installed skills (removes stale refs)
skills claudemd sync

# 2. Scan for test artifacts and slop
skills hygiene scan

# 3. If slop found, clean it
skills hygiene clean --confirm

# 4. Validate chain config (if chain files changed)
chain validate

# 5. Update PLAN.md with completed work
# (follow doc-maintenance procedure below)

# 6. Commit and push
git add -A && git commit -m "chore: pre-merge cleanup" && git push

This is the standard cleanup before any PR merge.

Procedure

Step 1: Read Current State

Read these files:

• •PLAN.md (root, consolidated project plan)
• •README.md (feature documentation)
• •packages/*/PLAN.md (check for package-level plans to consolidate into root)
• •Recent git commits (what changed)

Step 2: Consolidate Package Plans

If packages/*/PLAN.md files exist, consolidate their content into root PLAN.md:

1. •Each package gets a section: ## Package: {name}
2. •Move completed items to the Completed section
3. •Move pending items to the appropriate sprint/backlog section
4. •Delete the package-level PLAN.md after consolidation

Structure for root PLAN.md:

# Project Plan

## Current Sprint
- Active work items across all packages

## Package: chain
- Package-specific in-progress work

## Package: cli
- Package-specific in-progress work

## Backlog
- Future work items

## Completed
- Timestamped completed items

## Blocked
- Items waiting on dependencies

Step 3: Analyze Changes

Determine what was accomplished:

• •Which PLAN.md items are now complete?
• •Were new features added?
• •Were bugs fixed?
• •Did refactoring occur?
• •Were new issues discovered?

Step 4: Update PLAN.md

Mark completed items:

## Current Sprint
- [x] Implement user authentication  # Was [ ]
- [ ] Add password reset flow

Add discovered work:

## Backlog
- [ ] Discovered: Need rate limiting for auth endpoints
- [ ] Tech debt: Refactor auth middleware

Move completed items with timestamp:

## Completed
- [x] Implement user authentication (2026-01-30)

Update blocked items:

## Blocked
- Password reset: Waiting for email service setup

Step 5: Update README.md (If Features Changed)

When to update README.md:

• •New user-facing feature added
• •API changed
• •New command available
• •Installation steps changed

What to update:

• •Features list
• •Usage examples
• •API reference
• •Installation instructions

Step 6: Report Changes

Output a summary:

Documentation updated:

PLAN.md:
  - Marked complete: "Implement user authentication"
  - Added to backlog: "Need rate limiting for auth endpoints"
  - Moved to completed: 1 item
  - Consolidated from: packages/chain/PLAN.md

README.md:
  - Updated features list with authentication
  - Added auth usage example

Skill Chaining

With markdown-writer

All documentation updates MUST follow markdown-writer style:

• •Short sentences, direct claims
• •No em dashes
• •Active voice
• •Tables for structured data

Implicitly chain markdown-writer when editing any .md file.

After TDD Completion

When TDD workflow completes (GREEN phase):

1. •Mark the related PLAN.md task as complete
2. •Add any discovered edge cases to backlog

After Bug Fix

When a bug is fixed:

1. •Mark bug item as complete in PLAN.md
2. •Add regression test to PLAN.md if not present

After Refactoring

When refactoring completes:

1. •Mark refactoring task as complete
2. •Update any affected API documentation

Terminal Chain

After any documentation update: repo-hygiene (clean stale references)

Update Patterns

Marking Tasks Complete

Before:

- [ ] Implement feature X

After:

- [x] Implement feature X

Adding Discovered Work

When you discover new tasks during implementation:

## Backlog
- [ ] (discovered) New task from implementation
- [ ] (tech debt) Code that needs cleanup
- [ ] (bug) Issue found during testing

Timestamping Completed Items

Add date to completed items:

## Completed
- [x] Task description (2026-01-30)

Feature Documentation

When adding a feature to README.md:

## Features

- **Authentication**: Secure user login with JWT tokens
- **Password Reset**: Email-based password recovery

Rationalizations (Do Not Skip)

Example Session

Task: Add user authentication

After completion:

/doc-maintenance

Analyzing changes...

Found:
- New auth middleware in src/middleware/auth.ts
- New login endpoint in src/routes/auth.ts
- 5 new test files
- Git commit: "Add JWT authentication"
- packages/chain/PLAN.md exists (needs consolidation)

Updates:

PLAN.md:
  Current Sprint:
    - [x] Implement user authentication
  Backlog:
    + [ ] (discovered) Add refresh token support
    + [ ] (discovered) Rate limit login attempts
  Consolidated:
    - Merged packages/chain/PLAN.md content

README.md:
  Features:
    + Authentication: JWT-based user authentication
  Usage:
    + Added auth example code

Notes

• •All plan updates go to root PLAN.md (consolidated)
• •Package-level PLAN.md files should be consolidated, not maintained separately
• •Never removes items from PLAN.md (only marks complete)
• •Preserves existing formatting
• •Adds timestamps to completed items
• •Creates backlog items for discovered work
• •Only updates README.md when features change
• •Always follows markdown-writer style