change-context

Change Context

Capture the product-level "why" before every code change. This ensures commit messages describe not just what changed, but why it matters to users and the business.

This is a rigid skill — it always runs before code changes and cannot be skipped.

Process

digraph change_context {
    "User requests change" [shape=doublecircle];
    "Analyze requested change" [shape=box];
    "Ask change-specific question" [shape=box];
    "Answer describes concrete behavior?" [shape=diamond];
    "Ask one follow-up" [shape=box];
    "Compose commit context" [shape=box];
    "Proceed with implementation" [shape=doublecircle];

    "User requests change" -> "Analyze requested change";
    "Analyze requested change" -> "Ask change-specific question";
    "Ask change-specific question" -> "Answer describes concrete behavior?";
    "Answer describes concrete behavior?" -> "Compose commit context" [label="yes"];
    "Answer describes concrete behavior?" -> "Ask one follow-up" [label="no/vague"];
    "Ask one follow-up" -> "Compose commit context";
    "Compose commit context" -> "Proceed with implementation";
}

Step 1: Analyze the Requested Change

Before asking anything, understand:

• Which entity, file, module, or behavior is being changed
• What type of change this is (new feature, bug fix, refactor, etc.)
• The technical scope (single file vs cross-cutting)

Step 2: Ask a Change-Specific Question

Ask ONE question tailored to the specific change. Not generic — reference the actual entity, property, or behavior being modified.

For new features/properties:

"You're adding isPopular to Product — where will this be visible to users? (e.g., badge on product card, filter on listing page, sorting criteria)"

For bug fixes:

"You're changing the token refresh logic — what user-facing issue does this fix? (e.g., users getting logged out, error messages, broken flows)"

For refactors:

"You're extracting pricing into a service — what problem was the duplication causing? (e.g., inconsistent behavior, bugs in specific flows)"

For database changes:

"You're adding a last_active_at column to users — what feature or behavior depends on this? (e.g., showing online status, triggering re-engagement emails)"

Step 3: Follow Up If Vague (Max 1 Follow-Up)

If the answer doesn't describe concrete user-facing behavior, ask ONE clarifying question:

• "So on the [screen/flow], users will see [specific behavior]?"
• "Which users are affected — all users or a specific segment?"
• "When this happens, what does the user experience differently?"

Max 2 questions total, then proceed.

Step 4: Compose Commit Context

From the user's answers, extract:

• type: conventional commit type (feat, fix, refactor, perf, docs, chore, test, style)
• scope: module or feature name
• summary: one-line description of the change
• why: product-level context in plain language (1-3 sentences)

Store this context and ensure the commit message follows this format when the work is committed:

<type>(<scope>): <summary>

Why: <product-level context in plain language>

Commit Format Reference

Types

Type	When to Use
feat	New feature or capability
fix	Bug fix
refactor	Code restructuring without behavior change
perf	Performance improvement
docs	Documentation changes
chore	Maintenance, dependencies, tooling
test	Adding or updating tests
style	Formatting, whitespace, linting

Examples

feat(product): add isPopular property to Product entity

Why: Displays a trending badge on product cards in the listing page
and enables 'Popular' filter tab

fix(auth): handle expired refresh tokens gracefully

Why: Users on the mobile app were getting logged out mid-session
when their token expired during a long form submission

refactor(order): extract pricing calculation into separate service

Why: Pricing logic was duplicated across order and subscription flows,
causing inconsistent discount application

Quality Criteria for "Why:" Block

The "Why:" block must describe:

• User-facing behavior — what the user sees, does, or experiences differently
• Product language — written as a mini product spec, not technical jargon
• Concrete specifics — names screens, flows, user actions — not abstract goals

Bad	Good
"Improves code quality"	"Pricing logic was duplicated across order and subscription flows, causing inconsistent discount application"
"Adds new functionality"	"Lets users move all wishlist items to cart in one tap instead of adding them one by one"
"Fixes a bug"	"Users on the mobile app were getting logged out mid-session when their token expired during a long form submission"
"Updates the database"	"Enables the 'Recently Active' badge on user profiles and powers the re-engagement email campaign"

Red Flags

Thought	Reality
"This change is too small to ask why"	Every change has a reason. Capture it.
"The why is obvious from the code"	Obvious to you now, not to someone reading the changelog in 6 months
"I'll just write a generic why"	Generic = useless. Be specific or ask again.
"The user already explained why"	Great — extract it and format it. Don't skip the commit format.