DEV Community: Eugene

Two AI Prompts That Fixed My Git History

Eugene — Mon, 10 Aug 2026 13:00:00 +0000

TL;DR

I used to have pull requests with dozens, and sometimes hundreds, of commits. Most of the messages were complete garbage: Cleanup., More tests., fix., some initial notes.

Two small Markdown prompt files removed the friction:

commit.md stages the requested changes, reads the staged diff, and creates a short descriptive commit message.
create-pull-request.md reads the commit log, generates a PR title and description, pushes the branch, and runs gh pr create.

The useful part is how the quality compounds. Good commit messages become good PR descriptions. Those descriptions give reviewers better context, and the commit history becomes useful to both humans and coding agents later.

The prompt content is agent-agnostic. I usually package these prompts as commands, although skills can work too. For this kind of housekeeping task, I also prefer a fast, cheap model over the most expensive reasoning model available.

Video Walkthrough

If you prefer a video walkthrough, here it is:

A Real Pull Request With 209 Bad Commits

This was not a hypothetical example. I had a real pull request with 209 commits, and many messages looked like this:

Cleanup.
More tests.
Some initial notes.
More readme.
fix.

Sure, you can squash before merging. But that does not make the branch history useful while the work is in progress, and a vague squashed commit is still vague.

Usually nobody reads commit messages until production is on fire and you're trying to figure out what changed three months ago. At that point the history becomes a search index, and good history is way easier to search. Sure, an LLM will probably find the answer anyway, but it will take longer, explore more diffs, and likely burn more tokens as well.

I can write a good commit message by hand. The problem is doing it consistently while committing often, switching between branches, or working with several agents that are producing a bunch of code that I need to review and commit. This is a good LLM task: read some text that happens to be code, summarize it, and run a few Git commands, so adding prompts to automate this was a logical next step.

Prompt One: Turn the Diff Into a Commit

My current commit.md is intentionally small:

# Follow this instruction to commit changes.

Only use this instruction if the user asks for it.
* All commands should be run from a repo root.
* You will be given a list of files to commit.
* Commit all updated files if not otherwise specified. In this case use `git add .` from a repo root as a first step to stage all updated files.
* If user requested to commit specific files, use `git add <file1> <file2> ...` to stage specific files only.
* When committing, make sure to provide a sensible message. Figure out the message from chat history and/or the actual code changes. Make the message short and descriptive.
* Always run `git diff --staged` before composing the message so you can summarise what was changed.
* If you still lack context after reviewing the diff, consult the chat history; the diff should be your primary source for message content, not just `git status`.
Do NOT do any other verification or actions unrelated to this instruction. You SHOULD just commit the changes as specified here.

The staged diff is the primary source because it is what you are actually committing. Chat history is useful as extra context, but it can be incomplete, stale, or describe changes that never made it into the worktree.

The last line is also important. Without that boundary, a helpful agent may run lint, start fixing unrelated problems, or turn a five-second checkpoint into a much larger task. This prompt has one job. It does not replace the verification you run before calling the actual coding task complete.

If I want the whole worktree committed, git add . is convenient. If I want a specific set of changes, I give the agent the file list instead, but I think I do this less often.

Prompt Two: Turn Commit History Into a Pull Request

The companion create-pull-request.md uses the branch history as its input:

# Instruction to create pull request

This is an instruction to follow when user is referencing it. Only use this instruction when explicitly requested by the user.

1. Review the commit history between the base branch (use **main** unless another base is specified) and the current branch:
```bash
# Make sure remote is up to date
git fetch origin

# Get the current branch; use it when pushing and creating the PR
git branch --show-current

# Read commits on this branch that are not on the base branch
git log origin/<base branch>..HEAD --oneline | cat
```

2. Review commit history and come up with a sensible PR title.
3. Review commit history and come up with a sensible PR description:
   ```markdown
   * Short change description 1
   * Short change description 2
   * ...
   ```
4. Prepare the PR title and description.
5. Push pending changes and create a PR. Pass the description through standard input so multiline Markdown and shell characters remain intact:
```bash
git push origin <current branch> --set-upstream
gh pr create \
  --title "<PR title>" \
  --body-file - \
  --base "<base branch>" \
  --head "<current branch>" <<'EOF'
<PR description>
EOF
```
6. Show the PR URL to the user.

git fetch origin needs to happen before the comparison. Otherwise the agent may summarize the wrong range against stale remote state.

Good Summaries Compound

The first prompt is useful on its own, but the second prompt is where the workflow starts paying back.

Instead of this:

cleanup
fix
more changes
update tests
final tweaks

I get history closer to this:

