gac 1.13.0__py3-none-any.whl → 3.8.1__py3-none-any.whl

gac/prompt.py

@@ -8,10 +8,16 @@ formatting, and integration with diff preprocessing.
 import logging
 import re
 
+from gac.constants import CommitMessageConstants
+
 logger = logging.getLogger(__name__)
 
-# Default template to use when no template file is found
-DEFAULT_TEMPLATE = """<role>
+
+# ============================================================================
+# Prompt Templates
+# ============================================================================
+
+DEFAULT_SYSTEM_TEMPLATE = """<role>
 You are an expert git commit message generator. Your task is to analyze code changes and create a concise, meaningful git commit message. You will receive git status and diff information. Your entire response will be used directly as a git commit message.
 </role>
 
@@ -33,12 +39,12 @@ When changes span multiple areas:
 
 <format>
   <one_liner>
-  Create a single-line commit message (50-72 characters if possible).
+  Create a single-line commit message.
   Your message should be clear, concise, and descriptive of the core change.
   Use present tense ("Add feature" not "Added feature").
   </one_liner><multi_line>
   Create a commit message with:
-  - First line: A concise summary (50-72 characters) that could stand alone
+  - First line: A concise summary that could stand alone
   - Blank line after the summary
   - Detailed body with multiple bullet points explaining the key changes
   - Focus on WHY changes were made, not just WHAT was changed
@@ -49,7 +55,7 @@ When changes span multiple areas:
 
   Your commit message MUST follow this structure:
 
-  Line 1: A concise summary (up to ~72 characters) with conventional commit prefix
+  Line 1: A concise summary (that could stand alone) with conventional commit prefix
   Line 2: BLANK LINE (required)
   Lines 3+: Detailed multi-paragraph body with the following sections:
 
@@ -158,24 +164,6 @@ INCORRECT EXAMPLES (these formats are wrong and must NOT be used):
 You MUST NOT prefix the type(scope) with another type. Use EXACTLY ONE type, which MUST include the scope in parentheses.
 </conventions_with_scope>
 
-<hint>
-Additional context provided by the user: <hint_text></hint_text>
-</hint>
-
-<git_status>
-<status></status>
-</git_status>
-
-<git_diff_stat>
-<diff_stat></diff_stat>
-</git_diff_stat>
-
-<git_diff>
-<diff></diff>
-</git_diff>
-
-
-
 <examples_no_scope>
 Good commit messages (no scope):
 [OK] feat: add OAuth2 integration with Google and GitHub
@@ -252,297 +240,656 @@ Bad commit messages:
 [ERROR] WIP: still working on this
 [ERROR] Fixed bug
 [ERROR] Changes
-</examples_with_scope>
+</examples_with_scope>"""
+
+DEFAULT_USER_TEMPLATE = """<hint>
+Additional context provided by the user: <hint_text></hint_text>
+</hint>
+
+<git_diff>
+<diff></diff>
+</git_diff>
+
+<git_diff_stat>
+<diff_stat></diff_stat>
+</git_diff_stat>
 
-<instructions>
+<git_status>
+<status></status>
+</git_status>
+
+<language_instructions>
+IMPORTANT: You MUST write the entire commit message in <language_name></language_name>.
+All text in the commit message, including the summary line and body, must be in <language_name></language_name>.
+<prefix_instruction></prefix_instruction>
+</language_instructions>
+
+<format_instructions>
 IMMEDIATELY AFTER ANALYZING THE CHANGES, RESPOND WITH ONLY THE COMMIT MESSAGE.
 DO NOT include any preamble, reasoning, explanations or anything other than the commit message itself.
 DO NOT use markdown formatting, headers, or code blocks.
 The entire response will be passed directly to 'git commit -m'.
