---
description: This is the basic workflow to gather last changes, prepare a relevant commit message and commit the staged code changes
---

This workflow guides the creation of a high-quality, comprehensive commit message that accurately reflects all staged changes, adhering strictly to the Conventional Commits 1.0 standard.

**1. Comprehensive Evidence Gathering (MANDATORY - Prevent tunnel vision):**

**1.1. Staged Changes Analysis:**

- **Detailed Diff Review:** Run `git diff --staged --stat` to get both summary and detailed view of all staged changes.
- **File-by-File Analysis:** Run `git diff --staged --name-status` to see the operation type (Modified, Added, Deleted) for each file.
- **Functional Area Classification:** Group staged files by functional area:
  - **API Changes:** `src/groovy/umig/api/`, `src/groovy/umig/repository/`
  - **UI Changes:** `src/groovy/umig/web/js/`, `src/groovy/umig/web/css/`, `src/groovy/umig/macros/`
  - **Documentation:** `docs/`, `README.md`, `CHANGELOG.md`, `*.md` files
  - **Tests:** `src/groovy/umig/tests/`, `local-dev-setup/__tests__/`
  - **Configuration:** `local-dev-setup/liquibase/`, `*.json`, `*.yml`, `*.properties`
  - **Database:** Migration files, schema changes
- **Change Type Analysis:** For each file, determine the type of change:
  - New functionality added
  - Existing functionality modified
  - Bug fixes
  - Refactoring or code cleanup
  - Documentation updates
  - Test additions or modifications

**1.2. Unstaged and Untracked Files Review:**

- **Related Files Check:** Run `git status --porcelain` to identify any untracked or unstaged files that might be related.
- **Completeness Verification:** Ensure all related changes are staged or deliberately excluded.
- **User Prompt:** If potentially related files are unstaged, prompt the user about inclusion.

**1.3. Work Stream Identification:**

- **Primary Work Stream:** Identify the main type of work being committed.
- **Secondary Work Streams:** Identify supporting changes (e.g., tests, documentation, configuration).
- **Cross-Functional Impact:** Note changes that span multiple functional areas.
- **Architecture Impact:** Identify any architectural or pattern changes.

**2. Multi-Context Rationale Analysis (MANDATORY - Address tunnel vision):**

**2.1. Session Context Review:**

- **Conversation Timeline:** Review the entire session conversation to understand the evolution of the work.
- **Initial Problem:** Identify the original problem or task that initiated the changes.
- **Decision Points:** Note key decisions made during the session that influenced the implementation.
- **Scope Evolution:** If the work expanded beyond the initial scope, understand how and why.

**2.2. Development Context:**

- **Dev Journal Review:** If a development journal entry was created during the session, review it for high-level narrative.
- **Related Work:** Check if this commit is part of a larger feature or bug fix spanning multiple commits.
- **Previous Commits:** Review recent commits to understand the progression of work.

**2.3. Business and Technical Context:**

- **Business Impact:** Understand what user-facing or system benefits this change provides.
- **Technical Motivation:** Identify the technical reasons for the changes (performance, maintainability, new features).
- **Problem-Solution Mapping:** For each work stream, clearly understand:
  - What problem was being solved
  - Why this particular solution was chosen
  - What alternatives were considered
  - What the outcome achieves

**2.4. Change Dependencies:**

- **Cross-Stream Dependencies:** How different work streams in this commit depend on each other.
- **External Dependencies:** Any external factors that influenced the changes.
- **Future Implications:** What this change enables or constrains for future development.

**3. Multi-Stream Commit Message Synthesis (MANDATORY - Address tunnel vision):**

The goal is to create a message that comprehensively explains all changes and their context for future developers.

**3.1. Type and Scope Selection:**

- **Primary Type:** Choose the most significant type from the allowed list (`feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`).
- **Multi-Stream Consideration:** If multiple significant work streams exist, choose the type that best represents the overall impact.
- **Scope Selection:** Identify the primary part of the codebase affected:
  - **Specific Components:** `api`, `ui`, `db`, `auth`, `docs`, `tests`
  - **Functional Areas:** `admin`, `migration`, `iteration`, `planning`
  - **System-Wide:** Use broader scopes for cross-cutting changes

**3.2. Subject Line Construction:**

- **Imperative Mood:** Write a concise summary (under 50 characters) in imperative mood.
- **Multi-Stream Subject:** If multiple work streams are significant, write a subject that captures the overall achievement.
- **Specific vs General:** Balance specificity with comprehensiveness.

**3.3. Body Structure (Enhanced for Multi-Stream):**

- **Primary Change Description:** Start with the main change and its motivation.
- **Work Stream Breakdown:** For each significant work stream:
  - **What Changed:** Specific files, components, or functionality
  - **Why Changed:** Problem being solved or improvement being made
  - **How Changed:** Technical approach or implementation details
  - **Impact:** What this enables or improves
- **Cross-Stream Integration:** How different work streams work together.
- **Technical Decisions:** Explain significant design choices and why alternatives were rejected.
- **Context:** Provide enough context for future developers to understand the change.

**3.4. Footer Considerations:**

- **Breaking Changes:** Use `BREAKING CHANGE:` for any breaking changes with migration notes.
- **Issue References:** Reference related issues (e.g., `Closes #123`, `Relates to #456`).
- **Co-authorship:** Add `Co-Authored-By:` for pair programming or AI assistance.

**3.5. Message Assembly:**

- **Single Coherent Story:** Weave multiple work streams into a single, coherent narrative.
- **Logical Flow:** Organize information in a logical sequence that makes sense to readers.
- **Appropriate Detail:** Include enough detail to understand the change without overwhelming.

**4. Anti-Tunnel Vision Verification (MANDATORY - Use before finalizing):**

Before presenting the commit message, verify you have addressed ALL of the following:

**Content Coverage:**

- [ ] All staged files are explained in the commit message
- [ ] All functional areas touched are documented
- [ ] All work streams are identified and described
- [ ] Change types (feat/fix/docs/etc.) are accurately represented
- [ ] Cross-functional impacts are noted

**Technical Completeness:**

- [ ] Code changes include rationale for the approach taken
- [ ] API changes are summarized with impact
- [ ] UI changes are explained with user impact
- [ ] Database changes include migration details
- [ ] Configuration changes are noted
- [ ] Test changes are explained

**Context and Rationale:**

- [ ] Original problem or motivation is clearly stated
- [ ] Solution approach is justified
- [ ] Technical decisions are explained
- [ ] Alternative approaches are noted (if relevant)
- [ ] Future implications are considered

**Message Quality:**

- [ ] Subject line is under 50 characters and imperative mood
- [ ] Body explains "what" and "why" for each work stream
- [ ] Information is organized in logical flow
- [ ] Appropriate level of detail for future developers
- [ ] Conventional Commits format is followed

**Completeness Verification:**

- [ ] All evidence from steps 1-2 is reflected in the message
- [ ] No significant work is missing from the description
- [ ] Multi-stream nature is properly represented
- [ ] Session context is appropriately captured

**5. Await Confirmation and Commit:**

- Present the generated commit message to the user for review.
- After receiving confirmation, execute the `git commit` command.
