Frequently Asked Questions About Priscila Andre's Comprehend-First AI Coding Skill
22 answers covering everything from basics to advanced usage.
// Basics
What is mental model alignment in AI-assisted coding?
Mental model alignment is the state of having an accurate, internalized understanding of how a codebase or subsystem works before prompting an AI agent to act on it. Priscila Andre treats this as a mandatory prerequisite to planning and implementation. If your mental model is wrong or incomplete, the AI agent's output will drift, and you won't be able to catch errors during review. Alignment is achieved through the Catch Me Up exploration modes and verified through follow-up questioning.
What does it mean to be an agent manager instead of a coder?
Agent manager is Priscila Andre's self-assigned role descriptor—a developer who primarily orchestrates and steers AI agents rather than writing code directly. It reflects a shift in senior engineering work toward comprehension, direction-setting, and quality control over raw implementation. The key insight is that managing an agent well requires deeper understanding of the codebase than writing code yourself, because you need to catch when the agent goes wrong.
What is keynote code?
Keynote code is Priscila Andre's positive counterpart to slop code—code that is intentional, well-understood, and of a quality you would be proud to present publicly at a conference keynote. It is the quality standard to aim for in professional AI-assisted development. You achieve keynote code by ensuring you fully understand every change before it ships, using the comprehension gate in the Research → Comprehend → Plan → Implement workflow.
Can I use this skill with Claude, ChatGPT, or any AI assistant?
Yes. The Comprehend-First skill is AI-assistant agnostic. It works with Claude, ChatGPT, Gemini, Copilot Chat, Cursor, or any AI tool that can process code context. The skill is a structured prompting method, not a tool-specific feature. The key requirements are that your AI assistant can access or receive your codebase context and can produce structured output like tables or diagrams. Adapt the prompt format to whatever tool you use.
How long does the comprehension phase typically take?
For a focused question with a single exploration mode, 5–15 minutes including verification. For onboarding to a completely unfamiliar repository, plan for 30–60 minutes across multiple modes and rounds of follow-up questions. This is dramatically faster than manual code reading, which can take days for a large codebase. The time investment pays off immediately in implementation quality—you'll write correct code faster because your mental model is accurate.
// How To
How do I pick the right exploration mode for my situation?
Match the mode to your gap. Use Architecture when you don't understand the overall structure. Use Convention when you're unsure about coding standards. Use Feature to trace how a product feature works end-to-end. Use Trace to follow a specific data or execution path. Use Syntax when you encounter unfamiliar language patterns. Use Testing to understand what tests actually simulate vs. intercept. Use History to understand why something changed. You can combine multiple modes in one prompt.
How do I get the AI to output diagrams instead of walls of text?
Explicitly request structured output in your prompt. Ask for Mermaid diagrams, ASCII flow charts, component trees, or tables. If the AI defaults to prose, re-prompt with: 'Summarize that as a table,' 'Show me a component tree,' or 'Render that as a Mermaid flow diagram.' Visual structure accelerates comprehension significantly, especially for architectural and front-end questions. Most modern AI assistants support Mermaid syntax natively.
How do I verify the AI hasn't misunderstood my codebase?
Never accept the first response as ground truth. Ask follow-up questions that test the AI's understanding against what you already know—even partial knowledge. If its answer contradicts your expectations, probe the discrepancy. This is often where bugs or architectural misunderstandings live. Cross-reference the AI's output with actual code, documentation, or commit history. The verification step is where real comprehension is built, not in the initial summary.
How do I set up a reusable Catch Me Up prompt as a Markdown file?
Create a local Markdown file that contains the prompt template: a role declaration placeholder, the list of six exploration modes with brief descriptions, a slot for your specific question, and instructions to produce structured output. Store it in your project root or dotfiles. When you need to use it, copy the template, fill in your context, and paste it into your AI assistant. Update the template as you discover which formats work best for your codebase.
// Troubleshooting
What if the AI gives me wrong information about my codebase?
This is expected and is exactly why the comprehension gate exists. AI can misread complex, legacy, or unconventional codebases. When you spot an error, correct the AI explicitly and ask it to re-analyze with the corrected assumption. Use the discrepancy as a learning signal—it often highlights areas of the codebase that are poorly documented or counterintuitive. Never proceed to planning or implementation until you've resolved all contradictions between the AI's output and reality.
What if I still don't understand the codebase after running Catch Me Up?
Repeat steps 3–5 of the workflow with a more targeted exploration mode. If Architecture was too broad, try Trace to follow a specific execution path. If Feature-level understanding isn't clicking, try Syntax mode to understand unfamiliar language patterns first. Break your question into smaller sub-questions. The process is iterative—you may need two or three rounds before your mental model is solid enough to proceed to planning.
The AI agent keeps drifting during implementation—how do I fix this?
Agent drift during implementation means your steering isn't precise enough. Go back to the comprehension phase and sharpen your mental model of the specific area the agent is working in. When you re-enter implementation, give the agent more constrained instructions based on your verified understanding. Surface contradictions immediately—if the agent proposes something that conflicts with your model, resolve it before proceeding. Your comprehension is your steering wheel.
Is there a risk of over-relying on AI for codebase understanding?
The risk exists if you skip the verification step. AI can confidently present incorrect interpretations of complex or legacy code. Comprehend-First mitigates this by making verification mandatory—you must interrogate the AI's output, cross-reference it with actual code, and resolve contradictions. The framework is designed to make you the final authority on understanding, not the AI. Think of the AI as a research assistant whose work you always review.
// Comparisons
How does Comprehend-First compare to just reading the codebase manually?
Manual code reading is valuable but slow, especially in large or unfamiliar repositories. Comprehend-First uses AI to accelerate the research phase—scanning files, tracing paths, summarizing architecture—while keeping you in the driver's seat for actual understanding. The key difference is speed and structure: AI can produce a component tree or data flow in seconds that would take hours to map manually. But you still must verify and internalize the output yourself.
How is this different from just using GitHub Copilot or Cursor for code generation?
Copilot and Cursor default to code generation—they complete or produce code based on context. Comprehend-First explicitly separates comprehension from generation and treats comprehension as the primary use case (67% of prompts in Andre's audit). You can use Copilot or Cursor as the AI layer for Comprehend-First, but you change how you use them: asking for explanations, diagrams, and structural summaries instead of code completions. Generation only comes after comprehension is confirmed.
How does Comprehend-First compare to the standard Research-Plan-Implement workflow?
The standard three-phase workflow (Research → Plan → Implement) is missing a critical step. Comprehend-First inserts a mandatory personal Comprehension gate between Research and Planning. In the standard model, the AI does research and you move straight to planning—but if you haven't verified and internalized the research, your plan may be based on incorrect assumptions. The four-phase model ensures you personally understand the AI's findings before any planning begins.
// Advanced
How do I audit my own AI usage to find my comprehension-to-generation ratio?
Review your last 50–100 AI prompts and categorize each as comprehension (asking what code does, how it works, why it was written), planning (asking the AI to design an approach), or generation (asking for code output). Priscila Andre found her ratio was 67% comprehension, 31% planning, and only 2% generation. Knowing your actual ratio helps you invest in better comprehension prompts and workflows rather than optimizing for generation speed.
Can I use Comprehend-First for incident investigation and debugging?
Yes—incident investigation is one of the primary use cases. Use the Trace mode to follow the execution or data path related to the incident. Combine it with History mode to understand recent changes that may have caused a regression. Declare your role as 'incident responder investigating [symptom]' and ask the AI to trace the relevant code path. This builds the mental model you need to identify the root cause rather than just patching symptoms.
How do I use Comprehend-First when reviewing someone else's pull request?
Invoke Catch Me Up with role = 'PR reviewer with partial context,' select Feature + Trace modes, and ask the AI to walk you through the end-to-end feature the PR modifies and trace the data path being changed. This gives you enough contextual depth to perform a genuine review rather than a rubber-stamp approval. You avoid interrupting the PR author and can review asynchronously regardless of time zones.
Does Comprehend-First work for small codebases or only large ones?
It works for any codebase where your mental model is incomplete, regardless of size. For small codebases, you may only need one exploration mode and a single round of questioning. For large, long-lived codebases, you'll likely use multiple modes across several sessions. The value scales with codebase complexity, but the principle is universal: understand before you change. Even a small repo can have non-obvious conventions or test patterns worth comprehending first.
What if I'm the only developer and I already know the codebase well?
Even solo developers benefit from Comprehend-First when returning to code after time away or when exploring unfamiliar dependencies. Use History mode to remind yourself why past decisions were made. Use Architecture mode after significant refactors to verify your mental model still matches reality. The skill also helps when you're about to integrate a new library or service you haven't used before—treat the dependency's codebase as unfamiliar territory.
Can I combine Comprehend-First with test-driven development?
Absolutely. Use the Testing exploration mode to understand existing test structure before writing new tests. The comprehension phase reveals what tests actually simulate vs. intercept, what coverage exists, and what conventions are followed. This prevents you from writing redundant or incorrectly structured tests. Once you understand the testing patterns, you can plan your TDD cycle with accurate knowledge of how to fit new tests into the existing framework.