Add AccountsStore load/validate/query and tests
Add cmd/bbmd Cobra scaffold and DI smoke tests
Implement bbmd auth sub-commands
Implement bbmd pr sub-commands
bbmd: unify auth/PR execution via exec helpers and tests

Now the PR description is a summary of already-good summaries. A real PR created with this workflow has a specific title, a short explanation of the change, and a useful high-level list for reviewers.

The same history helps later when a teammate reviews the PR, an agent needs to understand why something changed, or you need to generate release notes. The compound effect works in the other direction too: vague commits give the PR prompt vague input.

How Do I Run This?

For the commit.md one, I usually do it like this:

Run it manually when I want to checkpoint my work, for example with /commit or follow @commit.md. I do this less often these days.
Have my agent run it during a long-running orchestration loop, usually as part of a verification step handled by a dedicated sub-agent.

The create-pull-request.md prompt works the same way: I run it myself or let my agent run it when it's time to submit the PR.

If Something Goes Wrong

If you notice a model misbehaving with these prompts, Agent Diagnostics Mode can help you understand why. I use it for prompt problems in general, not just commit and pull request automation.

Is This Lazy?

Maybe. But it is the good kind of lazy.

The output is better, the friction is lower, and the history is more useful. I will take that trade-off.

Your AI Coding Agent Is LYING When It Says "Done"

Eugene — Fri, 31 Jul 2026 08:10:07 +0000

TL;DR

When an AI agent changes few files, runs few tests, and says "Done", is it really done? Not always. Things may still break in unexpected places.

I prefer to define a strict definition of "Done", which I call the Task Completion Protocol. It usually lives in AGENTS.md and, in its simplest form, looks like this:

Run the repository's real lint and test commands.
Fix failures and rerun the checks.
Report the exact evidence before claiming completion.

This does not replace CI or code review. It moves a basic verification gate earlier, before a broken state reaches the next agent session, the pull request, or you.

Video Walkthrough

If you prefer a visual walkthrough, this video shows the concept in action. I run the same task twice: without a completion protocol and with it - this demonstrates how explicit definition of "done" helps. I also show few tricks and techniques for making agents follow the protocol.

The Agent Says "Done." The Repository Disagrees.

You have probably seen some version of this:

Agent:
Done. Implemented the fix and updated the tests.

Terminal:
$ make test
... FAIL

The implementation might even look correct. Perhaps the agent ran one focused test, inspected the diff, and produced a tidy summary. Then you run the repository's normal checks and find a lint error, a failing test in a different place, or any other error that was not caught by the agent.

This gets worse as AI-assisted workflows grow to involve multiple agents. In an interactive session, you may spot the failure and fix it yourself. In a multi-step workflow, one worker reports success and the next starts from a broken state. These problems accumulate quickly, and the final state may be badly broken.

The Repository Needs to Define What "Done" Means

Yes, this is obvious for humans: make some changes, run tests and lint, fix issues, maybe check few other things, and only then say "Done". Agents need it written down, and AGENTS.md is the perfect place for it. I call this section the Task Completion Protocol.

Here is a compact version you can adapt to your repository:

## Task Completion Protocol

Before reporting completion, classify the task as coding or non-coding.

For coding tasks:
1. Run lint: `your command to run lint`.
2. Run tests: `your command to run tests`.
3. Check whether commands, workflows, or architecture changed. If so, update AGENTS.md.
4. Report the commands run, their results, test coverage, and whether AGENTS.md changed.
5. Do not report the task as complete while a required check is failing.

For non-coding tasks:
1. Summarize the findings or actions taken.
2. Confirm that the requested deliverable was produced.
3. Do not run unrelated lint or test commands unless requested.

My Go backend template has a real version of this protocol. It uses make lint and make test. Your protocol should name the exact commands and any specific checks that matter.

Don't just say "Run the tests". This still leaves the agent guessing. It is best to name the exact commands the agent must run.

Classification and Hierarchy Are Important

"Always run everything" may work in a small repository. In a monorepo, it quickly becomes expensive and sometimes absurd.

A documentation change does not need the entire test suite. A CSS change may need visual verification, not a set of backend tests. The same applies to Terraform, Helm, and similar tools.

At minimum, I classify tasks as coding or non-coding. We don't want to run tests if we only changed some docs, skills, or similar files.

The hierarchy makes sense as well. Each area can have its own AGENTS.md file with its own completion protocol. Each type of change may require different checks and commands.

The root AGENTS.md can define project-wide behavior if relevant. More specific files can define what completion means there. Typically I have something like this:

AGENTS.md
├── apps/web/AGENTS.md
├── apps/backend/AGENTS.md
└── deploy/terraform/AGENTS.md

