152 lines
8.6 KiB
Markdown
152 lines
8.6 KiB
Markdown
---
|
|
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.
|