-</instructions>"""
+</format_instructions>"""
+
+QUESTION_GENERATION_TEMPLATE = """<role>
+You are an expert code reviewer specializing in identifying missing context and intent in code changes. Your task is to analyze git diffs and generate focused questions that clarify the "why" behind the changes.
+</role>
+
+<focus>
+Analyze the git diff and determine the appropriate number of questions based on change complexity. Generate 1-5 focused questions to clarify intent, motivation, and impact. Your questions should help the developer provide the essential context needed for a meaningful commit message.
+</focus>
 
+<adaptive_guidelines>
+- For very small changes (single file, <10 lines): Ask 1-2 essential questions about core purpose
+- For small changes (few files, <50 lines): Ask 1-3 questions covering intent and impact
+- For medium changes (multiple files, <200 lines): Ask 2-4 questions covering scope, intent, and impact
+- For large changes (many files or substantial modifications): Ask 3-5 questions covering all aspects
+- Always prioritize questions that would most help generate an informative commit message
+- Lean toward fewer questions for straightforward changes
+</adaptive_guidelines>
+
+<guidelines>
+- Focus on WHY the changes were made, not just WHAT was changed
+- Ask about the intent, motivation, or business purpose behind the changes
+- Consider what future developers need to understand about this change
+- Ask about the broader impact or consequences of the changes
+- Target areas where technical implementation doesn't reveal the underlying purpose
+- Keep questions concise and specific
+- Format as a clean list for easy parsing
+</guidelines>
+
+<rules>
+NEVER write or rewrite the commit message; only ask questions.
+DO NOT suggest specific commit message formats or wording.
+DO NOT ask about implementation details that are already clear from the diff.
+DO NOT include any explanations or preamble with your response.
+</rules>
+
+<output_format>
+Respond with ONLY a numbered list of questions, one per line:
+1. First focused question?
+2. Second focused question?
+3. Third focused question?
+4. [etc...]
+</output_format>
+
+<examples>
+Good example questions for small changes:
+1. What problem does this fix?
+2. Why was this approach chosen?
+
+Good example questions for larger changes:
+1. What problem or user need does this change address?
+2. Why was this particular approach chosen over alternatives?
+3. What impact will this have on existing functionality?
+4. What motivated the addition of these new error cases?
+5. Why are these validation rules being added now?
+
+Bad examples (violates rules):
+❌ feat: add user authentication - This is a commit message, not a question
+❌ Should I use "feat" or "fix" for this change? - This asks about formatting, not context
+❌ Why did you rename the variable from x to y? - Too implementation-specific
+❌ You should reformat this as "fix: resolve authentication issue" - This rewrites the message
+</examples>"""
+
+
+# ============================================================================
+# Template Loading
+# ============================================================================
+
+
+def load_system_template(custom_path: str | None = None) -> str:
+    """Load the system prompt template.
 
-def load_prompt_template() -> str:
-    """Load the prompt template from the embedded default template.
+    Args:
+        custom_path: Optional path to a custom system template file
 
     Returns:
-        Template content as string
+        System template content as string
     """
-    logger.debug("Using default template")
-    return DEFAULT_TEMPLATE
+    if custom_path:
+        return load_custom_system_template(custom_path)
 
+    logger.debug("Using default system template")
+    return DEFAULT_SYSTEM_TEMPLATE
 
-def build_prompt(
-    status: str,
-    processed_diff: str,
-    diff_stat: str = "",
-    one_liner: bool = False,
-    infer_scope: bool = False,
-    hint: str = "",
-    verbose: bool = False,
-) -> tuple[str, str]:
-    """Build system and user prompts for the AI model using the provided template and git information.
+
+def load_user_template() -> str:
+    """Load the user prompt template (contains git data sections and instructions).
+
+    Returns:
+        User template content as string
+    """
+    logger.debug("Using default user template")
+    return DEFAULT_USER_TEMPLATE
+
+
+def load_custom_system_template(path: str) -> str:
+    """Load a custom system template from a file.
 
     Args:
-        status: Git status output
-        processed_diff: Git diff output, already preprocessed and ready to use
-        diff_stat: Git diff stat output showing file changes summary
-        one_liner: Whether to request a one-line commit message
-        infer_scope: Whether to infer scope for the commit message
-        hint: Optional hint to guide the AI
-        verbose: Whether to generate detailed commit messages with motivation, architecture, and impact sections
+        path: Path to the custom system template file
 
     Returns:
-        Tuple of (system_prompt, user_prompt) ready to be sent to an AI model
+        Custom system template content
+
+    Raises:
+        FileNotFoundError: If the template file doesn't exist
+        IOError: If there's an error reading the file
+    """
+    try:
+        with open(path, encoding="utf-8") as f:
+            content = f.read()
+            logger.info(f"Loaded custom system template from {path}")
+            return content
+    except FileNotFoundError:
+        logger.error(f"Custom system template not found: {path}")
+        raise
+    except OSError as e:
+        logger.error(f"Error reading custom system template from {path}: {e}")
+        raise
+
+
+# ============================================================================
+# Template Processing Helpers
+# ============================================================================
+
+
+def _remove_template_section(template: str, section_name: str) -> str:
+    """Remove a tagged section from the template.
+
+    Args:
+        template: The template string
+        section_name: Name of the section to remove (without < > brackets)
+
+    Returns:
+        Template with the section removed
     """