And I make sure to keep the root AGENTS.md minimal.

The Reporting Part Also Matters

Do not let the agent "guess" what to report. Require an explicit format. I typically use something like this:

Lint: pass - make lint
Tests: pass - make test
Coverage: 87.42% - this one is very important
AGENTS.md: no changes needed
Status: complete

And it is not really for you to read (though I do sometimes). It is more for the agent. A strict reporting format gives the agent more "motivation" to actually run your checks. Otherwise it may just "guess" the outcome.

The dynamic part matters too. I typically require coverage reporting. If you don't collect it (I hope you do), ask for test duration or something else the agent can't guess. I haven't seen a model report this reliably without running the checks.

This Does Not Replace CI or Review

The completion protocol is a local behavioral contract. CI remains the hard and deterministic gate.

You still want deterministic checks in the pipeline, and you still need to review and validate the change. Passing tests do not prove the requested behavior is correct, the architecture is sensible, or the security model survived the refactor. But it gives you a solid baseline:

The repository is "green".
The agent used the team's canonical checks.
Failures were caught sooner instead of passed forward.

The Harness May Make It Harder

One frustrating caveat: repository instructions are not always the highest-priority instructions an agent receives. The harness may add constraints that shape command execution, testing behavior, and final reporting.

If an agent repeatedly ignores a clear completion protocol, the wording in AGENTS.md may not be the problem. Ask your model which instruction is shaping the verification behavior and where it came from. I use Agent Diagnostics Mode for this kind of investigation.

Start Small

You do not need a giant governance document. Start with the checks you already expect a responsible human contributor to run. Extend your completion protocol as the project grows.

This helps me a lot and I hope it will help you too!

Agent Diagnostics Mode — A Structured Technique for Iterative Prompt Tuning

Eugene — Sat, 21 Mar 2026 09:24:12 +0000

The Problem with Prompt Tuning Today

Prompts are not static configuration. If you have been running LLM-powered agents on real projects for more than a few months, you already know this. A prompt that worked perfectly last quarter drifts after a model update. A system instruction that produced reliable behavior on one agent — say, Cursor — behaves differently when you port it to Gemini or Claude. And the same prompt file can produce subtly inconsistent results across projects as the surrounding context changes.

The usual response to this is ad-hoc: you notice something is off, exit the working conversation, edit the prompt file, re-run the agent, and try to reconstruct the context you had before. That friction compounds. You lose the conversational thread. You lose the intermediate reasoning the model had built up. And you are basically doing print-statement debugging on a system that has no stack trace.

The problem is not that prompt tuning is hard. The problem is that there is no structured diagnostic loop for doing it inside the working context. As for me, this lack of structure has been a recurring pain point.

Video Walkthrough: The Diagnostics In Action

If you prefer a visual deep dive, I have a video for this post. I walk through the "Westworld" analysis vibe in real-time, showing exactly how the model pivots from "doing" to "reporting" in a live project.

Quick Start: Entering and Exiting Diagnostics Mode

The mechanic is simple. I keep a small file at .context/agent-diagnostics-mode.md:

# Agent Diagnostics Mode

If user is referencing this prompt, you are in self-diagnostics mode. The goal of this mode is typically to understand your reasoning process, decision making, actions or results. Typically the user is trying to optimise your performance or behavior and tune their instructions to you.

The user may typically ask you something along with this prompt. You should analyse the user enquiry and report your findings based on the user enquiry.

**IMPORTANT:** You MUST NOT do any actions or modifications - just analyse and report your findings based on the user enquiry.

To enter diagnostics mode on any agent that supports referenced prompt files (are there any that do not?), I include this file in my message. The effect is immediate and significant: the model pivots from doing to reporting. It stops planning tasks and starts articulating its reasoning.

Here is a real example from one of my Go projects. My AGENTS.md defines two distinct task completion protocols for example: a Coding Task Completion Protocol (run make lint, run make test, confirm coverage, report status) and a Non-Coding Task Completion Protocol (summarize findings, confirm deliverables, no lint/test required). The intent is obvious: code changes require verification, everything else does not.

The model started skipping lint and tests after refactoring a package. It classified the task as non-coding — I suspect because the instruction I gave was phrased around reorganizing files, which pattern-matched to "documentation/investigation" rather than "code change." The refactor changed Go files. Lint and tests were mandatory. But the agent declared completion with just a summary.

Enter diagnostics:

@agent-diagnostics-mode.md

I just asked you to move a package and update its imports across the codebase. You reported completion without running make lint or make test. Which task completion protocol did you apply, and what in my instructions led you to that classification?

