Frequently Asked Questions About Priscila Andre's Comprehend-First AI Coding Skill
20 answers covering everything from basics to advanced usage.
// Basics
What does 'Comprehend First, Code Later' actually mean?
It means you prompt AI for understanding before you prompt it for output. In a large codebase, the biggest unlock from AI is comprehension, not generation — code flows naturally once your mental model is aligned. It reverses the common instinct to jump straight to code generation, treating understanding as the mandatory first phase.
What is the Research → Comprehend → Plan → Implement workflow?
It's a four-phase model that extends the commonly cited three-phase approach (Research, Planning, Implementation) by inserting a mandatory personal Comprehension gate between Research and Planning. The agent can do the research, but you must personally comprehend its findings before planning begins. Planning without comprehension produces slop code.
What is keynote code?
Keynote code is the positive counterpart to slop code — code that is intentional, well-understood, and of a quality you'd be proud to present publicly at a keynote. It's the professional standard the Comprehend-First skill aims for: every contribution defensible because you genuinely understand what it does and why.
What is an Agent Manager in this context?
Agent Manager is the creator's role descriptor for a developer who primarily orchestrates and steers AI agents rather than writing code directly. It reflects the shift in senior engineering toward comprehension, direction-setting, and quality control over raw implementation. Your comprehension becomes the steering wheel for the agents you manage.
// How To
How do I structure a good Catch Me Up prompt?
Use the format: [Role statement] + [Catch me up on X] + [specific clarifying question]. For example: 'I am a new contributor. Catch me up on how this repository works and clarify whether it simulates a Sentry envelope or intercepts a real one during tests.' The role calibrates depth, the mode targets the lens, and the question keeps it concrete.
How do I get the AI to output a visual instead of a wall of prose?
Explicitly request it: ask for a table, a flow diagram (ASCII or Mermaid), or a hierarchical organogram of component relationships. If the AI produces prose only, re-prompt with 'Summarise that as a table / component tree / flow diagram.' Visual structure accelerates comprehension significantly, especially for front-end and architectural questions.
How do I choose which exploration mode to use?
Match the mode to your gap: use Architecture for structural overviews, Convention for standards and naming, Feature for end-to-end implementation, Trace for following data or execution paths, Syntax for unfamiliar language patterns, Testing for how tests behave, and History for why something changed. You can combine modes — e.g. Architecture + Testing for onboarding to test infrastructure.
How do I audit my own AI usage patterns?
Review your actual prompt history and categorize prompts by intent — comprehension vs. generation vs. planning. Most engineers assume they're mostly generating code; the creator found 67% was comprehension and only 2% generation. Knowing your true pattern lets you invest deliberately in better comprehension tooling and prompts rather than optimizing the wrong thing.
// Troubleshooting
What do I do when the AI's answer contradicts what I already know?
Probe the discrepancy rather than dismissing either side. Contradictions between the AI's reading and your knowledge are often exactly where bugs or misalignments live. Ask targeted follow-ups until you resolve which is correct. This interrogation step is where real understanding gets built — treat comprehension as a dialogue, not a one-time read.
What if I still can't explain the code after using Catch Me Up?
Repeat the workflow with a more targeted exploration mode. If an Architecture pass left you unclear on a data flow, switch to Trace; if syntax is the blocker, use Syntax mode. The comprehension gate is mandatory — you must be able to explain in plain language what the code does and why before moving to planning.
Why does my AI agent keep going in the wrong direction?
Usually because you let it explore and act without verifying its understanding first. If you don't confirm what the agent found during research, it may plan and implement against a wrong mental model. Insert the comprehension gate: understand its findings, correct misreadings, then steer it into planning. Your aligned model catches drift during implementation.
Isn't comprehending first slower than just generating code?
It's faster overall. Skipping comprehension is the primary source of slop code, which costs far more in rework, debugging, and failed reviews. Comprehension takes seconds with AI and prevents wrong-direction agent runs. In the examples, engineers onboarded in days and shipped conflicted PRs the same day — outcomes that direct generation would have delayed.
// Comparisons
How does Comprehend-First compare to the standard three-phase AI workflow?
The popular three-phase model (Research, Planning, Implementation) lets the agent research and jump straight to planning. Comprehend-First adds a mandatory personal Comprehension gate between Research and Planning, arguing the agent doing research is not the same as you understanding it. This single insertion is what prevents planning on a flawed mental model.
How is this different from just reading the docs or asking a colleague?
Docs are often outdated and colleagues are busy or in other time zones. The AI acts as the cheapest senior engineer available — answering everything you'd hesitate to ask, at any hour, without waiting. Unlike static docs, it traces actual code, follows execution paths, and answers your specific question interactively with visual output.
How does this compare to letting an autonomous agent do everything end-to-end?
Full autonomy without a comprehension gate risks slop code and wrong-direction runs, because you can't steer what you don't understand. Comprehend-First keeps you as the pair-programmer and quality gate: the agent does research and implementation, but you personally comprehend and verify at the critical junctures, catching incorrect assumptions before they merge.
// Advanced
How do I apply Comprehend-First when reviewing a PR I have little context on?
Invoke Catch Me Up as a 'PR reviewer with partial context' using Feature + Trace modes: 'Walk me through how this feature works end-to-end and trace the data path this PR is modifying.' This gives enough contextual depth to perform a genuine review instead of a rubber-stamp approval, without interrupting the PR author.
Can I use Comprehend-First when returning to my own code after time away?
Yes — declare 'returning contributor after N weeks' and use History + Convention modes. You can recover why a component changed and the current replacement convention from commit history and lint rule changes in seconds, resolve conflicts with full context, and ship the same day instead of waiting for a colleague across time zones.
How do I turn Catch Me Up into a reusable team asset?
Store it as a local Markdown file that encodes the six exploration modes and the prompt structure, so any teammate can invoke it consistently. Standardizing the role + mode + question format makes comprehension repeatable across the team and lets you audit which modes get used most, informing where to invest in tooling.
What's the relationship between comprehension and steering the agent during implementation?
Your comprehension from earlier steps is your steering wheel during implementation. When the agent proposes something that contradicts your aligned mental model, you surface and resolve the conflict before merging. Without that model you can only consume output blindly; with it, you catch drift and incorrect assumptions in real time.
Does Comprehend-First apply to non-code comprehension too?
Its principles generalize to any complex system where your mental model is incomplete — infrastructure, data pipelines, or third-party integrations. The core moves stay the same: declare your context, pick a lens, demand structured output, interrogate the answer, and refuse to act until you can explain the system in plain language.