-    template = load_prompt_template()
+    pattern = f"<{section_name}>.*?</{section_name}>\\n?"
+    return re.sub(pattern, "", template, flags=re.DOTALL)
+
 
-    # Select the appropriate conventions section based on infer_scope parameter
+def _select_conventions_section(template: str, infer_scope: bool) -> str:
+    """Select and normalize the appropriate conventions section.
+
+    Args:
+        template: The template string
+        infer_scope: Whether to infer scope for commits
+
+    Returns:
+        Template with the appropriate conventions section selected
+    """
     try:
         logger.debug(f"Processing infer_scope parameter: {infer_scope}")
         if infer_scope:
-            # User wants to infer a scope from changes (any value other than None)
             logger.debug("Using inferred-scope conventions")
-            template = re.sub(r"<conventions_no_scope>.*?</conventions_no_scope>\n", "", template, flags=re.DOTALL)
+            template = _remove_template_section(template, "conventions_no_scope")
             template = template.replace("<conventions_with_scope>", "<conventions>")
             template = template.replace("</conventions_with_scope>", "</conventions>")
         else:
-            # No scope - use the plain conventions section
             logger.debug("Using no-scope conventions")
-            template = re.sub(r"<conventions_with_scope>.*?</conventions_with_scope>\n", "", template, flags=re.DOTALL)
+            template = _remove_template_section(template, "conventions_with_scope")
             template = template.replace("<conventions_no_scope>", "<conventions>")
             template = template.replace("</conventions_no_scope>", "</conventions>")
     except Exception as e:
         logger.error(f"Error processing scope parameter: {e}")
-        # Fallback to no scope if there's an error
-        template = re.sub(r"<conventions_with_scope>.*?</conventions_with_scope>\n", "", template, flags=re.DOTALL)
+        template = _remove_template_section(template, "conventions_with_scope")
         template = template.replace("<conventions_no_scope>", "<conventions>")
         template = template.replace("</conventions_no_scope>", "</conventions>")
+    return template
 
-    template = template.replace("<status></status>", status)
-    template = template.replace("<diff_stat></diff_stat>", diff_stat)
-    template = template.replace("<diff></diff>", processed_diff)
 
-    # Add hint if present
-    if hint:
-        template = template.replace("<hint_text></hint_text>", hint)
-        logger.debug(f"Added hint ({len(hint)} characters)")
-    else:
-        template = re.sub(r"<hint>.*?</hint>", "", template, flags=re.DOTALL)
-        logger.debug("No hint provided")
+def _select_format_section(template: str, verbose: bool, one_liner: bool) -> str:
+    """Select the appropriate format section based on verbosity and one-liner settings.
+
+    Priority: verbose > one_liner > multi_line
+
+    Args:
+        template: The template string
+        verbose: Whether to use verbose format
+        one_liner: Whether to use one-liner format
 
-    # Process format options (verbose, one-liner, or multi-line)
-    # Priority: verbose > one_liner > multi_line
+    Returns:
+        Template with the appropriate format section selected
+    """
     if verbose:
-        # Verbose mode: remove one_liner and multi_line, keep verbose
-        template = re.sub(r"<one_liner>.*?</one_liner>", "", template, flags=re.DOTALL)
-        template = re.sub(r"<multi_line>.*?</multi_line>", "", template, flags=re.DOTALL)
+        template = _remove_template_section(template, "one_liner")
+        template = _remove_template_section(template, "multi_line")
     elif one_liner:
-        # One-liner mode: remove multi_line and verbose
-        template = re.sub(r"<multi_line>.*?</multi_line>", "", template, flags=re.DOTALL)
-        template = re.sub(r"<verbose>.*?</verbose>", "", template, flags=re.DOTALL)
+        template = _remove_template_section(template, "multi_line")
+        template = _remove_template_section(template, "verbose")
     else:
-        # Multi-line mode (default): remove one_liner and verbose
-        template = re.sub(r"<one_liner>.*?</one_liner>", "", template, flags=re.DOTALL)
-        template = re.sub(r"<verbose>.*?</verbose>", "", template, flags=re.DOTALL)
+        template = _remove_template_section(template, "one_liner")
+        template = _remove_template_section(template, "verbose")
+    return template
+
+
+def _select_examples_section(template: str, verbose: bool, infer_scope: bool) -> str:
+    """Select the appropriate examples section based on verbosity and scope settings.
 
-    # Clean up examples sections based on verbose and infer_scope settings
+    Args:
+        template: The template string
+        verbose: Whether verbose mode is enabled
+        infer_scope: Whether scope inference is enabled
+
+    Returns:
+        Template with the appropriate examples section selected
+    """
     if verbose and infer_scope:
