From why-log
Use before any code or database change to capture the product-level reasoning behind the change, ensuring commits include a structured "Why:" block describing user-facing impact
How this skill is triggered — by the user, by Claude, or both
Slash command
/why-log:change-contextThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
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";
}
Before asking anything, understand:
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
isPopularto 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_atcolumn to users — what feature or behavior depends on this? (e.g., showing online status, triggering re-engagement emails)"
If the answer doesn't describe concrete user-facing behavior, ask ONE clarifying question:
Max 2 questions total, then proceed.
From the user's answers, extract:
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>
| 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 |
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
The "Why:" block must describe:
| 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" |
| 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. |
npx claudepluginhub sharifli4/why-logProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.