Document

Document Changes

This command creates structured documentation for changes made during the current coding session. Documentation is placed under the docs/ folder at the root of the solution.

When to Use

Run /document after completing a feature, refactoring, or significant change that warrants documentation for future reference.

Related Commands

After documenting, consider whether additional changelog updates are needed:

Typical flow:

1. /document — Always create technical documentation first
2. /add-changelog — If user-facing, add to customer changelog

Output Structure

docs/
├── README.md              # Central index with links to all documentation
├── Changelog.md           # Customer-facing changelog (user-notable features/fixes only)
├── YYYY/
│   └── MM/
│       └── YYYY-MM-DD-<slug>.md   # Individual change documents
└── diagrams/
    └── <feature>-*.md     # Standalone Mermaid diagram files (if large)

Documentation Workflow

1. Gather Current State

Before documenting, analyze the current session:

1. Review git status - Identify all modified, added, and deleted files
2. Review git diff - Understand the actual code changes made
3. Read existing documentation - Check docs/README.md to understand current state
4. Check for existing change log - If documenting a multi-day feature, look for existing docs to update

# Run these to understand current changes
git status
git diff --stat
git diff HEAD~1..HEAD  # Recent commits

2. Identify Scope

Determine the scope of changes within the repository. Documentation should be created in the docs/ directory.

3. Create Change Document

Create a new markdown file using this template:

File: docs/YYYY/MM/YYYY-MM-DD-<slug>.md

# <Title: Brief Description of Change>

**Date:** YYYY-MM-DD  
**Author:** AI Assistant  
**Related Issues:** (if any)

## Summary

<1-3 sentence overview of what was accomplished>

## Context & Motivation

- Why was this change needed?
- What problem does it solve?
- What alternatives were considered?

## Plan

<Document the approach taken>

1. Step one taken
2. Step two taken
3. ...

## Architecture / Design

<Include Mermaid diagrams where helpful>

```mermaid
flowchart TD
    A[Component A] --> B[Component B]
    B --> C[Component C]

Changes Made

Files Modified

Key Code Changes

Change Log

Document the sequence of changes made during implementation:

Testing & Verification

• How can this change be verified?
• What tests were added/modified?
• Manual testing steps (if applicable)

Trade-offs & Limitations

• What trade-offs were made?
• Known limitations
• Future considerations

Related Documentation

• Links to related docs in this repository
• Links to external documentation

### 4. Update Central Index

Update `docs/README.md` to include the new document in the **Recent Changes** table:

```markdown
## Recent Changes

| Date | Title | Category | Description |
|------|-------|----------|-------------|
| YYYY-MM-DD | [Title](./YYYY/MM/YYYY-MM-DD-slug.md) | Category | Brief description |

Also add to the appropriate Category section table.

5. Update Changelogs (If Applicable)

After creating the technical documentation, update the appropriate changelogs.

Before adding entries, check existing changelogs:

• Is this feature already mentioned in a recent entry?
• Could this be merged with an existing entry for clarity?
• Would updating an existing entry be better than creating a new one?

Customer Changelog (docs/Changelog.md)

If the change is user-notable (new feature, bug fix, or significant improvement visible to end-users), run /add-changelog or manually add:

- **YYYY-MM-DD** - Brief one-liner describing the feature or fix

Include: User-facing features, bug fixes, performance improvements, UI/UX changes Exclude: Internal refactoring, code cleanup, developer tooling, backend-only changes

Editing and Merging Entries

Changelogs are not append-only. When updating:

• Merge related changes — Multiple changes to the same feature can be combined into one entry
• Update recent entries — If a follow-up change relates to a recent entry, update rather than duplicate
• Consolidate for clarity — 2-5 consecutive small changes may read better as a single description

Mermaid Diagram Guidelines

Use Mermaid diagrams to illustrate:

• Flowcharts - Process flows, decision trees
• Sequence diagrams - Component interactions over time
• Class diagrams - Entity relationships
• ER diagrams - Database schemas
• State diagrams - State machines

Example Diagrams

Flowchart:

flowchart LR
    A[Input] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[Output]
    D --> E

Sequence Diagram:

sequenceDiagram
    participant U as User
    participant W as Web
    participant A as API
    U->>W: Request
    W->>A: Process
    A-->>W: Response
    W-->>U: Display

Entity Relationship:

erDiagram
    PARTY ||--o{ LEDGER_POSTING : has
    LEDGER_POSTING }o--|| CURRENCY : uses
    PARTY {
        int Id PK
        string Name
    }

Cross-Solution Documentation

When changes span multiple solutions or projects:

1. Create the primary document in the solution with the most changes
2. Create a brief reference document in the other solution linking to the primary
3. Update both indexes
4. Update Changelog in both if user-facing

Reference document template:

# <Title>

**Primary Documentation:** [Link to primary doc in other solution]

## Changes in This Solution

<Brief summary of changes specific to this solution>

## Files Modified

| File | Description |
|------|-------------|
| ... | ... |

Best Practices

1. Be Concise - Focus on the "why" not just the "what"
2. Use Diagrams - Visual aids improve comprehension
3. Link Related Docs - Build a connected knowledge base
4. Include Context - Future readers may not have your context
5. Document Trade-offs - Explain decisions and alternatives
6. Keep Index Current - The index is the entry point
7. Log Your Work - The Change Log section helps trace what was done
8. Update Changelog - Don't forget user-facing features/fixes

Example Execution

# After completing session log feature implementation:

1. Run: git status && git diff --stat
2. Read: docs/README.md (current state)
3. Create: docs/2026/01/2026-01-09-session-logging.md
4. Add content following template above (including Change Log table)
5. Update: docs/README.md index with new entry
6. Update: docs/Changelog.md if user-facing

Verification Checklist

Before completing documentation:

• Change document created with all sections filled
• Change Log table documents the implementation sequence
• Files Modified table is complete and accurate
• docs/README.md updated with new entry
• docs/Changelog.md updated (if user-facing) — consider merging with recent entries
• Cross-solution docs updated (if applicable)
• Diagrams render correctly
• All links work

Converted and distributed by TomeVault — claim your Tome and manage your conversions.