-        # Verbose mode with scope - keep verbose_with_scope examples
-        template = re.sub(r"<examples_no_scope>.*?</examples_no_scope>\n?", "", template, flags=re.DOTALL)
-        template = re.sub(r"<examples_with_scope>.*?</examples_with_scope>\n?", "", template, flags=re.DOTALL)
-        template = re.sub(
-            r"<examples_verbose_no_scope>.*?</examples_verbose_no_scope>\n?", "", template, flags=re.DOTALL
-        )
+        template = _remove_template_section(template, "examples_no_scope")
+        template = _remove_template_section(template, "examples_with_scope")
+        template = _remove_template_section(template, "examples_verbose_no_scope")
         template = template.replace("<examples_verbose_with_scope>", "<examples>")
         template = template.replace("</examples_verbose_with_scope>", "</examples>")
     elif verbose:
-        # Verbose mode without scope - keep verbose_no_scope examples
-        template = re.sub(r"<examples_no_scope>.*?</examples_no_scope>\n?", "", template, flags=re.DOTALL)
-        template = re.sub(r"<examples_with_scope>.*?</examples_with_scope>\n?", "", template, flags=re.DOTALL)
-        template = re.sub(
-            r"<examples_verbose_with_scope>.*?</examples_verbose_with_scope>\n?", "", template, flags=re.DOTALL
-        )
+        template = _remove_template_section(template, "examples_no_scope")
+        template = _remove_template_section(template, "examples_with_scope")
+        template = _remove_template_section(template, "examples_verbose_with_scope")
         template = template.replace("<examples_verbose_no_scope>", "<examples>")
         template = template.replace("</examples_verbose_no_scope>", "</examples>")
     elif infer_scope:
-        # With scope (inferred) - keep scope examples, remove all others
-        template = re.sub(r"<examples_no_scope>.*?</examples_no_scope>\n?", "", template, flags=re.DOTALL)
-        template = re.sub(
-            r"<examples_verbose_no_scope>.*?</examples_verbose_no_scope>\n?", "", template, flags=re.DOTALL
-        )
-        template = re.sub(
-            r"<examples_verbose_with_scope>.*?</examples_verbose_with_scope>\n?", "", template, flags=re.DOTALL
-        )
+        template = _remove_template_section(template, "examples_no_scope")
+        template = _remove_template_section(template, "examples_verbose_no_scope")
+        template = _remove_template_section(template, "examples_verbose_with_scope")
         template = template.replace("<examples_with_scope>", "<examples>")
         template = template.replace("</examples_with_scope>", "</examples>")
     else:
-        # No scope - keep no_scope examples, remove all others
-        template = re.sub(r"<examples_with_scope>.*?</examples_with_scope>\n?", "", template, flags=re.DOTALL)
-        template = re.sub(
-            r"<examples_verbose_no_scope>.*?</examples_verbose_no_scope>\n?", "", template, flags=re.DOTALL
-        )
-        template = re.sub(
-            r"<examples_verbose_with_scope>.*?</examples_verbose_with_scope>\n?", "", template, flags=re.DOTALL
-        )
+        template = _remove_template_section(template, "examples_with_scope")
+        template = _remove_template_section(template, "examples_verbose_no_scope")
+        template = _remove_template_section(template, "examples_verbose_with_scope")
         template = template.replace("<examples_no_scope>", "<examples>")
         template = template.replace("</examples_no_scope>", "</examples>")
+    return template
+
+
+# ============================================================================
+# Prompt Building
+# ============================================================================
+
+
+def build_prompt(
+    status: str,
+    processed_diff: str,
+    diff_stat: str = "",
+    one_liner: bool = False,
+    infer_scope: bool = False,
+    hint: str = "",
+    verbose: bool = False,
+    system_template_path: str | None = None,
+    language: str | None = None,
+    translate_prefixes: bool = False,
+) -> tuple[str, str]:
+    """Build system and user prompts for the AI model using the provided templates and git information.
+
+    Args:
+        status: Git status output
+        processed_diff: Git diff output, already preprocessed and ready to use
+        diff_stat: Git diff stat output showing file changes summary
+        one_liner: Whether to request a one-line commit message
+        infer_scope: Whether to infer scope for the commit message
+        hint: Optional hint to guide the AI
+        verbose: Whether to generate detailed commit messages with motivation, architecture, and impact sections
+        system_template_path: Optional path to custom system template
+        language: Optional language for commit messages (e.g., "Spanish", "French", "Japanese")
+        translate_prefixes: Whether to translate conventional commit prefixes (default: False keeps them in English)
+
+    Returns:
+        Tuple of (system_prompt, user_prompt) ready to be sent to an AI model
+    """
+    system_template = load_system_template(system_template_path)
+    user_template = load_user_template()
 