The agent responds with a behavioral report — not an action. It identifies that it applied the Non-Coding protocol, cites the exact section it matched against ("investigation, documentation review, committing"), and notes that the ambiguity came from my use of the word "reorganize" — a word it associated with structural/documentation work rather than code modification. No files are changed. No commands are run.

Exit diagnostics:

Exit diagnostics mode. Now update AGENTS.md so that the Coding Task Completion Protocol explicitly lists package moves and import updates as coding tasks, regardless of how the instruction is phrased.

The model carries the diagnostic conclusion forward and applies the fix in one step. The conversation context is the working memory — no reconstruction needed.

No special tooling is required here. This is a pure prompt technique.

Side note: every time I type @agent-diagnostics-mode.md I think of Westworld — where the hosts switched to "Analysis" mode on a simple voice command. Same vibe, but instead of uncovering suppressed memories, you are uncovering why your agent skipped make test. Feels like the future we're living in — there were no flying cars in that movie, so I guess we're almost there. :)

Why This Works: The Architecture Behind the Mode

Why LLMs Respond to Mode Declarations

LLMs are sensitive to framing. This is not a bug — it is how the attention mechanism distributes probability mass across the context window. When you explicitly declare a behavioral mode by referencing a named instruction file, you are shifting the model's prior distribution over likely next tokens. The behavioral envelope changes without any retraining.

The critical constraint in the diagnostics prompt is MUST NOT do any actions or modifications. This is not politeness. It is load-bearing. Without it, many models — especially those optimized heavily for task completion — will collapse the investigation phase into an implementation. They will diagnose the issue and then helpfully fix it before you have had a chance to evaluate whether the diagnosis was correct. That is exactly the failure mode you are trying to avoid.

By separating the diagnostic phase from the implementation phase, you get something closer to a red team exercise than a development sprint. The model is not trying to be useful in the conventional sense. It is trying to be accurate.

Probing for Behavior vs. Triggering It

There is a meaningful distinction between asking an LLM to do something and asking it to explain what it would do and why. Diagnostics mode exploits that gap. You can surface hidden assumptions, expose conflicting instructions, and simulate edge cases — all without mutating any project state.

As for me, the most valuable use has been catching prompt assumptions I wrote months ago and forgot about. The model cites them back and precisely explains why it chose them.

Prompt Tuning as a Feedback Loop

The full workflow is a tight loop: enter diagnostics → interrogate → identify the misalignment → exit → apply change. Engineers will recognize the shape — it is the REPL, or unit test isolation. The difference is that the conversation context itself is the working memory, your prompts are like code files, and you're using the model as a debugger of its own behavior.

Edge Cases and Failure Modes

Mode bleed. Some models ignore the declaration and keep taking actions. Add an explicit confirmation step — "Confirm you are in diagnostics mode before proceeding" — which forces the model to process the constraint before it does anything else.

Context window exhaustion. Long diagnostic threads are expensive. If responses start sounding vague or recycled, the effective context is likely saturated. Keep sessions focused on one prompt file at a time; open a fresh context for distinct concerns.

Model-specific variance. Instruction-following models — Claude Sonnet, GPTs — respect the MUST NOT constraint more or less reliably. Some other models I've used may not. Also, some models tend to produce quite verbose diagnostics output which may be hard to analyze. I've seen this behavior with grok-code-fast.

DEV Community: Eugene

Two AI Prompts That Fixed My Git History

TL;DR

Video Walkthrough

A Real Pull Request With 209 Bad Commits

Prompt One: Turn the Diff Into a Commit

Prompt Two: Turn Commit History Into a Pull Request

Good Summaries Compound

How Do I Run This?

If Something Goes Wrong

Is This Lazy?

Your AI Coding Agent Is LYING When It Says "Done"

TL;DR

Video Walkthrough

The Agent Says "Done." The Repository Disagrees.

The Repository Needs to Define What "Done" Means

Classification and Hierarchy Are Important

The Reporting Part Also Matters

This Does Not Replace CI or Review

The Harness May Make It Harder

Start Small

Agent Diagnostics Mode — A Structured Technique for Iterative Prompt Tuning

The Problem with Prompt Tuning Today

Video Walkthrough: The Diagnostics In Action

Quick Start: Entering and Exiting Diagnostics Mode

Why This Works: The Architecture Behind the Mode

Why LLMs Respond to Mode Declarations

Probing for Behavior vs. Triggering It

Prompt Tuning as a Feedback Loop

Edge Cases and Failure Modes

Further Reading

Prompt Engineering and Instruction Design

LLM Attention and Context Behavior

Agent Instruction Patterns