Appendix - :grill-with-docs.mp4

Appendix: /grill-with-docs

When working with an agent on the same project repeatedly, you start to encounter a consistent problem. To understand it, we need to look at the sources of information available to agents when they're working in your codebase.

Information Sources Available to Agents

An agent typically has access to four main sources of information:

1. Current Code - The current commit of code that's accessible to the agent
2. Commit History - Historical information about how the code has evolved, allowing the agent to understand changes, find bugs, or track design decisions
3. GitHub/Issue Trackers - External information accessible via the GitHub CLI or other integrated tools (especially useful when commit messages reference issue numbers)
4. Your Messages - The instructions and context you provide directly

This all sounds comprehensive until you realize there are two critical questions that agents struggle to answer using only these sources.

The Questions Agents Can't Easily Answer

Why Did You Do It This Way?

The first difficult question is: why did you do it this way?

When there's an unusual trade-off visible in the code, agents need to understand:

• Why was this approach chosen over alternatives?
• Why was one technology selected instead of another?
• What constraints or considerations led to this decision?

An agent might theoretically find this information by digging through commit history and GitHub issues, but in practice, it's extremely difficult for them to piece together. Yet this understanding is crucial, because without it, the agent might recommend repeating the same pattern unnecessarily.

Architectural Decision Records (ADRs)