Explain a code change
explain_changeDocument every meaningful code edit with intent, rationale, trade-offs, and verification to preserve developer understanding and maintainability during AI-assisted development.
Instructions
Record an explanation for a change you just made. Call this after every meaningful code edit — before moving on to the next task. The explanation is quality-checked and rejected if it does not genuinely transfer understanding. "I fixed a bug" or "refactored for clarity" will be rejected. You need a session open (call start_session first).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | Every file changed, with per-file what/why. | |
| scale | Yes | trivial: whitespace, rename, one-liner. local: one function/class, no external contracts changed. structural: module boundaries or data shapes changed, callers affected. architectural: cross-cutting concerns, deployment topology, system contracts. | |
| intent | Yes | The user-facing goal this change serves, in the user's own framing. Not your framing. | |
| diagram | No | Optional Mermaid source code that illustrates the change. | |
| summary | Yes | One-line summary. Reads like a good git commit subject. | |
| rejected | Yes | Approaches you considered and did not take. Empty is valid for trivial/local changes; structural+ changes must have at least one. | |
| callChain | No | Call graph nodes for this change. Include modified/created nodes and their direct callers. Required for structural and architectural changes to visualize impact. | |
| followUps | Yes | Work this change implies but does not do. | |
| rationale | Yes | The reasoning: WHY this shape of solution. State the constraint, failure mode, or alternative it beats. Do NOT restate what you changed — that is what summary and files are for. | |
| sessionId | Yes | The session id returned by start_session. | |
| tradeoffs | Yes | Costs knowingly accepted: what got slower, more complex, or harder to change. An honest empty array is fine for trivial changes. | |
| confidence | Yes | verified: you ran something (build, test, manual check) and it passed — list it in verification. likely: you reasoned it through but did not run it. unverified: you are unsure. | |
| verification | Yes | How a reviewer can check this: commands run, test names, manual steps. Required when confidence is "verified". | |
| conventionsApplied | Yes | Convention ids checked against while making this change. Pass [] if no conventions exist yet. | |
| implementationFlow | No | Optional step-by-step, method-level breakdown showing how this feature runs end-to-end. Format each step as: "MethodName(args) — what it does and why it matters". Example: "POST /login → validateInput(email, password) — checks format, rejects injection → UserRepo.findByEmail(email) — queries DB, returns record or null → bcrypt.compare(input, hash) — constant-time comparison, prevents timing attacks → SessionService.create(userId) — generates token, writes to Redis → 200 {token, expiresAt}". For structural/architectural changes, include an `implementationFlow` field with a step-by-step method-level breakdown showing how the feature works end-to-end. |