-    # Clean up extra whitespace, collapsing blank lines that may contain spaces
-    template = re.sub(r"\n(?:[ \t]*\n){2,}", "\n\n", template)
-
-    # Split the template into system and user prompts
-    # System prompt contains all instructions, role, conventions, examples
-    # User prompt contains the actual git data
-
-    # Extract the git data sections for the user prompt
-    user_sections = []
-
-    # Extract git status
-    status_match = re.search(r"<git_status>.*?</git_status>", template, re.DOTALL)
-    if status_match:
-        user_sections.append(status_match.group(0))
-        # Remove from system prompt
-        template = template.replace(status_match.group(0), "")
-
-    # Extract git diff stat
-    diff_stat_match = re.search(r"<git_diff_stat>.*?</git_diff_stat>", template, re.DOTALL)
-    if diff_stat_match:
-        user_sections.append(diff_stat_match.group(0))
-        # Remove from system prompt
-        template = template.replace(diff_stat_match.group(0), "")
-
-    # Extract git diff
-    diff_match = re.search(r"<git_diff>.*?</git_diff>", template, re.DOTALL)
-    if diff_match:
-        user_sections.append(diff_match.group(0))
-        # Remove from system prompt
-        template = template.replace(diff_match.group(0), "")
-
-    # Extract hint if present
-    hint_match = re.search(r"<hint>.*?</hint>", template, re.DOTALL)
-    if hint_match and hint:  # Only include if hint was provided
-        user_sections.append(hint_match.group(0))
-        # Remove from system prompt
-        template = template.replace(hint_match.group(0), "")
-
-    # System prompt is everything else (role, conventions, examples, instructions)
-    system_prompt = template.strip()
-    system_prompt = re.sub(r"\n(?:[ \t]*\n){2,}", "\n\n", system_prompt)
-
-    # User prompt is the git data sections
-    user_prompt = "\n\n".join(user_sections).strip()
+    system_template = _select_conventions_section(system_template, infer_scope)
+    system_template = _select_format_section(system_template, verbose, one_liner)
+    system_template = _select_examples_section(system_template, verbose, infer_scope)
+    system_template = re.sub(r"\n(?:[ \t]*\n){2,}", "\n\n", system_template)
+
+    user_template = user_template.replace("<status></status>", status)
+    user_template = user_template.replace("<diff_stat></diff_stat>", diff_stat)
+    user_template = user_template.replace("<diff></diff>", processed_diff)
+
+    if hint:
+        user_template = user_template.replace("<hint_text></hint_text>", hint)
+        logger.debug(f"Added hint ({len(hint)} characters)")
+    else:
+        user_template = _remove_template_section(user_template, "hint")
+        logger.debug("No hint provided")
+
+    if language:
+        user_template = user_template.replace("<language_name></language_name>", language)
+
+        # Set prefix instruction based on translate_prefixes setting
+        if translate_prefixes:
+            prefix_instruction = f"""CRITICAL: You MUST translate the conventional commit prefix into {language}.
+DO NOT use English prefixes like 'feat:', 'fix:', 'docs:', etc.
+Instead, translate them into {language} equivalents.
+Examples:
+- 'feat:' → translate to {language} word for 'feature' or 'add'
+- 'fix:' → translate to {language} word for 'fix' or 'correct'
+- 'docs:' → translate to {language} word for 'documentation'
+The ENTIRE commit message, including the prefix, must be in {language}."""
+            logger.debug(f"Set commit message language to: {language} (with prefix translation)")
+        else:
+            prefix_instruction = (
+                "The conventional commit prefix (feat:, fix:, etc.) should remain in English, but everything after the prefix must be in "
+                + language
+                + "."
+            )
+            logger.debug(f"Set commit message language to: {language} (English prefixes)")
+
+        user_template = user_template.replace("<prefix_instruction></prefix_instruction>", prefix_instruction)
+    else:
+        user_template = _remove_template_section(user_template, "language_instructions")
+        logger.debug("Using default language (English)")
+
+    user_template = re.sub(r"\n(?:[ \t]*\n){2,}", "\n\n", user_template)
+
+    return system_template.strip(), user_template.strip()
+
+
+def build_group_prompt(
+    status: str,
+    processed_diff: str,
+    diff_stat: str,
+    one_liner: bool,
+    hint: str,
+    infer_scope: bool,
+    verbose: bool,
+    system_template_path: str | None,
+    language: str | None,
+    translate_prefixes: bool,
+) -> tuple[str, str]:
+    """Build prompt for grouped commit generation (JSON output with multiple commits)."""
+    system_prompt, user_prompt = build_prompt(
+        status=status,
+        processed_diff=processed_diff,
+        diff_stat=diff_stat,
+        one_liner=one_liner,
+        hint=hint,
+        infer_scope=infer_scope,
+        verbose=verbose,
+        system_template_path=system_template_path,
+        language=language,
+        translate_prefixes=translate_prefixes,
+    )
+
+    user_prompt = _remove_template_section(user_prompt, "format_instructions")
+
+    grouping_instructions = """
+<format_instructions>
+Your task is to split the changed files into separate, logical commits. Think of this like sorting files into different folders where each file belongs in exactly one folder.
+
+CRITICAL REQUIREMENT - Every File Used Exactly Once:
+You must assign EVERY file from the diff to exactly ONE commit.
+- NO file should be left out
+- NO file should appear in multiple commits
+- EVERY file must be used once and ONLY once
+
+Think of it like dealing cards: Once you've dealt a card to a player, that card cannot be dealt to another player.
+
+HOW TO SPLIT THE FILES:
+1. Review all changed files in the diff
+2. Group files by logical relationship (e.g., related features, bug fixes, documentation)
+3. Assign each file to exactly one commit based on what makes the most sense
+4. If a file could fit in multiple commits, pick the best fit and move on - do NOT duplicate it
+5. Continue until every single file has been assigned to a commit
+
+ORDERING:
+Order the commits in a logical sequence considering dependencies, natural progression, and overall workflow.
+
+YOUR RESPONSE FORMAT:
+Respond with valid JSON following this structure:
+```json
+{
+  "commits": [
+    {
+      "files": ["src/auth/login.ts", "src/auth/logout.ts"],
+      "message": "<commit_message_conforming_to_prescribed_structure_and_format>"
+    },
+    {
+      "files": ["src/db/schema.sql", "src/db/migrations/001.sql"],
+      "message": "<commit_message_conforming_to_prescribed_structure_and_format>"
+    },
+    {
+      "files": ["tests/auth.test.ts", "tests/db.test.ts", "README.md"],
+      "message": "<commit_message_conforming_to_prescribed_structure_and_format>"
+    }
+  ]
+}
+```
+
+☝️ Notice how EVERY file path in the example above appears exactly ONCE across all commits. "src/auth/login.ts" appears once. "tests/auth.test.ts" appears once. No file is repeated.
+
+VALIDATION CHECKLIST - Before responding, verify:
+□ Total files across all commits = Total files in the diff
+□ Each file appears in exactly 1 commit (no duplicates, no omissions)
+□ Every commit has at least one file
+□ If you list all files from all commits and count them, you get the same count as unique files in the diff
+</format_instructions>
+"""
+
+    user_prompt = user_prompt + grouping_instructions
 
     return system_prompt, user_prompt
 
 
