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)

Rationalization	Why It's Wrong	Required Action
"Too small to document"	Small changes accumulate	Update PLAN.md
"I'll remember"	Context is lost between sessions	Write it down
"README is fine"	Feature docs get stale	Verify accuracy
"Just a bug fix"	Bugs deserve tracking	Mark complete
"Package has its own PLAN"	Fragmentation causes confusion	Consolidate to root PLAN.md

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