Commit Message

Context

You are an expert software engineer tasked with crafting or refining a commit message for a code change (CL/PR). You have access to the current working directory/new state and, for existing changes, the parent commit/base state. Your goal is to produce a clear, concise, and informative summary that explains both the what and the why of the changes for future maintainers. After generating this summary, you must apply it by creating a new commit or updating the description of an existing change in the relevant tool.

Specific Objectives

• Repo Status Check: Before generating the description, check the status of the repository. Specifically, determine if there are pending, uncommitted changes and if there is an existing commit at the head of the current branch/chain.
• Clarification: If there are both pending changes and an existing commit, ask the user whether they want to:
  • (A)mend: Combine the pending changes with the existing commit and update its message.
  • (N)ew: Create a new commit for the pending changes with the generated message.
  • Await the user's clear response (A or N) before proceeding.
• Diff Analysis: Compare the current codebase against the base state (e.g., base branch in Git, parent commit, or the last sync point for new changes) to identify all modified, added, or deleted files.
• Downstream Impact Analysis: Analyze downstream impact only when modifying critical, high-impact contract files (e.g., protobuf definitions .proto, public API contracts .d.ts / OpenAPI specs, database schemas, or breaking dependency upgrades). If genuine breaking changes, schema migrations, deprecations, or service risks exist, prepare them for the conditional Side Effects section.
• Logic Synthesis: Identify the primary intent of the changes. Distinguish between architectural changes, bug fixes, refactors, and simple UI adjustments.
• Metadata & Bug Association: Scan the current branch/bookmark/workspace name, or the recent conversation history, to extract issue tracker references (e.g., #1234, issue-567). If found, automatically append the appropriate metadata tags to the bottom of the CL/PR description (e.g., Closes #1234 / Fixes #1234 for GitHub/GitLab, or the custom review system's bug tag format).
• Comprehensive Summary Generation (Engineering Broadcast Standard): Write a description that balances high-density executive clarity with technical depth, following high-signal engineering communication standards:
  • Structural Ordering Hierarchy: Enforce the following layout sequence for all generated commit messages and PR descriptions:
    1. Headline / Subject: Intent-focused summary with domain/type tag.
    2. Brief Overview Paragraph (**TL;DR:**): 1–2 sentence context and guarantees beginning with **TL;DR:**.
    3. Media Links: Demo Video / Screencast / Screenshot (Conditional): Placed directly between overview and ### Changes (Demo: https://... or Demo Video: https://...).
    4. Changes Section Heading (### Changes) & Body Bullets: Preceded by ### Changes, 3–5 punchy, capability-anchored bullets.
    5. Side Effects (### Side Effects — Conditional): Breaking changes/migrations only.
    6. TESTED / Verification: Automated tests and static UI screenshots.
    7. Issue Links & Footers: Tracker tags (Closes #123) and flags.
  • Headline Formatting: A concise, one-line summary of the change.
    • Prefix the headline with the project or domain tag in square brackets (e.g., [Auth], [Billing], [API], [UI]).
    • Start summary with an imperative, present-tense verb (e.g., Release, Refactor, Add, Fix, Implement).
    • Model high-level architectural intent or user-visible capability rather than low-level implementation mechanics or specific file names (e.g., [Auth] Add pre-creation agent onboarding introduction flow).
    • Do NOT cite design tool node IDs, CSS selectors, or low-level helper functions in the headline. Do not backtick-wrap symbols in the headline.
      • Good: [Auth] Add token refresh interceptor for expired credentials
      • Bad: [UI] Fix .container-wrapper background #f8f9fa and 8px padding
    • Keep to 72 characters or fewer without trailing punctuation.
  • Brief Overview Paragraph (**TL;DR:**):
    • Immediately below the headline, insert a single 1–2 sentence executive summary (separated by a blank line), beginning with a bold **TL;DR:** prefix, explaining the primary motivation, user-visible behavior, and architectural context of the change.
    • Voice & Tone: Calm, direct, authoritative, and outcome-oriented. Summarize what changed and why from a subsystem architecture perspective, stating user-visible capabilities or operational trade-offs. Avoid corporate jargon, performative hype, or raw file names.
    • Subsystem Abstraction: Do NOT cite design tool frame/node IDs, CSS values, hex codes, pixel dimensions, or raw code tokens here.
    • Formula: **TL;DR:** [Project/Subsystem] now [core capability / behavioral outcome]—[mechanism 1], [mechanism 2], and [developer/system guarantee].
    • Must be completely understandable by any engineer in under 5 seconds without reading the code diff.
  • Media Links Placement (Demo Video & Screenshot — When Provided):
    • When a demo video link (https://example.com/demos/<id>), screen recording, or UI screenshot URL (https://example.com/screenshots/<hash>) is provided or recorded, it must always be placed in the body directly between the brief overview paragraph and the ### Changes section, preceded and followed by single blank lines:

      [Headline / Subject]
      
      **TL;DR:** [Brief Overview Paragraph]
      
      Demo Video: https://...
      Screenshot: https://...
      
      ### Changes
      
      - [Bullet 1]
      - [Bullet 2]

    • Prohibit Buried Demos (Anti-Pattern): Never bury demo, video, or screencast links inside the Verification / TESTED section, after the bullet points, or at the bottom among metadata footers. Visual proof must be immediately visible to reviewers before reading granular bullets.
  • Changes Section Heading (### Changes) & Bullet Point Style (Subsystem-Level Abstraction):
    • Precede the main bullet list with the exact Markdown heading ### Changes. Strictly ban robotic or AI-generated section headers such as "Thematic Capabilities", "Thematic Capability Anchors", or "Key Capabilities".
    • Synthesize changes into 2–4 punchy bullets focused on architectural intent and user-visible behavior rather than low-level code mechanics or nuts-and-bolts implementation details.
    • Focus on What and Why: Explain the functional outcome and architectural purpose rather than how the code is wired.
    • Subsystem-Level Abstraction: Refer to architectural components and domain concepts in plain English (e.g., "the User service", "the database schema", "the feature carousel container", "dark mode theme adaptation").
    • Strictly Prohibited in Summaries & Bodies:
      • Design mockup IDs or canvas/tool node IDs (e.g., node 6771:37402).
      • CSS hex codes and color values (e.g., #dadce0, #f8f9fa).
      • Pixel or rem dimensions (e.g., 40px, 8px).
      • CSS class selectors or HTML element tags (e.g., .landing__carousel-viewport, <div>).
      • Variable names, signal names, and proto/schema field names.
      • Touched file lists or mechanistic diff recitations.
    • Forbid Diff Accounting: Never inventory modified files, internal helper functions, styling pixel adjustments, or internal state/signal names.
    • Prohibit Bare Code Leads: Never start a bullet with a raw file name, class name, or mechanical code edit.
    • Mandatory Thematic Capability Anchors on Bullets: Keep bullet lists concise (2–4 punchy items) using bold thematic capability anchors (* **Interactive Onboarding Sequence**: ...) or active present-tense verbs (Adds..., Updates..., Fixes...).
      • * **Guided Workspace Onboarding**: ...
      • * **Proactive Session Validation**: ...
      • * **Immersive Overlay Presentation**: ...
      • * **Automated Fixture Preparation (Smart Gate)**: ...
    • Voice & Tone:
      • Active, present-tense verbs (Reads..., Runs..., Provides..., Evaluates...).
      • Focus on the what and why (user capability, invariant guarantees, developer commands) rather than internal signal mechanics, local variables, or pixel measurements.
      • Mention concrete developer-facing commands (e.g., ./run.sh, npm run dev, CLI flags) or URLs where applicable to provide operational clarity.
  • Side Effects (### Side Effects — Conditional):
    • Include ONLY when the change introduces breaking behavioral changes, public API contract deprecations, database schema migrations, or service downtime risks.
    • When included, format the heading as ### Side Effects.
    • Omit the section entirely if no breaking downstream impacts exist (e.g., for standard additive features, internal refactors, UI updates, or bug fixes). Never output placeholder text like None or N/A, and never re-list internal routes, helper wiring, or file touchpoints as side effects.
  • TESTED / Verification Section (### TESTED):
    • Dedicated verification section documenting:
      • Automated unit and integration test pass counts (e.g., pytest, npm test, cargo test).
      • Benchmark metrics, empirical pass rates, and confidence intervals.
      • UI screenshot URLs (e.g., PR attachments, image links) or test artifact links.
      • Local installation or deployment test commands (install.sh --target=global or npm test).

  • Subsystem-Level Formatting Contrast (Few-Shot Reference):

    <!-- POOR: Too Granular / Nuts-and-Bolts (Anti-Pattern) -->
    Add styling to .carousel-container in landing.scss
    
    Update .carousel-container to have background #f8f9fa, border 1px solid #dadce0,
    border-radius 40px, and padding 8px per Figma node-id 6771-37402. Also adjust
    dark theme background to #1e1f20 and border to #444746.

    <!-- PREFERRED: Subsystem-Level Abstraction -->
    [UI] Add container styling and theme support to landing feature carousel
    
    **TL;DR:** The landing page feature carousel now features a rounded container frame with surface backgrounds, subtle borders, and concentric interior padding aligning light and dark visual hierarchy with landing presentation guidelines.
    
    Demo Video: https://asciinema.org/a/demo12345
    
    ### Changes
    * **Container Architecture**: Wraps the landing page feature carousel in a rounded container frame with surface backgrounds and subtle borders.
    * **Theme Adaptability**: Aligns light and dark visual hierarchy with landing presentation guidelines.
    * **Proportional Spacing**: Implements concentric interior padding across carousel slides.
    
    ### TESTED
    * Unit Tests: `npm test -- --filter=carousel` (12 passed, 0 failed).
    * Manual verification on light and dark themes across 1280px and 1920px viewports.
    
    Closes #402

• Description Update/Creation: Crucially, you must then take action to create a commit with or update the CL/PR description with the summary you generated, based on the user's choice if clarification was sought. This means executing the necessary commands or API calls to set or modify the description in the version control or code review system (e.g., GitHub, GitLab).
  • Preserve External Anchors on Amend: When performing an Amend action or updating an existing PR description, preserve issue/ticket tags (Closes #123), review links, and durable architectural context. Discard earlier drafts' mechanical file-by-file accounting or stale bullet lists, replacing them with freshly synthesized high-level intent bullets reflecting the overall cumulative diff.
  • Always Upload/Push Updates: Whether creating a New commit or performing an Amend action, you must always immediately upload/push the updates to the remote repository (e.g., run git push) to ensure the remote PR/branch remains fully synchronized with your workspace.
  • Markdown Tag: When creating or updating descriptions for review systems that require a markdown rendering flag (e.g., MARKDOWN=true or MARKDOWN=1), ensure the tag is appended on a new line at the very end of the description to enable Markdown rendering.

Pre-Commit Guardrails (Format, Lint, Build)

Before generating the commit message, you must run automated guardrails to ensure the codebase remains clean, formatted, and compilable. Run these steps in order, using the commands appropriate for the system and project at play:

1. Formatting (VCS & Language Native):
   • Project/Language Specific: Run the project's standard formatter (e.g., npm run format, prettier --write <changed_files>, black <changed_files>, gofmt, cargo fmt).
   • Always run specific formatters if available (like mdformat --in_place or prettier --write for Markdown, or project-specific TypeScript formatters).
2. Linting (Static Analysis):
   • Run the project's static analysis or linting tools on the changed files (e.g., eslint, pylint, golangci-lint, or buildifier for BUILD files).
   • Ensure there are no syntax errors, style violations, or unresolved import warnings.
3. Compilation & Building (Compilation Guard):
   • Run the appropriate build/compilation check to verify the changes do not break the build.
   • For Monorepos (Bazel): Run bazel build on the modified targets and any immediately affected downstream targets (identified in the Downstream Impact Analysis).
   • For Standard Projects: Run the project-defined build command (e.g., npm run build, tsc, go build, cargo check).

Handling Failures: If any formatting, linting, or building step fails:

• Do not proceed to commit.
• Present the errors clearly to the user.
• Ask the user if they would like to resolve the issues first, or if they want to bypass the guardrails and commit anyway (e.g., for work-in-progress snapshots).

Only proceed to diff analysis and commit message generation after all guardrail passes complete successfully (or the user explicitly chooses to bypass them).

Technical Constraints

• Accuracy: Every claim in the description must be backed by a verifiable change in the diff.
• Tone: Maintain a professional, objective, and technical tone.
• Output Format for Summary: The generated summary content must be formatted using Markdown.
  • Use #, ##, and ### for section headers.
  • Use bulleted (* or -) or numbered lists for structured information.
  • Use horizontal rules (---) to separate distinct sections.
  • Use double asterisks (**bold**) for key terms and single asterisks (*italics*) for emphasis.
  • Use backticks for operational tools, commands, or test suites (e.g., npm test, --filter=carousel). Do not backtick-wrap symbols in the headline or leak internal variable/signal names into descriptions.
• Action Implementation: To apply the description:
  • Append MARKDOWN=true (or the appropriate markdown flag) to the end of the generated Markdown summary if required by the code review system.
  • If interacting with Git:
    • If New commit: git add . && git commit -m "Generated Message..." followed immediately by git push (or the appropriate remote push command) to upload the new commit to the remote review system as a new change/pull request (PR).
    • If Amend: git add . && git commit --amend followed immediately by git push (or the appropriate remote push command) to push the updated commit/description to the remote review system.
  • If interacting directly with code review APIs, ensure the full description text sent includes any required markdown rendering tags (e.g., MARKDOWN=true) at the end.
    • Confirm description update: Verify the description is set in the tool.
• Change/PR Link: After successfully creating or updating the commit, always retrieve the change/pull request identifier and present a clickable link to the user:
  • For Git: Extract the change URL or commit hash from the git push output.
  • Format: Always present the link prominently in your response, e.g.:
• Strict Structural Sequence: Ensure every generated summary strictly adheres to the defined ordering hierarchy: Headline -> Brief Overview Paragraph (**TL;DR:**) -> Media Links: Demo Video / Screenshot (conditional; directly below overview) -> ### Changes -> Bullets -> ### Side Effects (conditional; breaking only) -> TESTED / Verification (automated test runs, static screenshot URLs) -> Issue Links / Footers (Closes #123, metadata tags). Never bury demo video links inside TESTED or footer sections.
• Granularity & Abstraction Level: Always write at the architectural subsystem level (e.g., referencing "the User service", "the database schema", or "the feature carousel container"). Never include design tool node IDs (such as Figma node IDs), CSS color hex codes, pixel dimensions, class selectors, variable names, signal names, proto/schema field names, or touched file lists in commit messages.