# How to recover intent from a coding session

Recovering intent from a coding session means reading the prompts and decisions behind a change to learn what it was meant to do, not only what it does.

Last updated September 29, 2026, 9 min read

## Learning objectives

After reading this article you will be able to:

-   Define the intent behind a code change
-   Apply a saved session to review or debug a change
-   Identify what a transcript cannot show about intent

## Related content

-   [What is a coding agent?](https://specstory.com/learning/ai-coding/coding-agent)
-   [What is AI coding session history?](https://specstory.com/learning/ai-coding/ai-coding-session-history)
-   [What is context engineering?](https://specstory.com/learning/ai-coding/context-engineering)
-   [What is plan mode in a coding agent?](https://specstory.com/learning/ai-coding/plan-mode)
-   [What is a PRD, and does a coding agent need one?](https://specstory.com/learning/ai-coding/prd-for-coding-agents)

## Key points

-   Trace the line to its commit with git blame, then find the session that produced that commit.
-   Read the developer's prompts and approvals as the intent, and the agent's replies as its method.
-   Write the recovered reason into a comment, a test, or a commit message where the next reader looks.

## How do you recover intent from a coding session?

To recover the intent behind a change, trace the line to the [commit](https://specstory.com/learning/glossary#commit) that added it, then find the coding session that produced that commit. Read the developer's prompts, corrections, and approvals around the edit. Treat the agent's replies as its method, not the goal. Then write the reason down next to the code.

The intent behind a code change, also called developer intent, is the result a person wanted from it and the reason for it. When a [coding agent](https://specstory.com/learning/ai-coding/coding-agent) writes the change, much of that reason is in the developer's prompts, which the diff does not hold.

Saved conversations make up [session history](https://specstory.com/learning/ai-coding/ai-coding-session-history), and [context engineering](https://specstory.com/learning/ai-coding/context-engineering) covers how the reason gets lost between sessions. The path from a line to its commit and its session is part of the change's provenance. Reviewers follow it to [review a pull request](https://specstory.com/learning/code-review/reviewing-agent-pull-requests) from an agent, and developers follow it in [root cause analysis](https://specstory.com/learning/debugging/root-cause-analysis).

## What do you need before you start?

A trace from a line back to its reason needs these records:

-   **The line in question.** A file path and a line number set the scope of the search.
-   **The full Git history.** A full clone lets `git blame` reach commits that a shallow clone leaves out.
-   **The saved sessions.** Transcripts hold the prompts and replies, in the agent's own store or a shared folder.
-   **Any linked document.** A written goal, e.g. a [product requirements document](https://specstory.com/learning/ai-coding/prd-for-coding-agents), records limits that the prompts leave out.

When the session that wrote the code was not saved, the trace stops at the commit. The commit message, the [pull request](https://specstory.com/learning/code-review/pull-request), and the tests hold what is left of the reason, and the developer who ran the agent may recall more. A reason rebuilt this way is less certain.

## How do you recover intent from a coding session step by step?

Here is an illustrative example. Acme Co. sells furniture online. A developer at Acme finds a line in `src/checkout/address.js` that reloads the cart after each address change. Nothing in the file explains it.

Diagram: Tracing a line of code back to its intent

The developer's words state the intent. The agent's replies explain its method, which can change while the intent stays the same.

### 1\. Name the line and the decision

Write down the line and the decision that waits on the answer. At Acme, the line is `await cart.reload();` at line 41, and the decision is whether to delete it.

### 2\. Find the commit that added the line

Run [`git blame`](https://git-scm.com/docs/git-blame) on the line. The `-w` flag ignores whitespace, and `-C` follows lines moved or copied from other files that the same commit changed:

```bash
git blame -w -C -L 41,41 src/checkout/address.js
```

The output names the commit and its author:

```text
9c41e2ab (acme-dev 2026-06-12 14:03:22 +0000 41)   await cart.reload();
```

The author, `acme-dev`, is the developer who ran the coding agent. The agent wrote the line. If blame names a commit that only reformatted the line, `--ignore-rev` skips it. The [git log manual](https://git-scm.com/docs/git-log) adds two searches. `git log -S'cart.reload()'` finds the commits that added or removed that text, and `git log -L 41,41:src/checkout/address.js` shows each change to the line.

### 3\. Read the commit and find its session

Print the full message with `git log -1 --format=%B 9c41e2ab`. At Acme, it has a title and one trailer:

```text
Keep the cart when the delivery address changes

Agent-Session: history/address-cart-fix.md
```

A trailer is a `key: value` line in the last paragraph of a commit message. [`git interpret-trailers`](https://git-scm.com/docs/git-interpret-trailers) adds and parses trailers, and `git log --format='%(trailers)'` prints them. Trailers are one way to record [AI code attribution](https://specstory.com/learning/glossary#ai-code-attribution).

Some agents add a link by default. From a cloud or Remote Control session, Claude Code [adds a `Claude-Session` trailer](https://code.claude.com/docs/en/settings-reference) to the commit and a session link to the pull request description. Without either, match the commit's branch and time with the saved sessions, or search them for the file name.

### 4\. Separate the request from the agent's method

Read the developer's messages around the edit, then the agent's reply before the tool call that made it. At Acme, that part reads:

```text
Developer: The address saved, but the cart emptied. Keep the cart's
           items when the address changes.
Agent:     saveSession() replaces the whole session, so the cart is
           dropped. I will reload the cart from the server after the
           address saves.
Tool call: edit src/checkout/address.js, add await cart.reload();
Developer: ok
```

The developer asked for one result, a cart that keeps its items. The reload came from the agent, as a workaround for `saveSession()`, and the developer's "ok" approved the fix without a word on the method. Deleting the reload would bring the failure back. A `saveSession()` that keeps the cart would meet the same intent.

An approved plan from [plan mode](https://specstory.com/learning/ai-coding/plan-mode) also records what the developer accepted before any edit. An edit the task did not ask for is an [out-of-scope edit](https://specstory.com/learning/verification/out-of-scope-edits), and at most the agent's reply explains it.

### 5\. Write the reason where the next reader looks

The next reader starts from the code, not the session. Put the rule in a comment next to the line, e.g. "The cart keeps its items when the address changes." Then add a test for the rule:

```js
test("changing the address keeps the cart", async () => {
  const order = await startCheckout({ items: 2 });
  await order.setAddress("12 Elm Street");
  expect(order.items).toHaveLength(2);
});
```

The rule is one of the change's [acceptance criteria](https://specstory.com/learning/ai-coding/acceptance-criteria), and the test lets a run check it. A commit message should state the reason in the developer's words and point to the session with a trailer. Pasting the whole prompt makes the message long, and a prompt can hold secrets, e.g. an API key.

Writing the recovered reason down is one way to pay down [comprehension debt](https://specstory.com/learning/code-review/comprehension-debt), the code that nobody on the team understands. This example is simplified. A real line can have several commits and sessions behind it.

## What can a transcript not tell you about intent?

A transcript records what was typed and run in one session. Intent can sit outside it in these ways:

-   **Rules nobody typed.** A prompt is a short version of what the developer wanted, so an assumed rule appears nowhere.
-   **Approval without reading.** A reply of "ok" can accept a fix whose code nobody read, so it shows consent to the result, not a check of the method.
-   **Decisions after the session.** A review comment, a later session, or a hand edit can change the code and its reason somewhere else.
-   **Reasons the model generated.** The reply before an edit is generated text, and the edit can differ from what the reply describes.
-   **Intent without a check.** Knowing what a change was meant to do does not show that the code does it. That takes a run.

## What are common mistakes?

These mistakes lead to the wrong reason:

-   **Asking a later session why.** A later agent session does not hold the old conversation, so its answer is a reason generated from the code, not the one the developer gave.
-   **Reading the summary, not the prompts.** The final summary is the agent's account of its work, not the developer's request.
-   **Stopping at the first prompt.** Later corrections often narrow or change the request.
-   **Taking the method for the goal.** A workaround the agent generated can be replaced, while the rule it served has to stay.
-   **Leaving the reason in the session.** A reason kept only in a transcript is lost when nobody can find the file.

## How do you check that it worked?

The reason is recovered when these statements are true:

-   The reason fits in one sentence, matches the diff, and points to a message from the developer, not only an agent reply.
-   The reason sits in a comment, a test, or a commit message, where the next reader looks.
-   The test fails when the line is deleted and passes when it is restored.
-   A second person, e.g. a reviewer in [code review](https://specstory.com/learning/code-review/code-review), reaches the same answer from the record alone.

## How does SpecStory help with recovering intent?

Without a saved session that people can find, the trace from a line stops before its reason. SpecStory keeps the conversations behind your code. It keeps the prompts and decisions from your coding agent sessions, so you can reuse them when the next task begins.

Your sessions become local Markdown files you can read, search, and keep alongside your code. You can also sync to SpecStory Cloud to search across conversations and share the context behind a change. Saving a conversation with SpecStory does not itself test the software.

[Get SpecStory →](https://specstory.com/specstory)

## FAQs

### What is developer intent?

Developer intent is the result a developer wanted from a change and the reason for it. In a coding session, it shows in the developer's prompts, corrections, and approvals, while the agent's replies record its method.

### Should commit messages record the prompt?

Commit messages should record the reason for a change in the developer's words, not the whole prompt. A full prompt makes the message long and can hold secrets. A trailer that points to the saved session leads a reader to the full conversation.

### Can git blame show why a line was written?

Git blame shows which commit last changed each line, with its author and date, but not the reason. The reason sits in the commit message, the pull request, or the session. With a coding agent, the author is often the developer who ran it.

### What if the session that wrote the code was not saved?

Without a saved session, the trace ends at the commit. The commit message, the pull request, and the tests hold part of the reason. A reason rebuilt from them and the developer's memory is less certain than one read from the session.

---

Source: [Why was this code written? | Recover its intent | SpecStory](https://specstory.com/learning/ai-coding/intent-from-coding-sessions)