Skip to content

AI Guide: Creating Development Log Entries

Overview

This SOP provides instructions for AI assistants on how to properly create and maintain development log entries in the AIC Holdings data science documentation system.

When to Create Log Entries

Create a new development log entry when: - Significant development work has been completed - Multiple commits have been made in a day - New features, systems, or major changes have been implemented - At the end of a substantial work session

File Structure

Development logs are stored in: 

apps/Docs/docs/log/YYYY-MM-DD.md

Step-by-Step Process

1. Create the Log File

Create a new markdown file with the current date: 

# Example for August 21, 2025
/Users/dshanklinbv/repos/data-science/apps/Docs/docs/log/2025-08-21.md

2. Use the Standard Template

# Development Log - [Month DD, YYYY]

## Summary

Brief one-line summary of total scope of work.

## Changes Made

### [Category Name]
**Commit**: [`commit-hash`](https://github.com/aic-holdings/data-science/commit/commit-hash) - Brief commit description

- Bullet point describing what was done
- Another bullet point for additional changes
- Keep descriptions factual and concise

### [Another Category]
**Current Session** - Description for uncommitted work

- Changes made during current work session
- Features added or modified
- System improvements

3. Content Guidelines

Categories: Group related work under logical sections: - Repository Reorganization - Feature Development - Documentation Updates - System Enhancements - Bug Fixes - Performance Improvements

Commit References: Include commit hashes as clickable links when available: - Link to GitHub commits: [9aa1f93](https://github.com/aic-holdings/data-science/commit/9aa1f93) - Include brief commit message after hash - Format: [hash](https://github.com/aic-holdings/data-science/commit/hash) - Brief commit description

Bullet Points: Keep descriptions factual and concise: - ✅ "Added MkDocs Material setup with navigation features" - ❌ "Implemented a comprehensive and beautiful documentation system that will revolutionize our workflow"

Avoid: Strategic analysis, future planning, or editorial commentary

4. Update Navigation

Add the new log entry to two places:

A. Update the log index (docs/log/index.md): 

## Recent Entries

- **[YYYY-MM-DD](YYYY-MM-DD.md)** - Brief description of day's work

B. Update log directory pages (docs/log/.pages): 

nav:
    - August 2025:
        - 2025-08-21.md
        - YYYY-MM-DD.md  # Add new entries here

Note: The awesome-pages plugin automatically handles navigation. No need to update mkdocs.yml for individual log entries.

5. File Naming Convention

  • Use ISO date format: YYYY-MM-DD.md
  • Example: 2025-08-21.md
  • Ensure consistency across all references

Example Implementation

See the existing log entry at docs/log/2025-08-21.md for a complete example following these guidelines.

Quality Checklist

Before completing a log entry, verify:

  • File named with correct ISO date format
  • Template structure followed
  • Commit hashes included where available
  • Descriptions are factual, not analytical
  • Navigation updated in both log/index.md and log/.pages
  • No strategic commentary or future planning
  • Bullet points are concise and specific