--- description: At the end of each session, we look back at everything that was said and done, and we write down a Development Journal Entry --- The Developer Journal is a great way to keep track of our progress and document the way we made design decisions and coding breakthroughs. The task is to generate a new Developer Journal entry in the `docs/devJournal` folder, in markdown format, using the naming convention `yyyymmdd-nn.md`. The content of the entry must narrate the session's story. To ensure the full context is captured, you will follow these steps in order: **1. Establish the 'Why' (The High-Level Context):** - First, determine the active feature branch by running `git branch --show-current`. - Then, find and read the most recent previous journal entry to understand the starting point. - Synthesise these with the beginning of our current conversation to state the session's primary goal or the feature being worked on. **2. Gather Evidence of 'The How' (The Journey):** This step is critical to avoid "tunnel vision". You must perform a deep analysis of the entire session using multiple evidence sources. **2.1. Multi-Source Evidence Gathering (MANDATORY - All sources must be reviewed):** - **Conversation Chronology:** Create a timeline of the entire session from start to finish. Note every major topic, tool usage, file interaction, and decision point. - **Git Commit Analysis:** Run `git log --since="YYYY-MM-DD" --stat --oneline` to get a comprehensive view of all commits since the last journal entry. Each commit represents a separate work stream that must be captured. - **Staged Changes Analysis:** Run `git diff --staged --name-status` to see what's currently staged for commit (if anything). - **File System Impact:** Run `git status --porcelain` to see all modified, added, and untracked files. Group by functional area (API, UI, docs, tests, etc.). - **Documentation Trail:** Check for changes in: - `CHANGELOG.md` (often contains structured summaries of work) - `README.md` and other root-level documentation - `docs/` directory (API specs, ADRs, solution architecture) - `cline-docs/` (memory bank files) - Any workflow executions mentioned in conversation **2.2. Evidence Cross-Reference (MANDATORY - Prevent tunnel vision):** - **Workflow Execution Review:** If any workflows were mentioned in the conversation (e.g., `.clinerules/workflows/`), review their outputs and ensure their objectives are captured. - **API Development Pattern:** If API work was done, check for: - New/modified Groovy files in `src/groovy/umig/api/` - New/modified repository files in `src/groovy/umig/repository/` - Documentation updates in `docs/api/` - OpenAPI specification changes - Postman collection regeneration - **UI Development Pattern:** If UI work was done, check for: - JavaScript file changes in `src/groovy/umig/web/js/` - CSS changes in `src/groovy/umig/web/css/` - Macro changes in `src/groovy/umig/macros/` - Mock/prototype updates in `mock/` - **Refactoring Pattern:** If refactoring was done, check for: - File moves, renames, or splits - Architecture changes reflected in project structure - New patterns or modules introduced - Breaking changes or deprecations **2.3. Completeness Verification (MANDATORY - Final check):** - **Three-Pass Review:** 1. **First Pass:** What was the initial request/problem? 2. **Second Pass:** What were all the intermediate steps and discoveries? 3. **Third Pass:** What was the final state and all deliverables? - **Breadth vs Depth Check:** Ensure both technical depth (how things were implemented) and breadth (all areas touched) are captured. - **Hidden Work Detection:** Look for "invisible" work like: - Configuration changes - Dependency updates - Test file modifications - Documentation synchronization - Workflow or process improvements **3. Synthesise and Write the Narrative:** The goal is to write a detailed, insightful story, not a shallow summary. Prioritise depth and clarity over brevity. **3.1. Multi-Stream Integration (MANDATORY - Address tunnel vision):** - **Identify All Work Streams:** Based on evidence gathering, create a list of all distinct work streams (e.g., "API documentation", "Admin GUI refactoring", "Environment API implementation", "Schema consistency fixes"). - **Parallel vs Sequential Work:** Determine which work streams were parallel (done simultaneously) vs sequential (one led to another). - **Cross-Stream Dependencies:** Note how different work streams influenced each other (e.g., API documentation revealed schema issues that required code changes). - **Scope Creep Documentation:** If the session expanded beyond initial scope, document how and why this happened. **3.2. Narrative Structure (Enhanced):** - **Copy and Fill the Template:** For every new devJournal entry, always copy and fill in the persistent template at `docs/devJournal/devJournalEntryTemplate.md`. This ensures consistency, quality, and traceability across all devJournal entries. - **Multi-Problem Awareness:** If multiple problems were addressed, structure the narrative to handle multiple concurrent themes rather than forcing a single linear story. - **Enhanced Story Arc:** The "How" section should follow this comprehensive structure: 1. **The Initial Problem(s):** Clearly describe all bugs, errors, or tasks at the start of the session. Note if scope expanded. 2. **The Investigation:** Detail the debugging/analysis process for each work stream. What did we look at first? What were our initial hypotheses? What tools did we use? 3. **The Breakthrough(s):** Describe key insights or discoveries for each work stream. Note cross-stream insights. 4. **Implementation and Refinements:** Explain how solutions were implemented across all work streams. Detail code changes and architectural improvements. 5. **Validation and Documentation:** Describe how we confirmed fixes worked and updated documentation across all areas. - **Technical Depth Requirements:** For each work stream, ensure you capture: - **What changed** (files, code, configuration) - **Why it changed** (problem being solved, improvement being made) - **How it changed** (technical approach, patterns used) - **Impact** (what this enables, what problems it solves) **3.3. Quality Assurance (MANDATORY - Final verification):** - **Evidence vs Narrative Cross-Check:** Verify that every piece of evidence from step 2 has been addressed in the narrative. - **Completeness Audit:** Check that the journal entry would allow someone to understand: - The full scope of work accomplished - The technical decisions made and why - The current state of the project - What should be done next - **Tone and Format:** The tone should be in British English, and the format should be raw markdown. - **Final Review:** Before presenting the journal entry, re-read it one last time to ensure it captures the full journey and avoids the "tunnel vision" of only looking at the final code or the most recent work. **4. Anti-Tunnel Vision Checklist (MANDATORY - Use before finalizing):** Before presenting the journal entry, verify you have addressed ALL of the following: **Content Coverage:** - [ ] All git commits since last journal entry are documented - [ ] All workflow executions mentioned in conversation are captured - [ ] All file modifications (API, UI, docs, tests, config) are explained - [ ] All architectural or pattern changes are documented - [ ] All bug fixes and their root causes are explained - [ ] All new features and their implementation are detailed **Work Stream Integration:** - [ ] Multiple work streams are identified and explained - [ ] Parallel vs sequential work is clearly distinguished - [ ] Cross-dependencies between work streams are noted - [ ] Scope expansions are documented with reasoning **Technical Depth:** - [ ] Code changes include the "what", "why", "how", and "impact" - [ ] Database schema changes are documented - [ ] API changes include request/response examples - [ ] UI changes include user experience impact - [ ] Documentation changes and their necessity are explained **Project Context:** - [ ] Current project state is accurately reflected - [ ] Next steps and priorities are updated - [ ] Key learnings and patterns are documented - [ ] Project milestone significance is noted **Quality Verification:** - [ ] Evidence from step 2 matches narrative content - [ ] No significant work is missing from the story - [ ] Technical decisions are justified and explained - [ ] Future developers could understand the session's impact **5. Await Confirmation:** - After presenting the generated journal entry, **DO NOT** proceed with any other actions, especially committing. - Wait for explicit confirmation or further instructions from the user.