How to Give Your AI Agent Full Context Before Every Debug Session

The AI context window is not the problem. Modern models have 100,000 to 200,000 token windows — more than enough for any debugging session. The problem is that the context window starts empty every time, and filling it correctly is manual work that most developers skip.

When you skip it, you get generic answers. The AI doesn’t know what changed in the last three commits, what the logs say, or what the bug looked like when it happened. You spend the first few turns of the conversation establishing things you already know, and the AI spends those turns making plausible-sounding guesses about your specific codebase.

This is an entirely solvable problem. Here’s a system that fixes it.

What the AI actually needs

Before a debugging session, there are five categories of information that separate a useful AI from a generic one:

1. Recency: what changed
The most common cause of “it worked yesterday” bugs is a change that landed in the last few commits. git log --oneline -10 and git diff HEAD~3 take three seconds to run. They often point directly at the problem before you’ve described it.

2. Error context: what broke
Server error logs, browser console errors, crash traces. Pasting the last 50–100 lines of the relevant log file gives the AI the stack trace, timestamp, and request context it needs to make specific diagnoses rather than generic suggestions.

3. Project structure: what kind of code this is
A Laravel project has different conventions, log locations, and failure modes than a Node.js project or a Joomla site. The AI knows this, but you need to tell it which one you’re working with. The fastest way is to paste the relevant config file — composer.json, package.json, .env — which communicates project type, dependencies, and environment all at once.

4. Reproduction: what the bug looks like
Describing a bug in text is worse than showing it. If you have a screen recording or screenshot of the failure state, the AI can see what you mean rather than having to infer it. This is especially true for UI bugs and intermittent failures where the description is always incomplete.

5. Scope: what you’re trying to do
Are you fixing a bug, adding a feature, or doing a code review? The AI reasons differently depending on the goal. A bug fix session should end with a diagnosis and a patch. A feature session should end with an implementation plan. Stating this explicitly up front keeps the conversation on track.

Why developers skip this

The five categories above are obvious once you list them. So why do most developers dump a half-formed question into the chat instead?

Because assembling the briefing is tedious. You need to:

• SSH into the server and run tail -n 100 /var/log/apache2/error.log
• Switch to the local repo and run three git commands
• Find the last BugCapture report in ~/bugcapture-output/
• Format all of this into something coherent
• Paste it

That’s 5–10 minutes, every session, before you’ve typed the actual question. For a daily debugging workflow, that’s significant friction. Friction compounds: you do it once, notice the AI’s answers improve, but still don’t do it the next time because you’re in a hurry.

The solution isn’t willpower. It’s automation.

A structured briefing template

If you want to start with a manual approach, here’s a template that works:

# AI Briefing — [task name]

**Date**: [today]
**Scope**: [bug fix / feature / refactor]
**Project**: [path or repo name]

## Git context

**Status**
[output of: git status --short]

**Last 5 commits**
[output of: git log --oneline -5]

**Diff stat**
[output of: git diff --stat HEAD]

## Error log (last 60 lines)

[output of: tail -n 60 /path/to/error.log]

## Project config

[contents of package.json or composer.json]

## Recorded bug

[description or screenshot of the failure state]

## Objective

Analyze the context above and propose a solution for: [task name]

Paste this at the start of every session, fill in the sections that are relevant, and skip the ones that aren’t. The AI response quality difference is significant — you’ll typically get an actionable first response instead of three clarifying questions.

Automating the briefing

The template above works, but filling it in manually still takes time. There are two ways to automate it:

Shell alias approach
For local projects on a single machine, a shell function that runs the git commands and copies output to clipboard covers 80% of the work:

aibriefing() {
  local dir="${1:-.}"
  echo "## Git context"
  echo ""
  echo "**Status**"
  echo '```'
  git -C "$dir" status --short
  echo '```'
  echo ""
  echo "**Last 5 commits**"
  echo '```'
  git -C "$dir" log --oneline -5
  echo '```'
  echo ""
  echo "**Diff stat**"
  echo '```'
  git -C "$dir" diff --stat HEAD
  echo '```'
}

Add it to ~/.bashrc or ~/.zshrc. Run aibriefing /path/to/project | xclip -selection clipboard, paste into the AI chat.

This covers git context. It doesn’t cover remote logs, SSH connections, or bug recordings.

Dedicated tool approach
For workflows involving remote servers, multiple log sources, or bug recordings, a dedicated tool that assembles the full briefing is more practical. ContextForge does exactly this — it connects to SSH servers, tails log files, picks up BugCapture reports, runs the git commands, and formats everything into a single Markdown document you copy into any AI.

The practical difference is that a shell function stops at local git state. A tool that knows about your server configuration can pull error logs from staging, correlate them with the git diff from the same timeframe, and include the recording of the bug all in one step.

The 60-second workflow

With the right setup, a complete pre-session briefing takes under a minute:

1. Record the bug (30 seconds) — screen-record the failure state. Tools like BugCapture transcribe voice notes alongside the recording and save a .md report with a screenshot. Or just take a screenshot and add a note.

2. Generate the briefing (15 seconds) — open ContextForge (or run your shell alias), hit Generate. Git diff, server logs, and the bug recording are assembled automatically.

3. Start the session (15 seconds) — paste the briefing, state the objective, ask the question.

The AI receives a complete picture of the current project state. The first response addresses your specific situation, not a generic version of it.

What to put in the AI context window

A few principles for what goes in and what stays out:

Include: git log + status + diff stat, last 60–100 lines of the relevant log, the config file for the current project type, a description or screenshot of the failure state.

Exclude: full file contents of large files (use diffs instead), base64 image data (reference by description), logs from services not involved in the current issue, unrelated commit history.

Always include: the objective. One sentence stating what the session is for. Without it, the AI will infer the goal from the context, which works sometimes and fails badly other times.

The compounding effect

The immediate benefit of a structured briefing is a better first response. But the compounding effect is more significant: when the AI is well-oriented from the start, subsequent turns stay focused. You spend less time correcting misunderstandings, less time pasting additional context you should have included up front, and less time explaining why a suggested fix doesn’t apply to your specific setup.

A 5-minute investment in context preparation often saves 20–30 minutes of back-and-forth. At scale — daily debugging over weeks — the difference is substantial.

The AI context window is a resource. Pre-loading it with the right information before the session starts is the simplest high-leverage thing most developers can do to improve their AI debugging workflow.

---

The tools mentioned here are part of Machina — a free, open-source suite of AI developer tools for debugging workflows. No accounts, no cloud, no API keys. Everything runs locally.