-def clean_commit_message(message: str) -> str:
-    """Clean up a commit message generated by an AI model.
+def build_question_generation_prompt(
+    status: str,
+    processed_diff: str,
+    diff_stat: str = "",
+    hint: str = "",
+) -> tuple[str, str]:
+    """Build system and user prompts for question generation about staged changes.
 
-    This function:
-    1. Removes any preamble or reasoning text
-    2. Removes code block markers and formatting
-    3. Removes XML tags that might have leaked into the response
-    4. Ensures the message starts with a conventional commit prefix
-    5. Fixes double type prefix issues (e.g., "chore: feat(scope):")
+    Args:
+        status: Git status output
+        processed_diff: Git diff output, already preprocessed and ready to use
+        diff_stat: Git diff stat output showing file changes summary
+        hint: Optional hint to guide the question generation
+
+    Returns:
+        Tuple of (system_prompt, user_prompt) ready to be sent to an AI model
+    """
+    system_prompt = QUESTION_GENERATION_TEMPLATE
+
+    # Build user prompt with git context
+    user_prompt = f"""<git_diff>
+{processed_diff}
+</git_diff>
+
+<git_diff_stat>
+{diff_stat}
+</git_diff_stat>
+
+<git_status>
+{status}
+</git_status>"""
+
+    if hint:
+        user_prompt = f"""<hint>
+Additional context provided by the user: {hint}
+</hint>
+
+{user_prompt}"""
+
+    # Add instruction to ask questions in the appropriate language if specified
+    user_prompt += """
+
+<format_instructions>
+Analyze the changes above and determine the appropriate number of questions based on the change complexity. Generate 1-5 focused questions that clarify the intent, motivation, and impact of these changes. For very small changes, ask only 1-2 essential questions. Respond with ONLY a numbered list of questions as specified in the system prompt.
+</format_instructions>"""
+
+    return system_prompt.strip(), user_prompt.strip()
+
+
+# ============================================================================
+# Message Cleaning Helpers
+# ============================================================================
+
+
+def _remove_think_tags(message: str) -> str:
+    """Remove AI reasoning <think> tags and their content from the message.
 
     Args:
-        message: Raw commit message from AI
+        message: The message to clean
 
     Returns:
-        Cleaned commit message ready for use
+        Message with <think> tags removed
     """
-    message = message.strip()
+    while re.search(r"<think>(?:(?!</think>)[^\n])*\n.*?</think>", message, flags=re.DOTALL | re.IGNORECASE):
+        message = re.sub(
+            r"<think>(?:(?!</think>)[^\n])*\n.*?</think>\s*", "", message, flags=re.DOTALL | re.IGNORECASE, count=1
+        )
+
+    message = re.sub(r"\n\n+\s*<think>.*?</think>\s*", "", message, flags=re.DOTALL | re.IGNORECASE)
+    message = re.sub(r"<think>.*?</think>\s*\n\n+", "", message, flags=re.DOTALL | re.IGNORECASE)
+
+    message = re.sub(r"<think>\s*\n.*$", "", message, flags=re.DOTALL | re.IGNORECASE)
+
+    conventional_prefixes_pattern = r"(" + "|".join(CommitMessageConstants.CONVENTIONAL_PREFIXES) + r")[\(:)]"
+    if re.search(r"^.*?</think>", message, flags=re.DOTALL | re.IGNORECASE):
+        prefix_match = re.search(conventional_prefixes_pattern, message, flags=re.IGNORECASE)
+        think_match = re.search(r"</think>", message, flags=re.IGNORECASE)
+
+        if not prefix_match or (think_match and think_match.start() < prefix_match.start()):
+            message = re.sub(r"^.*?</think>\s*", "", message, flags=re.DOTALL | re.IGNORECASE)
 
-    # Remove any markdown code blocks
-    message = re.sub(r"```[\w]*\n|```", "", message)
-
-    # Extract the actual commit message if it follows our reasoning pattern
-    # Look for different indicators of where the actual commit message starts
-    commit_indicators = [
-        "# Your commit message:",
-        "Your commit message:",
-        "The commit message is:",
-        "Here's the commit message:",
-        "Commit message:",
-        "Final commit message:",
-        "# Commit Message",
-    ]
-
-    for indicator in commit_indicators:
+    message = re.sub(r"</think>\s*$", "", message, flags=re.IGNORECASE)
+
+    return message
+
+
+def _remove_code_blocks(message: str) -> str:
+    """Remove markdown code blocks from the message.
+
+    Args:
+        message: The message to clean
+
+    Returns:
+        Message with code blocks removed
+    """
+    return re.sub(r"```[\w]*\n|```", "", message)
+
+
+def _extract_commit_from_reasoning(message: str) -> str:
+    """Extract the actual commit message from reasoning/preamble text.
+
+    Args:
+        message: The message potentially containing reasoning
+
+    Returns:
+        Extracted commit message
+    """
+    for indicator in CommitMessageConstants.COMMIT_INDICATORS:
         if indicator.lower() in message.lower():
-            # Extract everything after the indicator
             message = message.split(indicator, 1)[1].strip()
             break
 
-    # If message starts with any kind of explanation text, try to locate a conventional prefix
     lines = message.split("\n")
     for i, line in enumerate(lines):
-        if any(
-            line.strip().startswith(prefix)
-            for prefix in ["feat:", "fix:", "docs:", "style:", "refactor:", "perf:", "test:", "build:", "ci:", "chore:"]
-        ):
+        if any(line.strip().startswith(f"{prefix}:") for prefix in CommitMessageConstants.CONVENTIONAL_PREFIXES):
             message = "\n".join(lines[i:])
             break
 
-    # Remove any XML tags that might have leaked into the response
-    for tag in [
-        "<git-status>",
-        "</git-status>",
-        "<git_status>",
-        "</git_status>",
-        "<git-diff>",
-        "</git-diff>",
-        "<git_diff>",
-        "</git_diff>",
-        "<repository_context>",
-        "</repository_context>",
-        "<instructions>",
-        "</instructions>",
-        "<format>",
-        "</format>",
-        "<conventions>",
-        "</conventions>",
-    ]:
+    return message
+
+
+def _remove_xml_tags(message: str) -> str:
+    """Remove XML tags that might have leaked into the message.
+
+    Args:
+        message: The message to clean
+
+    Returns:
+        Message with XML tags removed
+    """
+    for tag in CommitMessageConstants.XML_TAGS_TO_REMOVE:
         message = message.replace(tag, "")
+    return message
+
+
+def _fix_double_prefix(message: str) -> str:
+    """Fix double type prefix issues like 'chore: feat(scope):' to 'feat(scope):'.
+
+    Args:
+        message: The message to fix
 
-    # Fix double type prefix issues (e.g., "chore: feat(scope):") to just "feat(scope):")
-    conventional_prefixes = [
-        "feat",
-        "fix",
-        "docs",
-        "style",
-        "refactor",
-        "perf",
-        "test",
-        "build",
-        "ci",
-        "chore",
-    ]
-
-    # Look for double prefix pattern like "chore: feat(scope):" and fix it
-    # This regex looks for a conventional prefix followed by another conventional prefix with a scope
+    Returns:
+        Message with double prefix corrected
+    """
     double_prefix_pattern = re.compile(
-        r"^(" + r"|\s*".join(conventional_prefixes) + r"):\s*(" + r"|\s*".join(conventional_prefixes) + r")\(([^)]+)\):"
+        r"^("
+        + r"|\s*".join(CommitMessageConstants.CONVENTIONAL_PREFIXES)
+        + r"):\s*("
+        + r"|\s*".join(CommitMessageConstants.CONVENTIONAL_PREFIXES)
+        + r")\(([^)]+)\):"
     )
     match = double_prefix_pattern.match(message)
 
     if match:
-        # Extract the second type and scope, which is what we want to keep
         second_type = match.group(2)
         scope = match.group(3)
         description = message[match.end() :].strip()
         message = f"{second_type}({scope}): {description}"
 
-    # Ensure message starts with a conventional commit prefix
+    return message
+
+
+def _ensure_conventional_prefix(message: str) -> str:
+    """Ensure the message starts with a conventional commit prefix.
+
+    Args:
+        message: The message to check
+
+    Returns:
+        Message with conventional prefix ensured
+    """
     if not any(
         message.strip().startswith(prefix + ":") or message.strip().startswith(prefix + "(")
-        for prefix in conventional_prefixes
+        for prefix in CommitMessageConstants.CONVENTIONAL_PREFIXES
     ):
         message = f"chore: {message.strip()}"
+    return message
+
+
+def _normalize_whitespace(message: str) -> str:
+    """Normalize whitespace, ensuring no more than one blank line between paragraphs.
+
+    Args:
+        message: The message to normalize
+
+    Returns:
+        Message with normalized whitespace
+    """
+    return re.sub(r"\n(?:[ \t]*\n){2,}", "\n\n", message).strip()
+
 
-    # Final cleanup: trim extra whitespace and ensure no more than one blank line
-    # Handle blank lines that may include spaces or tabs
-    message = re.sub(r"\n(?:[ \t]*\n){2,}", "\n\n", message).strip()
+# ============================================================================
+# Message Cleaning
+# ============================================================================
 
+
+def clean_commit_message(message: str) -> str:
+    """Clean up a commit message generated by an AI model.
+
+    This function:
+    1. Removes any preamble or reasoning text
+    2. Removes code block markers and formatting
+    3. Removes XML tags that might have leaked into the response
+    4. Fixes double type prefix issues (e.g., "chore: feat(scope):")
+    5. Normalizes whitespace
+
+    Args:
+        message: Raw commit message from AI
+
+    Returns:
+        Cleaned commit message ready for use
+    """
+    message = message.strip()
+    message = _remove_think_tags(message)
+    message = _remove_code_blocks(message)
+    message = _extract_commit_from_reasoning(message)
+    message = _remove_xml_tags(message)
+    message = _fix_double_prefix(message)
+    message = _normalize_whitespace(message)
     return message