A few weeks later I came back with proper time. Wrote instructions. Specified duration, format, on-screen elements. The output mostly ignored them. Tried again. Same thing. I was a few minutes from dropping this article.

Then NotebookLM surprised me with this one. Take a look.

Honestly, not bad, right? Style. The Netflix logo woven into the staging. Animated transitions, generated charts, stock-footage cuts that fit the narration. It felt like someone had art-directed it.

That’s what’s possible when the brief lands. Most briefs don’t. One in ten does.

Cinematic is a creative tool, not a prompt-and-go tool. Write it like a film brief, not like a chat message.

Here’s the rough flow that produces a generation worth keeping.

Three sections from here to your own working video:

1. Learn from my experiments: what I tested and where it broke.

2. Make your first cinematic video: the click-by-click and the five patterns that worked.

3. Apply it to real work: five product-work use cases plus when to play these in a meeting.

Press play.

Learn from my experiments

The setup: one PRD, +10 cinematic videos

I didn’t go far for the topic. I’m reusing the same fictional Netflix feature I built around in my previous post on visual storytelling:

The pretend feature is “random shuffle.” One button on the Netflix home screen that picks a comfort show and starts playing it instantly, so you don’t lose another twenty minutes scrolling at 11pm. I wrote a PRD for it. Last time, I turned that PRD into a visual library using Nano Banana Pro and a voice note. This time: same PRD, same notebook, generating videos instead of static images.

NotebookLM offers three video formats. The differences matter.

• Cinematic (New!): A stitched composition of animated clips, generated images, stock-footage cuts, and on-screen graphs, with a visual style that changes per generation. The video at the top is one.

• Explainer: A structured, comprehensive overview that connects the dots within your sources. Single voice, single visual style, more linear.

• Brief: A bite-sized version of the “explainer”. Same single voice and recognizable style, just shorter. Useful when you want a quick summary, not a vibe.

To feel the difference, here’s a “brief “generation from the same workspace.

Cinematic is the one I came to test. Same source, very different output per generation.

I generated more than ten cinematic videos with different instructions, varying the framing, the audience, and the visual style each time. The list piled up in the studio panel.

To see every prompt I tested, open the workspace, click any video, hit the “…” menu, and pick “show prompt”. The full instructions for that generation appear on the right.

Open NotebookLM

Honest summary of the batch: V04 is my favorite, the one at the top. V05 is also nice, the kind you’d ship if V04 didn’t exist. The other eight are okay. Animated graphs, on-screen diagrams, transitions that work. Maybe I’m being too demanding, but they’re not at the same level. Not bad videos. Just okay ones.

You’ll find the full instructions behind the video further down, plus a template to inspire your own.

The honest fight: three constraints to know

I want to be honest about three constraints I hit. They set the rules of the game.

1. Instruction-following: partial. Specify duration, on-screen elements, narrator register, and the system honors maybe half of what you asked for. Sometimes less. You write a brief; the model interprets. The output is a mix of what you said and what the model decided to do anyway.

2. The quota: punishing on Pro. Two cinematic generations per day on AI Pro. Twenty on Ultra. You’re probably on Pro. Two shots before tomorrow. A bad brief costs you the whole day.

3. No feedback loop, at all. You can’t say ”redo this but tighten the third beat.” Each generation is one-shot. If you don’t love it, you scrap it and start over with a new full brief.

That’s what made V04 feel lucky. None of these are reasons not to try cinematic, they’re reasons the method has to be deliberate.

Make your first cinematic video

Set up your first generation

The clicks are the easy part. Five steps to a generation in flight.

1. Create a new notebook. Go to notebooklm.google.com. Click “New notebook”.

2. Add one focused source. One. The reflex is to dump every PDF, slide deck, and meeting transcript into the notebook. More context ≠ better output. A PRD. A brief. A one-page strategy doc. A research summary. Pick one. If you really need several, merge them into a single document and read every line: keep only what’s useful, still valid, and meant to be there.

3. Open Cinematic. Studio panel → Video overview tile →small arrow. Three formats appear. Pick cinematic.

4. Write your instructions. The field is labeled, exact wording, ”How would you like the video to be customized?” Style, structure, central metaphor, narrator register, brand hooks, visual style cues. Everything goes here.

5. Generate. Wait. Fifteen to thirty minutes. NotebookLM doesn’t block the tab. The mobile app sends a push when it’s ready, worth installing for that reason alone.

The clicks are easy. The instructions are the work.

Write instructions that land

Five patterns showed up across V04 and V05. Here they are, with one example each, pulled from the briefs that produced both videos.

1. First-person setup. Tell the system who you are, who you’re presenting to, and the feeling you want in the room. Specific, not abstract.

I’m the PM who wrote the random shuffle PRD. I’m walking the engineering team through the wireframes at sprint planning, and I want it memorable, not sleepy.

2. One bold genre or format metaphor. Game show. Sports broadcast. Movie trailer. Late-night talk show. The metaphor gives the model permission to leave its default explainer voice and produce something with actual style.

Pitch the wireframes as a 1980s prime-time TV game show called “spin to unwind.”

3. A named central scene with brand woven in. The brand belongs in the first paragraph, not as an afterthought.

Behind them, a velvet-curtain wall is studded with Netflix show tiles. Friends, Seinfeld, Brooklyn 99, Breaking Bad. Each glowing under studio spotlights.

4. Segmented beats with PRD-element labels. This is the trick. Each beat of the metaphor gets a name and a label pointing at its source-document equivalent in parentheses. The model uses both.

The buzzer (a.k.a. the random shuffle button): A gigantic red buzzer sits center stage. Dramatic close-up. The audience gasps.

5. A tone directive, a sign-off, a visual style paragraph. Tone translates content into the metaphor’s currency. Sign-off lands the metaphor. Visual style is 8 to 12 comma-separated phrases on palette, lighting, typography, voiceover, and sound, appended to the same block.

Tone: Treat every wireframe element like a game-show set piece.

Sign-off: Press the button. Win the night.

Visual style: 1980s American prime-time game show, neon-accented set, chunky Las Vegas-style typography, studio spotlights, velvet curtains, lower-third prize graphics in flashing yellow...

The reusable template. Strip out the Netflix specifics and you have a fill-in-the-blanks shape that works for any source artifact and any audience.

I’m the [role] who [authored the source artifact]. I’m presenting [the artifact] to [audience] at [occasion], and I want the room to feel [the desired register].

Deliver it as [a bold genre or format metaphor]. [Two sentences naming the central setting, with at least one brand visual hook woven in.]

The beats:

- [Beat 1] (a.k.a. [source element]): [vivid scene + how the narrator frames it].

- [Beat 2] (a.k.a. [source element]): [same shape].

- [Beat 3] (a.k.a. [source element]): [same shape].

- [Beat 4] (a.k.a. [source element]): [same shape].

Sign-off: [one closing line that lands the metaphor].

Tone: [three-word descriptor]. No irony. Treat [the source content] like [the metaphor’s currency].

Visual style: [8 to 12 comma-separated phrases on palette, lighting, typography, graphics, voiceover, sound, with 1 to 2 brand-specific hooks].

The patterns in action: V04 in full. Here’s the actual instructions block that produced the video at the top. Read it as a showcase of how the five patterns play out together, not as something to copy. The template above is your starting point.

You are the product manager who wrote the PRD for Netflix’s random shuffle feature. You’re walking the engineering and design teams through the low-fidelity wireframes so the whole room sees the interaction flow before sprint planning, and you want it memorable, not sleepy.

Pitch the wireframes as a 1980s prime-time TV game show called “spin to unwind.” The host wears a sparkly navy suit, smiles too hard, and narrates every interaction like a big reveal. Tired Tom is tonight’s lucky contestant.

- Segment 1: The wheel (a.k.a. the home screen). The host stands in front of a giant spinning wheel made of Netflix tiles. “Behind each of these tiles, Tom, is another agonizing decision. But we’ve got a better way.”

- Segment 2: The warm-up round (a.k.a. onboarding). The host walks Tom through three quick onboarding taps with studio applause after each one. “Now choose your three favorite sitcoms, Tom. Lock ‘em in!”

- Segment 3: The buzzer (a.k.a. the random shuffle button). A gigantic red buzzer sits center stage. Dramatic close-up. The audience gasps as Tom hovers. Slam cut when he presses. Lights go wild.

- Segment 4: The prize (a.k.a. the playback screen). The Friends opening credits begin. Confetti falls. Tom lifts a trophy shaped like a remote control.

The host narrates wireframe elements as game-show set pieces, not as UX components. Each step gets a studio sting, a lower-third prize-value graphic, and at least one audience reaction shot. Around 2 minutes total.

Visual style: 1980s American prime-time game show, neon-accented set, chunky Las Vegas-style block typography, studio spotlights, enthusiastic announcer voiceover, orchestral stings between segments, lower-third prize graphics in flashing yellow, velvet curtains, audience reaction shots.

This worked once. Plenty of close variants didn’t. The five patterns above are your best shot at finding your own working version.

Iterate on what almost worked

No native feedback loop in NotebookLM. You can’t comment on a generation and ask for a tweak the way you would in chat. Each Cinematic generation is one-shot. Default move: scrap it and start over with a new full brief.

There’s a workaround I haven’t tested on cinematic yet. I think it’s the path forward when you land a near-perfect generation.

Download the video. Add it back to the notebook as a source. NotebookLM accepts video files. Once it’s in there, launch a new generation that starts from that source video with small adjustments. The kind of feedback you’d give:

• Change one specific sequence and keep the others as they are.

• Swap a specific line of narration for new wording.

• Restructure the order of the beats.

• Adjust the visual style or palette of one segment.

I haven’t run this on cinematic, quota burned. I tested the same trick on slides for the slides post a few months ago, and it worked surprisingly well:

Same idea: feed the system its own previous output as a starting point, then steer.

It’s not officially documented. It emerged from how NotebookLM treats video as a valid source format. If you try it on cinematic before I do, tell me what you find.

Apply it to real work

Pick from five use cases

With only two cinematic generations per day on AI Pro, the question is which moments at work are worth one of your shots.

Five places this format genuinely pays off. Each comes with a one-line snippet to spark your own brief.

1. Pitch the strategic case to leadership. Quarterly reviews, board prep, exec narrative. Makes the bet feel like a story, not a slide deck.

Deliver it as an ESPN SportsCenter broadcast. The anchor calls activation, watch-through, and retention like championship stats.

2. Walk the dev team through the wireframes. Sprint planning, design reviews, kickoff sessions. Forces the room to pay attention to a UI flow they’d otherwise zone out on.

Pitch the wireframes as a 1980s prime-time TV game show called “spin to unwind.” A host in a sparkly navy suit narrates every interaction like a big reveal.

3. Brief marketing on the campaign positioning. Before anyone writes a line of copy. Marketing writes copy after feeling the trailer, not before.

Deliver it as a summer-blockbuster trailer drop. A booming voiceover, a hundred-foot Netflix marquee, lens flares across every brand reveal.

4. Kick off cross-functional research with design. Surface the user pain before the team designs around it. Each viewer persona becomes a guest with a story.

Pitch it as a late-night talk show. Three guests walk through the curtain, each tells a 20-second story of last night’s viewing chaos.

5. Open the all-hands with the long-term vision. Town hall, off-site, Product Week. Makes the long-term bet feel inevitable, not abstract.

Render it as a prestige-drama teaser. Somewhere between Black Mirror and Stranger Things in tone. Serious. Cinematic. Slightly melodramatic.

Use it before the meeting, not in it

These videos don’t belong inside most meetings. A working meeting is an exchange between people. A generated video is a broadcast. Stopping a discussion to play two to four minutes of a robotic AI voice saying exactly what the person could have said is awkward. The two don’t mix.

The exception is broadcast moments: all-hands, off-site keynotes, product week openers. The room has already accepted that one person is going to talk at them. A 2-minute cinematic video as the cold open lands hard. That’s exactly why use case 5 above is the one meeting where I’d press play in the room.

For every other kind of meeting, these videos earn their place before the meeting starts. Drop the link in the calendar invite. Send it the morning of, in a Slack message, or as the first item in a pre-read packet.

The audience arrives with the picture in their heads, with formed opinions, with sharper questions. The meeting becomes the discussion the picture provoked, not the picture itself.

That’s where this format unlocks something a static deck doesn’t: a shared visual frame the room arrives with, instead of one you spend the meeting building from scratch.

Try it and tell me what landed

One in ten generations produced something I’d share with a team. The other nine taught me what a working brief looks like.

The patterns from V04 and V05 are the closest thing I have to a recipe. Recipes for creative tools are aspirational, not deterministic. Plenty of close variants of the same brief produced forgettable output.

NotebookLM recently added a per-slide feedback feature for slides. You comment on a single slide, and the system regenerates that slide with the comment applied. If that pattern lands on cinematic, the workaround above becomes unnecessary, and real iteration becomes possible inside the tool. Worth checking back in a few months.

In the meantime: try it on something you’d otherwise put in a deck. Tell me what landed. If you crack a different pattern that works, send the instructions, I’ll share it in a follow-up post.

I caught the bad ones instantly. The AI didn’t flag them as risky. It produced them with the same tone as the good ones. The point: this is competent junior output that still needs an expert in the room. What happens to someone who isn’t?

The same thing happens with code, only worse. The output looks competent. The notebook runs. The accuracy number sounds plausible. And you ship a model that’s been cheating on the test the whole time, because you didn’t have the vocabulary to spot it. It’s a pattern I’ve seen repeatedly, and the project we’re about to walk through illustrates it better than any abstract example could.

AI amplifies what you already know. Your expertise, and your gaps. That’s why learning still matters even when the AI writes the code, and it’s also why learning has never been easier, because the same AI that exposes the gaps can be the patient tutor that closes them.

Five sections to get from there to a working model on GitHub:

• Why I changed my mind about PMs and code

• The build, narrated from the inside: from a Kaggle dataset to a working model, with one classic ML mistake caught along the way

• The best practices for using an LLM as your tutor, plus what it actually feels like

• What AI changes about learning, ten years apart, same author, different experience

• Your first project, this evening

Let’s start with what I believed a year ago, and how the year proved me wrong.

Why this matters

Two objections come up every time I talk about this with another PM. They were my objections too, word for word, until a year ago.

• Objection 1. PMs work with developers by design. Discovery, specs, handoff. No one expects a PM to write production code. That’s the job description.

• Objection 2. AI coding tools exist. A few prompts and you have a working prototype. So why spend time learning a skill the machine already does?

Short answer to both, before the long version:

• The job description is shifting toward people who can build, not just specify.

• AI amplifies what you already know, including the gaps.

The PM who learns to code becomes more autonomous, not redundant. The PM who outsources to AI without understanding what it produces becomes more dependent, not less. I held both objections anyway until a year ago. The rest of this section is how the year answered them.

The conversion: what I thought, and what actually changed

I’ve been working with AI for ten years, well before LLMs. The unglamorous kind: fraud detection in the public sector, classical machine learning, the kind nobody mentioned at dinner parties. When LLMs arrived and suddenly everyone was an “AI expert” from one ChatGPT prompt, something felt off. I needed to prove something more durable than prompt fluency.

I enrolled in a one-year evening program at the Sorbonne. Real projects, actual rigor. My mindset going in: give the minimum, collect the diploma, move on. I told myself product people don’t need to code. I believed that.

Something strange happened. The code wasn’t the surprise. Writing Python is mechanical, and AI handles most of it. What was surprising was the development process itself. Going from a notebook on a laptop to something running in production. Monitoring whether a model is drifting. Routing predictions in real time. Managing data across knowledge graphs. All those questions about how things move from theory to actual production turned out to be more interesting than I’d expected.

Then a second shift. I started seeing the same process in PM work. We produce ideas, specifications, prototypes too. That workflow benefits from the same rigor: version control, structured checkpoints, outputs that can be reviewed and improved. Product decisions are constrained and unlocked by what’s technically feasible. PMs who understand the development side don’t just communicate better with engineers. They make different bets, earlier and more confidently, with fewer surprises in sprint review.

The Git and GitHub mindset shift came last and landed hardest. I started seeing every project as a GitHub project. Not just code. Everything. Every commit is an undo button, so experiments become cheap. Every README is a spec for whoever reads it next, human or AI. Every public repo is portable proof of work, the modern PM portfolio. Every conversation with an engineer suddenly has a shared vocabulary, which makes meetings shorter. That mental shift is worth more than the Python syntax.

AI amplifies what you already know, including your gaps

The Gemini moment from the intro is the principle in one scene. AI enforces bad habits more efficiently. It didn’t invent bad discovery questions. It amplified the prompter’s lack of domain knowledge and produced them at scale, with confidence.

The coding parallel is direct and uncomfortable. If you don’t know what clean, correct code looks like, AI produces messy code and you won’t catch it. You’ll think it worked. You’ll ship the leak. You’ll trust the accuracy number without knowing it was built on a cheating feature. All of that happened in this build. It was a second AI session, not the first, that caught it.

The synthesis: you don’t need to learn to code from scratch so you can replace the AI. You need enough vocabulary to audit what it produces. That’s what autonomy looks like in 2026. Not prompting faster, but catching errors earlier and asking sharper questions.

After one year, that vocabulary includes data leakage, overfitting, class imbalance, training versus test accuracy, feature importance versus SHAP values. Each term is a filter. AI output now has to pass through those filters before I trust it.

The future belongs to people who can think about the future and build in the present. The PM role isn’t disappearing. It’s expanding toward something between product management, design, and development. This is the right time to close the gap, because the tools to do it have never been more accessible.

Use an LLM chat, not a coding tool

Start with the popular narrative. There’s a wave of YouTube videos and op-eds claiming that learning with AI makes people shallow or lazy. Brain-rot, dependency, the death of expertise. Pick the framing. It’s true if you let it. It’s false if you don’t. The tool isn’t the problem. The shortcut is the problem.

You’ve almost certainly used an LLM to learn something already. Summarizing a long article, formalizing messy notes, debating a concept, getting a 24/7 explainer for anything you were curious about. That’s not the new thing. The new thing is that code is one of the highest-leverage things to learn this way, and almost nobody is doing it right.

It has never been easier to learn coding from scratch. Ten years ago, the alternatives were a 30-hour video course and a Stack Overflow thread that might get answered tomorrow. Today it’s a one-on-one tutor that explains every line on demand, never gets impatient, and adjusts to your pace. The blocker for most people isn’t whether AI can teach code. It’s that they’ve been pointing AI at the wrong job.

The wrong job is the AI that generates code instead of teaching it. Claude Code, Cursor, vibe-coding agents. They produce too much output too fast. You can’t follow. You can’t ask. The notebook works because the machine did everything, and the moment something breaks in front of someone, you discover you didn’t actually learn anything. The output looks like productivity. The reality is dependency.

Important nuance: this isn’t an argument against code-agent tools as a category. It’s an argument about when to use them. When you’re learning, stay in chat mode and stay in the loop. One step, confirm, ask, next step. When you’re delivering work you already understand (you know what good code looks like, you know the failure modes, you can read what the agent produces and catch what’s wrong), switching to a code agent is exactly the right move. The trap is using a code agent to learn. The win is using one when you no longer need to.

The rule that flips the LLM from code generator to patient instructor, set at the very start of the conversation: “Explain before every command. Wait for my confirmation before the next step.” That single sentence is the difference between a notebook that teaches you and a notebook that teaches the AI.

For a PM, the deliverable was never the notebook. It’s the vocabulary you can use in the next sprint review. A model you can explain is one you can defend in a meeting, challenge when the numbers look off, and redirect when the team is asking the wrong question. The patient-instructor approach builds that. The code generator skips it entirely.

The project

From data to a working model: the workflow

If you want to follow this build yourself, step by step, the complete guide is here on Google Docs. The final notebook is at github.com/adamfaik/churn-prediction. Open it and you’ll see every cell, every chart, and every commit.

Why churn prediction. Understanding how the product is used, or not used, is one of the core jobs of a product person. Why are users leaving? Which segments are at risk? What’s the gap in lifetime value between cohorts? These are the questions a PM brings to every retention meeting.

Before LLMs, the answer came down to two slow paths. Either I filed a ticket with the data team and waited two or three weeks for a chart in a slide deck, readable but not mine and not something I could iterate on. Or I tried to learn the analysis myself: a 30-hour Udemy course, half-finished side projects, no one to ask when something broke. Both paths were inefficient enough that most decisions still got made on intuition and dashboard glances.

There’s now a third path, and it’s the entire reason this article exists. The PM picks a real dataset, opens an LLM chat, and walks through the analysis themselves in an evening. They probably won’t ship the model to production. That’s not the point. They bring sharper questions to the next retention meeting, having seen the data with their own eyes and built a working model on it. This is the autonomy the section above promised.

The workflow itself, before zooming into the build. The build guide for this project distills four meta-steps that make the whole thing work. They’re the workflow of discussing with the LLM, not the data-science workflow itself. The seven machine learning phases came from the LLM during step 2 and are narrated phase by phase in the next sub-sections.

1. Set up your workspace once. VS Code with the integrated terminal, Python and Jupyter inside it. Not the focus, but it has to exist before the rest works. Thirty minutes the first time, never again.

2. Hand the LLM your problem and ask for a plan. Don’t ask for code. Paste the dataset description, your full context, and the kind of beginner you are. What comes back is a multi-phase plan with checkpoints. For this build, seven phases of classic ML.

3. Work the plan one phase at a time, with the LLM as patient tutor. Inside this step lives a five-move loop that runs once per phase: expand the phase into actions, do one action, share the result back (success or failure), ask the deep-dive “why” question, verify the checkpoint. Push back when the plan misses something you know is important.

4. Get a second opinion before declaring done. Open a fresh LLM session with no shared history, attach the GitHub repo, ask “any feedback?”. Two AIs disagreeing is the highest-value moment in any build, and in this project it’s where a data leakage that the tutor never spotted got caught.

For PMs specifically: this isn’t a one-off ritual for the churn project. It’s a portable workflow that runs on any technical topic: the analytics question you’d normally file with the data team, a feature spec where you need to understand a backend constraint, a competitive analysis where you want to reverse-engineer how a tool works. Same four steps, same five-move loop. The churn project just happens to be where this article shows it in action.

Set up your workspace once

Before any conversation with the LLM can produce code that runs, the workspace needs to exist. The setup is light: three installs, one folder, one verification command. The full step-by-step (with screenshots, troubleshooting notes, and Mac/Windows variants) lives in the reader guide.

• Python, downloaded from python.org. macOS and Windows installers are straightforward. On Windows, the only must-do is checking “Add Python to PATH” during install, otherwise the terminal won’t find Python later.

• VS Code, downloaded from code.visualstudio.com. It’s the editor where the notebook will live. Two extensions get installed inside it from the Extensions panel on the left sidebar: the Python extension (by Microsoft) and the Jupyter extension (by Microsoft).

• A project folder created on disk wherever you keep projects. This build called it churn-prediction. VS Code opens it via File → Open Folder. The sidebar shows the folder name at the top and an empty tree below, the canvas before the first file.

Once the folder is open in VS Code, the integrated terminal opens at the bottom of the window via View → Terminal (or Ctrl + `) and is already scoped to the project folder. From here on, every terminal command runs inside this panel. No separate terminal app, no confusion about which directory you’re in.

A quick verification: python3 --version in the integrated terminal. If it returns Python 3.11.x or newer, the workspace is ready. The whole setup takes about 30 minutes the first time and is reusable across every future project. Accounts you’ll need by this point: GitHub (free), Kaggle (free), and an LLM chat (Claude.ai or equivalent). Detailed install steps for Mac and Windows live in the reader guide.

That’s it for setup. The next conversation is the one that turns this empty workspace into a project.

Hand the LLM your problem and ask for a plan

With the workspace ready, the first conversation that matters: the build starts at the dataset. The IBM Telco Customer Churn dataset on Kaggle is the canonical first ML problem. 7,043 customers, twenty-one attributes, one binary target (did they cancel?). Small enough to finish in an evening, big enough to teach real lessons.

Ctrl+A, Ctrl+C the dataset description and column list. Open Claude.ai in a new browser tab. Paste it in along with full context: VS Code open, Python installed, first project, want to learn.

What comes back is a plan, not code. A 7-phase plan with goals and checkpoints per phase. The first instinct is to start executing immediately. The right move is to read the whole thing end to end first and ask “why” on anything that’s unclear before touching a keyboard.

The plan that came back for this build (yours will look similar): set up the project (libraries, dataset, notebook) → load and look at the data → clean what’s broken → explore patterns → prepare for modeling → train and compare models → interpret and ship. Seven phases, each with a checkpoint, each one ready to expand into specific actions when its turn comes.

The simple framing matters. You don’t ask the LLM to write a churn model. You ask it to walk you through how to build one. Same tool, completely different output. Code without learning versus learning that produces code.

Work the plan one phase at a time

Now the plan turns into a working model. Each phase runs through the five-move loop introduced above: expand into actions, do one action, share the result back, ask the deep-dive “why” question, verify the checkpoint. Six phases of work, narrated in order.

Phase 1: finish the workspace setup with the LLM

The LLM’s Phase 1 isn’t “install Python.” That’s already done. It’s the first concrete output the project needs: a requirements.txt file. The LLM introduces it as “a shopping list for Python libraries.” Eight dependencies, each pinned to a specific version so the project behaves the same way in a year.

One install command later (pip install -r requirements.txt), all eight libraries are on the machine.

A pushback that became the first meta-lesson. The LLM’s plan never included GitHub versioning. Phase 1 was setting everything up locally, with nothing saved anywhere else. I stopped mid-phase and said so plainly: “I want to save to GitHub from the start, not just at the end.” Claude adjusted immediately: “Great instinct, that’s exactly what real developers do.” The plan was a draft. It was always meant to be reshaped.

Two small VS Code rhythms learned during this phase. A dot next to a filename in the tab bar means unsaved. Save before every commit, always. After the first push, the source control panel lights up with file colors: green for new files never tracked before, orange for modified files. Both disappear after a clean commit. The empty source control panel becomes the live “nothing waiting” status.

Phase 1 ends with the dataset downloaded into the project folder, the first Jupyter notebook (churn_analysis.ipynb) created and open in VS Code, and the first commit pushed to a fresh GitHub repo.

Phase 2: load and look at the data

One line of Python and 7,043 customer records appear in a notebook cell. The LLM calls a DataFrame “a spreadsheet but with superpowers.” Every row is one customer, every column is one thing known about them. The output shows (7043, 21): 7,043 customers, 21 features. That number becomes the baseline everything is measured against.

The LLM’s checkpoint after Phase 2: “You’ve loaded 7,043 customer records, confirmed 21 columns, and seen the first few rows. Say the word and we move to Phase 3, where we clean what needs cleaning.”

Checkpoints like that became a rhythm. Each one confirmed what was done, named the state of the data, and bridged to what was next. They made it possible to stop for the day and pick up the next morning without losing the thread.

Phase 3: clean what’s broken

The data is messier than it looks. The TotalCharges column appears to contain numbers but is actually stored as text, a quirk of how the CSV was exported. Converting it reveals 11 rows with blank values that quietly get dropped. 7,043 becomes 7,032. This is the reality of working with real data: the first thing you do is clean what shouldn’t need cleaning.

A small but important move in the same phase: the Churn column gets converted from “Yes/No” to 1/0. Models can’t read text. Anything binary becomes a number before going further.

After Phase 3, zero missing values. The LLM’s checkpoint: “You independently caught the data leakage concept. That’s genuinely impressive for someone on their first project.” (More on what that means in the second-opinion section below.)

Phase 4: explore the data

EDA, Exploratory Data Analysis, is the habit of looking at the data before doing anything with it. Not modeling, just looking. Five or six charts.

The first chart: overall churn rate. 73.4% stayed, 26.6% left. That 73.4% number matters more than it looks. It’s the naive baseline. A dumb model that predicts “no churn” for everyone would be 73.4% accurate by default. Any model has to beat that to be worth anything. Accuracy alone is therefore a terrible metric on imbalanced data, a lesson that comes back hard in Phase 6.

The chart that changes everything is the second one: churn by contract type. Month-to-month customers churn at 42.7%, one-year contract customers at 11.3%, two-year customers at 2.8%. The LLM’s note: “As a PM, this is the chart that will make you want to immediately call your retention team.” Month-to-month customers churn at 15 times the rate of two-year customers. That’s not a pattern. That’s a business decision waiting to be made.

A third chart: churn by tenure.

47.7% of customers churn within their first 12 months. After five years, the rate drops to 6.6%. Year one is the critical retention window.

A fourth chart compares monthly charges. Higher-bill customers churn more. The LLM uses this to surface a critical PM lesson: ”Correlation isn’t causation.” This chart raises the question, it doesn’t answer it. Do they leave because the bill is high, or are high-bill customers structurally more likely to leave for other reasons? That distinction is exactly the kind of thing AI can’t tell you on its own. You have to bring the framing.

The LLM’s checkpoint after Phase 4: “You have 5-6 charts that tell a clear story about what drives churn. You could explain it to a colleague without showing any code.” That’s the sentence that makes a PM feel like a data person for the first time.

Phase 5: prepare the data for the model

Data needs to be reshaped before a model can read it. ML models only understand numbers. They can’t process text like “Month-to-month” or “Fiber optic.” The solution is one-hot encoding. The LLM’s explanation: “You can’t say DSL=0, Fiber=1, No service=2 because that implies Fiber is mathematically twice DSL, which is nonsense. One-hot encoding gives each category its own 0/1 column.”

Then the train/test split: 80% to train, 20% hidden until the end. The LLM’s metaphor: ”like an unseen exam. If you test the model on data it trained on, it looks brilliant and is useless on real new customers.” The 80/20 split is stratified, which means the original churn rate (26.6%) is preserved in both halves. Without stratification, the test set could randomly end up with 15% churners or 40%, and the reported performance number would be misleading. Stratification keeps the test honest.

A subtle but critical moment: numerical columns get scaled. Without scaling, a tenure value of 72 dominates a SeniorCitizen value of 1 just because the number is bigger. The order matters: scale after the split, not before, and only learn the scaling factors from training data. The LLM’s framing: “fit on training, then apply to test, never the other way around.” A few exchanges earlier I’d instinctively asked whether scaling should happen before or after the split. Claude’s reaction: “You’ve just independently discovered one of the most important concepts in machine learning.” First encounter with data leakage thinking, well before the formal catch in the next section.

Phase 6: train and compare three models

Logistic Regression is the simplest baseline. It draws a straight line through the data, very explainable. Random Forest is a committee of decision trees. The LLM’s metaphor: “500 different analysts each studying the data independently, then going with the majority opinion.” And XGBoost, with the metaphor that’s actually worth remembering: ”where Random Forest builds trees independently and votes, XGBoost builds them sequentially. Each new tree specifically focuses on fixing the mistakes the previous trees made.”

Five metrics, set up before any model trains. Each answers a different question:

• Accuracy. Of all predictions, how many were right? Misleading on its own here, since the naive “predict no churn for everyone” already hits 73.4%.

• Precision. Of the customers the model flagged as churners, how many actually churned? Optimize for precision when false alarms are expensive (wasted retention spend on people who weren’t leaving).

• Recall. Of the actual churners, how many did the model catch? Optimize for recall when missing a churner is expensive (a customer who could have been saved). For most retention teams, recall wins.

• F1 score. The balance of precision and recall in one number, useful when both matter.

• ROC-AUC. How well the model separates churners from stayers across every possible decision threshold. 1.0 is perfect, 0.5 is a coin flip. The gold standard for churn models because it doesn’t depend on where you draw the line.

The confusion matrix visualizes all of this in a 2x2 grid: true positives (correctly flagged churners), false positives (flagged but stayed), true negatives (correctly identified stayers), false negatives (the churners the model missed). One glance tells you what kind of mistakes the model is making, and which kind your team can afford.

The overfitting catch came right away. Random Forest reached 100% accuracy on training data but only 79% on the test set. The LLM named it immediately: “Classic overfitting, the forest memorized the training set but didn’t generalize.” Logistic Regression, the simplest model, held steady at 80% on both. XGBoost hit 74.9% accuracy but 71.4% recall, the best at actually catching churners. That’s the one that got chosen.

For a PM, this whole phase is one conversation: which metric matters for which business decision? “Highest accuracy” is the wrong default for an imbalanced dataset, and accepting it without question is how a retention strategy gets built on a misleading number. The PM value here isn’t writing the code. It’s leading the conversation with the data team, naming the cost of a missed churner versus a false alarm, and choosing the metric that maps to the actual decision the team will make.

A consistent technique I used across every phase: ask for per-line comments on every code block. “Rewrite this snippet with a comment on every single line. I want it to read like a tutorial when I open the file next week.” Those comments became my notes. They’re also what made writing this article possible days later.

Get a second opinion before declaring done

Between Phase 2 and Phase 3, and again at the end of the build, I opened a new LLM session. Not the same one. A fresh tab, zero conversation history, the GitHub repo attached via the GitHub integration. Three words: “Any feedback?”

What the fresh session at the end caught was the killer one. A leaky feature is one that secretly gives the model information about the outcome it’s supposed to predict, making it look accurate in testing while being useless in production. TotalCharges is exactly that. It’s essentially MonthlyCharges × tenure. Customers who left earlier naturally have lower TotalCharges because they were billed fewer months. The model wasn’t predicting who would churn. It was detecting who already had. The LLM’s explanation: “Like predicting someone died because their life was short.”

The fresh session returned five points: the leakage, a missing comment in the code explaining a dropped column, a quantification of the false alarm cost (how many customers would be incorrectly targeted by a retention campaign), a naive baseline that was never explained, and SHAP values as a more rigorous measure of feature importance than the default method. Default importance counts how often a feature was used to split decisions; SHAP measures how much each feature actually moved each prediction. They answer different questions, “how often” versus “how much,” and sometimes produce different rankings. For this dataset, SHAP showed tenure mattering more than default importance suggested, and fiber optic mattering less.

The fix: drop TotalCharges, retrain all three models, compare before and after. Slightly lower accuracy, but an honest model. The final commit: “Address reviewer feedback: remove leaky feature, add cost analysis, SHAP values.”

The tutor session never caught it because it had been inside the build since Phase 3. It had no reason to question a decision it made itself. The fresh session had no stake in being right.

For a PM, this is the moment that earns trust with engineers and data scientists. Catching a leak, even with help from a fresh AI session, and being able to describe it in one sentence (”the model was learning from the outcome instead of predicting it”) is the difference between being someone who reads ML reports and someone who participates in modeling decisions. This single move, repeated a few times over a year, is how a PM gets invited deeper into the technical conversation rather than nudged out of it.

The result: what the model actually found

XGBoost finished at 71.4% recall, meaning 71 of every 100 customers who actually churn get flagged. The 15x churn rate gap is the single most actionable finding in the entire build: month-to-month at 42.7%, two-year at 2.8%. 47.7% of customers churn within year one, so onboarding is the highest-leverage intervention. Fiber optic customers churn at nearly double the rate of DSL (41.9% versus 19.0%), a service-quality signal worth investigating.

The last step is making the model reusable. The trained XGBoost model gets saved to a .pkl file (along with the fitted scaler and the encoded feature column list). The model can be loaded later and used to score new customers without retraining the whole pipeline. It’s the small artifact that turns a notebook into something that could plausibly be deployed.

I wrote three business recommendations directly into the notebook: an annual contract incentive programme, a 90-day onboarding programme for new customers, a targeted NPS investigation for fiber optic customers.

The GitHub repo is the artifact. A README that reads like a product spec, ten commits that trace the build phase by phase, a notebook where every code cell explains itself in comments, and the saved model file that proves the pipeline works end to end.

How to use an LLM as your tutor

Apply these seven moves

The first one is the headline. The other six assume it’s already in place.

Ask for a plan first. This is the superpower. The move that turns “use AI” into “learn from AI” is asking for a plan before asking for anything else. Paste your context, paste your goal, paste any constraint you can think of, then ask for a multi-phase plan with checkpoints. It works for far more than ML: a feature spec, a competitor breakdown, a backend system you want to understand, a cooking technique, a workout program, a Spanish grammar topic you’ve avoided for years. The plan gives you a runway and gives the LLM a frame. The first conversation in this entire build was exactly this move. Paste the Kaggle dataset and the PM context, get a 7-phase plan back. Every other technique below assumes the plan exists.

Drop a screenshot before you describe. The LLM reads UI state, not just text.

In Phase 1, before any error had happened, the LLM noticed “Python 3.13.3 in the bottom-right corner” of a VS Code screenshot and flagged that one library (xgboost) might need extra handling on that version. It read the kernel selector, the toolbar, the Explorer panel. Save the typing. Paste the picture and let the model do the inspection.

Treat errors as conversation, not failure.

When import pandas as pd returned ModuleNotFoundError: No module named ‘pandas’, the response wasn’t “you broke it.” It was a metaphor and a fix.

“The libraries are installed, but the notebook’s kernel is using a different Python than the one where we installed them. Think of it like installing apps on your phone but trying to run them on someone else’s phone.” Then a one-line install fix and a “restart the kernel” instruction. Paste the full error verbatim. Ask for the explanation, not just the fix.

Ask for per-line comments on every code block. “Rewrite this snippet with a comment on every single line. I want it to read like a tutorial when I open the file next week.” Those comments became my study notes. They’re also the lines I’ll quote when someone asks how the code works six months later. The pattern is portable: any AI-generated artifact (SQL, config file, spec doc) can be made to explain itself line by line.

Ask the same question three different ways. The LLM doesn’t get frustrated. “Explain this like I’ve never seen code.” “Now as a PM, not an engineer.” “Now with a real-world analogy.” Three takes on the same concept. Keep the one that lands.

Push back when the plan misses something. The original plan in this build skipped GitHub versioning entirely. Phase 1 set everything up locally with no remote backup. I stopped mid-phase, said so plainly, and the plan adjusted immediately (”Great instinct, that’s exactly what real developers do”). You always know your context better than the LLM does. When a gap shows up, name it. The LLM has no ego about being wrong; it integrates the correction without friction.

One warning: when you say “I’m a beginner,” the LLM may oversimplify. It might skip edge cases, skip error handling, or give a version that works for the tutorial but wouldn’t hold up in production. That’s exactly why the second-opinion session above isn’t optional. One session teaches you, a second session audits what you learned. Treat them as a pair, not as alternatives.

The felt experience: what changed for me

Two observations on what working this way actually feels like, hour after hour:

• The encouragement is real. When the LLM says “great instinct” or “you caught that yourself before I even explained it fully,” it’s flagging a moment when you did something a beginner wouldn’t normally do. The recognition isn’t decorative. Over the course of an evening’s focused build, those moments add up to a low-grade momentum that’s hard to get from a textbook or a video course.

• You can reframe any output in any direction. “Read this output like a PM” worked dozens of times in this build. The same numbers land completely differently depending on the lens: raw accuracy versus retention budget impact versus board-ready story. The LLM switches frames on request, and the second framing is usually the one your team will actually understand.

What this style of learning quietly removes that traditional self-taught paths never could: the loneliness of being stuck, and the rigidity of pre-recorded explanations.

What AI changes about learning

Step back from the build for a moment. One PM, one project, one evening. The bigger story is what’s actually different about learning today, anchored in the same person trying to learn the same kind of thing, ten years apart.

The contrast: same brain, ten years apart

Ten years ago. A 30-hour Udemy course bought on a whim, half-watched in evenings. Stack Overflow for the parts that broke, YouTube comments for the parts that confused. No one to ask the obvious dumb question. No one to translate the textbook into plain English. No one to hold the rope when a side project stalled out. Most people who started never finished. Most who finished couldn’t transfer what they learned to their actual job.

This year. A one-year program at the Sorbonne, evening classes alongside a full-time PM job. The course itself was good. But the actual learning happened in a different place than the diploma suggested it would.

I recorded every lecture, transcribed the audio, and pasted the transcripts into Gemini for cleaner notes with the gaps filled in. Once a unit was done, I dropped everything into NotebookLM and let it generate a podcast and a slide deck to replay on the commute, in the gym, between meetings. And through all of it, I kept a continuous conversation going with Gemini: questions about the lecture content, metaphors that helped a hard concept land, code snippets explained line by line, deeper discussions hours after the actual instructor had gone home. **A 24/7 patient tutor in the pocket.**

The diploma was the scaffolding. The AI was the actual classroom.

The instructor’s new job

This isn’t an argument that AI replaces teachers. The instructor still does work that AI can’t. They tell you what’s possible, including the things AI won’t volunteer because you didn’t know to ask. They give you the principles you need to challenge AI output. They catch the leaks (in this build’s case, a literal data leakage in the model) that you’d miss because you don’t yet know leaks exist.

The four-minute mile is the parallel that fits here. On May 6, 1954, Roger Bannister ran a mile in under four minutes, something the medical community genuinely believed was physically impossible. Within a year, dozens of runners broke the same barrier. Knowing something is possible changes what people attempt. A good instructor today is mostly in the business of expanding what their students believe is possible, and trusting AI to handle the parts that used to require lectures.

One last thing. I’m joining the training team at the Sorbonne on the PM side after this year. Knowing every future student will have a 24/7 patient tutor in their pocket will probably change how I teach. More time spent on what AI can’t do (naming what’s possible, framing real problems, defending judgment calls, holding the rope when a student is stuck on something that has no clean answer) and less on what it now does for free. The job description of “instructor” is being rewritten in real time, and getting to be on both sides of that change at the same moment is one of the strangest and most interesting things happening in education right now.

Start your first project this evening

The bar to start has never been lower. One dataset, one LLM chat session, one question: “give me a beginner-friendly plan.”

Don’t do this for the joy of learning. Do it the next time a real question lands on your desk, the kind that would normally turn into a ticket and three weeks of waiting for the data team. Why are users dropping off, what’s driving conversion, where the support tickets are spiking, which features correlate with retention, which support categories are growing fastest. Pull the export yourself. Ctrl+A, Ctrl+C. Open an LLM chat, not a coding assistant. Paste it in along with what you’re trying to figure out. Ask for a beginner-friendly plan. Spend an evening on it. You probably won’t ship the analysis. You’ll walk into the next meeting with sharper questions than the people still waiting in the queue.

The public repo for this build: github.com/adamfaik/churn-prediction. Everything is there if you want to see what the end looks like before you start.

Here’s the part that still surprises me. I didn’t set out to finish it. That afternoon, I was working on something else in Claude Code and it was taking its time on a slow task.

I could have scrolled Instagram. Instead, I opened a second VS Code window, pulled up the repo of that abandoned book project, and started poking around. Just to have something to do while another window was busy.

A few hours later, I had compared twenty-one chapters to the original 1683 source, added about a hundred and forty historical annotations (each one with a cited source), and published the whole thing on GitHub Pages. I had not meant to finish the book. I meant to have something to do while another task was thinking. And the work just... happened.

It’s about the shift in how I work. How I went from thinking of Claude Code as ”that thing engineers use for code” to seeing it as a way to run any project where the same rules have to be applied over and over. Including, apparently, a 17th-century autobiographical memoir and a slice of French-Moroccan history.

Here’s what the rest of the article covers, in order:

1. The use case: a forgotten 1683 memoir. The book, what makes it worth a modern edition, and the personal story behind it.

2. First try: how I used Gemini. The first attempt: what worked, what the tools got right, and why I stopped anyway.

3. The click: rules in a file, not a chat. The moment the mindset shifted: from re-pasting rules into a chat to encoding them in a file.

4. How I finished the book: four steps. Ten editorial rules defined in one morning, three Skills built in sequence, twenty-one chapters run in parallel.

5. Spot skills in every project. The three-question test and how the same shape shows up in any product week.

Let’s open the book.

The use case: a forgotten 1683 memoir

I found it on archive.org one evening when I was bored and typed ”livre du Maroc” into the search bar. A pretty chaotic way to stumble on a book. The title that came back stopped me cold: Relation de la Captivité du Sieur Moüette dans les Royaumes de Fez et de Maroc.

A Frenchman. Eleven years held captive in Morocco under Moulay Ismaïl. Published in 1683. I’ve always been drawn to the history of both countries, and a first-person 17th-century memoir from someone who lived both is not a book you scroll past. I downloaded it instantly.

The first page was almost unreadable. Not just old French. Pre-1800 French, with the long-s (ſ) instead of s, and spellings and abbreviations that make your eyes bounce off the page after two sentences. I gave up after three pages.

A week later I tried again, and something strange happened. By the end of chapter one I was reading it almost normally. Your brain does an involuntary translation once you’ve seen enough of the pattern. It’s a little like those well-known scrambled-letter paragraphs where the first and last letters are right and everything in the middle is a mess. Same phenomenon, slower setup.

I finished the book over a long weekend. Two things hit me.

The first was the modernity of it. Moüette is talking, in 1683, about things that still feel recognizable in 2026. The politics of North Africa. The economics of trans-Mediterranean trade. The porous borders of belief and identity. The names change. The shape of the conversations doesn’t. That’s the part you never get from a history textbook. Read through someone’s lived experience and the whole period comes alive from the inside. You don’t learn about the 17th century. You sit next to someone who lived it.

The second was that Moüette is a weirder narrator than you’d expect. He was taken captive in the 1670s and then decided, somewhere along the way, to treat his captivity as fieldwork. He saw himself as an observer. He believed France and Morocco were eventually going to have to figure out how to talk to each other, and he wanted to come back with something useful for that conversation. A kind of self-appointed diplomat, writing notes in chains. That’s a strange posture to hold, and it’s the reason the book is as good as it is.

And then there’s the personal layer, which is the part I almost kept to myself. I grew up in Morocco. I moved to France to study and then to work. Moüette did the reverse trip, involuntarily, in 1670. I’m not going to overstate the parallel (I’m not, to be clear, a captive in France, thank you for asking), but reading his memoir felt like meeting someone who made my exact trajectory 350 years earlier, in the opposite direction. That’s why the book kept tugging at me months after I’d finished it.

Here’s what I started thinking. A book like this deserves more than a scan sitting quietly on archive.org, smelling of basement. A modernized French edition is the minimum. Past that, it deserves a bande dessinée, a Netflix series, and honestly a Scorsese film, but I’m willing to negotiate. It’s a tight, weird, human account of a period most of us only ever learn in abstractions.

I checked Amazon. Nobody had made a modern edition. If the book was going to get one, I was going to have to do it myself.

First try: how I used Gemini

First attempt: chapters one by one

My first attempt was months earlier, and it was all done in Gemini. I’d open the PDF, copy a page, paste it into the chat, and ask for a modern French transcription. Genuinely, I did not expect this to work.

The first time it did, I was a little stunned. Even with archaic spellings and garbled OCR in the source, Gemini came back with readable, well-formed paragraphs. I kept going, chapter by chapter, pushing several pages at a time thanks to the big context window.

The result was a working first pass. Chapter by chapter, Gemini turned the archaic French into readable modern French, formatted as markdown. Each chapter came out as a structured file: headings, paragraphs, footnote markers in place.

Not perfect. There were omissions and meaning drifts I’d only discover much later. But it was a genuine starting point. A folder of modernized text, ready to become a book.

The most fun part was the Arabic lexicon at the end of the book. Moüette had included a small French / dialectal-Arabic dictionary. Not classical Arabic. Street Arabic from 17th-century Morocco. Running it through Gemini, I realized a lot of those words are still used in Moroccan darija today. A tiny time capsule of spoken language that survived 350 years.

I want to be honest about what I was actually doing here. I wasn’t using Gemini because it’s ”the right tool for OCR.” I was using Gemini because it was the AI I knew, and chat was the only mode I knew how to work in.

Open a tab. Write a prompt. Hope the model keeps the context. Paste a page. Paste another page. Thank the gods for the big context window. Everything I built in this phase, I built in chat mode. One long conversation per chapter. Rules re-explained in each new tab. No memory between sessions.

That worked. But it hit a ceiling I couldn’t see from inside it. Picture the whole project being held together by three hundred Gemini tabs in my favorites bar and my own willingness to keep pasting the same block of instructions into each new one.

Use a standard tool, not custom code

When I eventually asked Gemini how to publish the book as a website, I expected ”let’s build a small React app.” Instead, Gemini pointed me at VitePress, a static-site framework that turns markdown files into a clean, navigable, book-shaped site. I’d never heard of VitePress. I also hadn’t asked. I was about to ask the model to build me something custom, and it quietly told me there was a standard tool for this job.

That’s the lesson I keep coming back to. Before you ask an AI to vibe-code a custom thing, ask it the opposite question first:

Is there a standard framework, library, or tool that already does this? If there is, use it.

Most of the time, the answer is yes. A few examples I’ve hit since:

• For a book or documentation site, VitePress or Docusaurus.

• For a quick internal data dashboard, Streamlit.

• For a training or course site, Docusaurus or MkDocs.

• For an LLM prototype with a simple UI, Gradio or Streamlit.

• For presentation slides generated from a structured document: Marp (markdown → slides), Beamer (LaTeX → slides), or a small Python script with python-pptx if you need a programmatic PowerPoint.

Off-the-shelf tools are boring. They’re also well-tested, documented, styled by people who actually care about typography, and usually fifteen minutes of setup. Custom code is seductive because the model will happily generate three hundred lines of it. Resist for a second. Ask the ”is there something standard?” question. Often the answer saves you from a pile of maintenance you don’t want.

The site build: six steps with Gemini

Once VitePress was on the table, I asked Gemini to walk me through it. Nothing magical happened here, but the process might be useful if you’ve never set up a static-site project before.

Roughly how I did it:

1. Created a new empty repo on GitHub for the book project. No git-clone terminal dance. I made the repo on github.com directly, added a README from the web interface, then downloaded the repo as a ZIP when I needed the files locally.

2. Followed VitePress’s official setup instructions with Gemini narrating them in plain French as we went. The scaffold gives you a configuration file, a home page, and a docs/ folder where your markdown chapters live. Same idea as a Word document with a table of contents, except each chapter is its own small file.

3. Created one markdown file per chapter, calmly, one at a time, pasting in the modernized French that Gemini had produced during the earlier chat sessions. Files named preface.md, chapitre-1.md, chapitre-2.md, and so on.

4. Asked Gemini to generate a cover image for the modern edition. Something with period typography and a hint of 17th-century North Africa. It produced something decent on the second try. That became the book’s homepage art.

5. Asked Gemini to help adjust the VitePress theme so the site felt closer to the book’s period. Historical serif fonts that are still readable on screen. A slightly warmer palette than the default. A navigation sidebar with the chapters in order. I described the mood (”old paper, candle light, but readable on a 2024 laptop”) and Gemini produced a CSS file that matched it reasonably well.

6. Deployed to GitHub Pages, again with Gemini’s instructions, which is where I hit a small hiccup. GitHub Pages will happily render your README as the homepage by default, not your VitePress build. You have to flip a setting in the repo’s Pages tab to tell it to use a GitHub Actions workflow instead. Fifteen minutes, not fifteen seconds, but once flipped it stayed flipped.

By the end of an afternoon, I had a private, working, scrolling book-shaped site. A third of the chapters modernized. A cover image. A period-appropriate theme. A deploy pipeline. Not published publicly, but running.

The stall: out of time and no plan

And then, for a few reasons, I stopped.

The first reason was the content itself. Moüette is a 17th-century Catholic writing about people he considers his enemies, and the vocabulary shows it. I didn’t want to push something into the world without knowing how to handle the parts that would land badly.

The second reason is more boring. I ran out of time and momentum. I had a decent VitePress scaffolding, a cover, maybe a third of the chapters done, and no clear path to the finish line.

The twenty pieces left to modernize and review felt like a lot of evening hours, and not one of them felt especially fun. I told myself I’d come back to it when I retired. Then I closed the tab.

It sat there for months.

Looking back, stopping was the right call. If I’d kept grinding through chapter-by-chapter pastes in Gemini, I’d have spent weeks on something that eventually took an afternoon. The problem wasn’t the effort. It was the shape of work. I didn’t even know skills were a thing.

Leaving the project in a drawer meant I came back to it after I’d understood something new. Put it down. Let your understanding catch up. Then open it again.

The click: rules in a file, not a chat

Back to the afternoon. Second VS Code window open, abandoned repo loaded, I typed a request. Something like: ”can you compare this modernized chapter to the original 1683 source and tell me what went wrong?” Claude Code read both files, thought for a minute, and came back with a list of differences. Missing paragraphs. Odd word choices. A few proper nouns spelled three different ways across the chapter.

That alone was useful. But while I was reading the output, a smaller thought hit me: I’m going to want to do this exact thing on the next chapter. And the one after that. With the same rules.

In Gemini, that would have meant opening a new chat, re-pasting the rules, re-explaining the context, every time. I have a folder of three hundred bookmarked Gemini conversations that exists exactly so I can find the rules I wrote down somewhere and paste them into the new chat. That’s a lot of effort for something that’s really just saying ”apply these rules.”

What Claude Code let me do instead was create a file. A small markdown file, in a folder called .claude/skills/, with a name and a short description and the rules written out. Once that file existed, I could type /review-chapter chapitre-2 and Claude Code would just... apply the rules. No re-pasting. No re-explaining. The same behavior every time.

The difference isn’t the AI. It’s the container. A rule typed into a chat window lives exactly as long as that chat window is open. A rule written into a file outlives the conversation. It travels with the repo. It applies the same way next month as it does today.

That was the click. I wasn’t writing a prompt anymore. I was writing a rule. The rule lived in a file. The file lived in the repo. Next week, next month, next year, the rule would still be there, applying itself consistently to whatever chapter I pointed it at.

That’s the thesis of this article, and I’ll say it plainly: any project you’d run on a whiteboard can be run in a repo. Not just code. Any project where the same rules have to get applied to multiple inputs. A book. A stack of stakeholder updates. A folder of user-interview transcripts. A weekly research synthesis. If you’ve ever pasted the same block of context into a fresh chat window twice, you’ve hit the shape of work that Skills solve.

How I finished the book: four steps

Once the mindset shifted, everything else followed in sequence. Four steps, each one unlocking the next.

Define your rules once

Before writing any Skill, I needed to know what the rules actually were. I had a vague sense of what the modernization should feel like: preserve Moüette’s voice, handle the old typography, keep the unusual words where they belonged. A feeling isn’t a rule, and a rule you can’t write down in one sentence can’t live in a skill file.

So Claude Code and I spent a morning doing something very simple. One question at a time, with options.

A typical exchange looked like this:

Claude Code: For the author’s voice, which of these three feels right?
(A) Keep the original phrasing exactly, even when archaic.
(B) Allow light rephrasing for clarity, but preserve personal interjections and hedging.
(C) Modernize fully for readability, voice can drift.

Me: B. If he says ”je ne sais combien de déserts”, that stays. It never becomes ”de nombreux déserts”.

Claude Code: Got it. Locking that as rule #1: voice preservation, light rephrasing allowed, personal interjections and hedges always kept.

That’s the pattern. One question, 2–3 concrete options, pick one, lock it. Repeat until you have a list.

Try it the opposite way and you’ll freeze. I know this because I’ve frozen. ”What are your editorial rules?” is an impossible question. ”Given this paragraph, would you prefer A, B, or C?” is a simple question. Options force judgment. Judgment produces rules.

By the end of the morning, I had ten. Three of them took real back-and-forth.

• Voice preservation was first. The reason it took ten minutes, not two, is the example I had to nail down: ”je ne sais combien de déserts” can’t become ”de nombreux déserts.” That hedged, slightly shy way of describing an overwhelming thing is who Moüette is as a narrator. Smooth it out and you lose the person.

• Handling omissions. Gemini’s first pass had quietly left some paragraphs out. The question: reintegrate them silently (A), add editorial brackets to signal they’d been restored (B), or leave the gaps and note them in a footnote (C). I picked A. Moüette wrote those paragraphs. They belong in the text. An editorial bracket interrupts the reading experience with a scholarship signal most readers didn’t ask for.

• Sensitive terminology was the uncomfortable one. Moüette uses vocabulary that a 17th-century French Catholic writing about his captors would use. Options: modernize the terms (A), keep them exactly as written and contextualize via annotations (B), or remove the worst instances (C). I picked B. Changing the vocabulary would be changing the historical record. The annotations explain without excusing. I’ll come back to how this made it possible to ship.

The other seven took much less time. Some were thirty seconds: footnote format was just ”which syntax does VitePress support?” Done.

Once the ten rules existed, I saved them in three places. Inside project memory (so Claude Code would always see them). Embedded inside each skill (so the skill carried the rules with it). And in a reader-facing editorial note on the published site (so anyone reading the book could see exactly what was done to the text). Three homes for the same rules. Each one earning its place.

The three skills: review, apply, enrich

I didn’t start by designing three Skills. I started by needing one answer: “what’s actually wrong with what Gemini produced?”

The first skill I built was review-chapter. I described what I wanted: read a modernized chapter, read the corresponding section of the 1683 source, compare paragraph by paragraph, flag every problem. Then I wrote the skill.

I ran it on the preface. The output was immediately useful and immediately humbling. Twelve instances where Moüette’s personal voice had been smoothed away. The exact sentence I’d noticed (”je ne sais combien de déserts” quietly rewritten as ”de nombreux déserts”) was flagged, with the source passage and a suggested fix.

I ran it on chapter 1. Same categories: omissions, meaning shifts, OCR artifacts, proper nouns spelled inconsistently. I had a diagnosis.

What I didn’t have was a way to fix all of it consistently. And that’s when the connection clicked. I had just spent a morning writing ten editorial rules. Those rules were sitting in project memory. ”I have a set of rules I want applied to every chapter. That’s exactly what a Skill is for.” So the second skill wrote itself out of the first. That became harmonize.

Running both skills across all the chapters left me with a clean text. But clean doesn’t mean alive. A modern reader hitting Moüette’s offhand mentions of ”les corsaires de Bouregreg” or ”les Marabouts” or ”la milice des Renégats” gets nothing: no frame, no context, no reason to care. So a third conversation started: ”what if we added a short sourced annotation at the end of each chapter?” That conversation produced annotate.

Three skills, each one discovered by using the previous one (browse in the GitHub repo).

Here’s what each one actually does:

• review-chapter: the diagnostic. Reads the modernized chapter, reads the corresponding section of the 1683 source, compares paragraph by paragraph. Produces a structured report across eight categories (A–H): omissions, meaning shifts, unauthorized additions, proper-noun inconsistencies, modernization inconsistencies, OCR artifacts, paragraph structure, footnote candidates. Each issue gets a location, a quoted source passage, a problem statement, and a suggested fix. The report ends with an overall grade: Good / Needs minor fixes / Needs significant rework. Read the full SKILL.md here.

• harmonize: the rules-applier. Applies all ten editorial rules using the edit tool to touch only what needs touching, never rewriting the whole file. Voice preservation, silent reintegration of omissions, proper-noun normalization, footnote discipline, paragraph-structure rules, sensitive-vocabulary preservation. All embedded in the skill itself. When I run /harmonize chapitre-7, it doesn’t just “modernize” the chapter. It applies the whole editorial policy. Read it here.

• annotate: the one with the strictest rule. Appends a ”Repères historiques” section to each chapter with five to ten contextual notes. Each note: a brief quote from the chapter, a 3-6 sentence explanation, a cited source. Every factual claim must be verified via WebSearch before it’s written. No exceptions. If the model can’t verify something, the note either gets dropped or explicitly marked as uncertain. Academic sources preferred. The tone target is ”a knowledgeable friend, not a textbook.” Read it here.

The run: 21 chapters in parallel

Once the three Skills existed, I had to run them across the whole book. That’s 21 files: the preface, the royal privilège, fifteen chapters, a commerce treaty, the Arabic lexicon, a geography annex. I could have run them one at a time. I didn’t.

I did the first chapter in full. Ran /review-chapter chapitre-1, read the report, ran /harmonize chapitre-1, read the diff, ran /annotate chapitre-1, read the annotations. Then I stopped and asked myself a simple question: does this look right? It did. Then I fanned out. Claude Code launched sub-agents (parallel workers, up to eleven at a time for the annotation pass) and pointed each one at a different chapter.

The pattern is worth naming, because it stops you from blowing up a whole project on a flawed first run:

Demo one. Approve it. Then fan out.

The run itself was genuinely fast. Minutes, not hours. Here are the numbers across all 21 files:

• 412 insertions, 253 deletions committed across 22 files

• ~70 footnotes added

• ~140 sourced historical annotations written

• Up to 11 concurrent sub-agents during the annotation pass, 6 during review/harmonize

I want to be honest about the timeline. The ”I finished it in under an hour” line was the felt experience, not the actual clock.

The run took minutes. The work took two days. That morning spent defining rules. An afternoon fixing a few mistakes. Another morning reviewing annotations, rewriting the editorial note, and publishing the site.

Skills aren’t magic. They’re leverage. The run is fast because the rules are sharp. The rules take a morning.

What the annotations surfaced is the part I keep bragging about at dinners. The Republic of Bouregreg, a corsair city-state that existed between 1627 and 1668. Barbary lions, which roamed North Africa until they went extinct in the wild in 1942.

The fleurs de lys carved by French slaves into the walls of Moulay Ismaïl’s palace at Meknes. The Order of the Merci’s “blood vow”, a fourth monastic vow to offer oneself as a replacement for a captive who couldn’t be ransomed. I knew none of this before the annotate skill found it and sourced it. The annotations made the book twice as alive.

What made it shippable: values in the skill

One of the reasons the book had sat in a private repo for months was the content itself. Some passages are genuinely uncomfortable by today’s standards. I wasn’t sure I wanted my name on a site hosting that content without some kind of frame.

The annotate skill gave me the frame. Its job on those passages wasn’t to censor them or smooth them over. It was to contextualize them. Sourced notes. Historical framing. Scholarly context that helps a modern reader understand what they’re looking at and why it’s there. The content warning on the homepage tells readers what they’re walking into before they open the first chapter.

That combination (a content warning and annotations that explain rather than erase) was what finally made me feel ready to ship. A skill can hold values, not just rules. The whole policy lives in a file. It can be inspected. It can be argued with. That’s what I want from a system I put my name on.

What I’d change: use skill-creator

Only one thing. Next time, I’d open Anthropic’s skill-creator skill before writing a single file. It’s a skill that helps you write other skills. You describe what you want, it scaffolds the folder, the SKILL.md, the frontmatter, all following current best practices. I didn’t know it existed when I built my three, so I learned the hard way, through trial and Claude Code’s diagnostic errors. It worked out fine. But if you’re about to build your first skill, skill-creator is the shortcut I wish I’d taken.

Spot skills in every project

After the book was live, I sat down to write a stakeholder update at work and caught myself thinking: ”wait, this is a skill.” Not a lightning bolt. A small, quiet ”oh, this too” about a task I’d been doing the hard way for years.

The book didn’t teach me skills. It taught me to see them. Here’s the practical test I started applying. Three questions, in order:

1. Am I re-explaining the same rules over and over? If you’ve typed the same block of context into a fresh chat window more than twice, those rules belong in a file, not in your head.

2. Is there a checklist living in my head that I never wrote down? The quality bar you apply before sending something, the three things you always catch, the format you always enforce. That’s a skill waiting to be written down.

3. Does the output need to look the same shape every time? Same structure, same tone rules, same format, week after week. That’s the exact shape a skill solves.

Applied to a product week, the list shows up fast. I wrote about one of these in detail already: /customer-pulse.

That skill searches reviews, forums, and app stores for what users are saying, and returns a structured report with ranked themes, real quotes, and a “Top 3 this week” action list. If you want the step-by-step on building a skill from scratch, any Skill, that’s where to start.

The same pattern shows up across the rest of a product week:

• Customer feedback synthesis. Multiple sources, grouped by theme, real quotes, source links. The rules you re-apply every time are exactly what a skill holds.

• Stakeholder updates. Same structure every week, same length target, same tone rules. Skill-shaped.

• User-interview theming. A folder of transcripts, a definition of what a good theme looks like, quote extraction with attribution. Skill-shaped.

• Competitor monitoring. A list of URLs, a definition of what change looks like, a weekly diff. Skill-shaped.

• Meeting recaps. Your team’s template, your tone rules, action items always in the same format. Skill-shaped.

Once you answer yes to one of those three questions, you’re looking at a skill. The only question is which project you want to start with.

Start with a project you already know

The book took an afternoon to finish. The afternoon started because another task was thinking and I had a spare VS Code window. That’s the whole origin story.

It’s still not finished, if I’m honest. I’d like to generate comic-book panels with Gemini Nano Banana Pro to tell Moüette’s story visually. Maybe a short film, once video models get a bit cheaper. Another weekend, another skill.

Your turn. You don’t need a 17th-century book. You just need one project where you already know what good looks like, and where you’re tired of re-explaining it. Open it. Ask one question: “what rule am I re-pasting into every fresh chat?” Write it down. Put it in a file. That’s the first skill.

Then something shifted. I saw product people getting genuinely excited. Not about the concept, but about what they were building with it. So I carved out an afternoon, sat down, and actually built one from scratch. And it changed how I think about my work.

The skill I built is called /customer-pulse. It searches the web for what real users are saying about a product (app store reviews, Trustpilot, forums, comparison articles, etc.), then produces a structured report with ranked themes, real quotes, blind spots, and concrete actions. Everything I built is in this GitHub repo. Clone it, explore it, use it for your own product.

A quick definition: a skill is a set of instructions written in plain English that lives in your project folder. When invoked, Claude reads those instructions, reads your files, uses real tools (web search, file creation, page fetching, etc.), and produces real output. Unlike a custom GPT or a Gem, it lives in your repo. You own it. You version-control it. It evolves with your project.

Here’s what we’ll go through in this article:

• Level 1: Download the repo and run a skill. Get Claude Code installed, download the project, run the skill, and see a real feedback report.

• Level 2: Understand what skills are. Open the skill files and learn the building blocks: SKILL.md, product context, CLAUDE.md. See how skills compare to custom GPTs, NotebookLM, and saved prompts.

• Level 3: Build your first skill step by step. The real story: how I described my problem to Claude Code, the review process that caught 5 issues, and the iteration that turned a generic report into an actionable one.

• Level 4: Go further. Where to find existing skills, what MCP servers and agents are, and when skills are the wrong tool.

Each level is self-contained. Stop at Level 1 and still walk away with a working tool. Go to Level 3 and walk away knowing how to build your own.

Why this use case

Read the full skill instructions. It’s plain English, no code. That file is the entire skill.

I chose feedback collection because it’s something product people will always do. No matter how much AI disrupts our work, understanding what users actually experience remains a human decision. AI can collect, synthesize, and structure the data faster. But deciding what matters is still ours.

I considered building skills for other PM tasks: PRD generation, user story refinement, sprint review preparation. I dismissed them. Not because they’re bad ideas, but because I’m genuinely unsure those artifacts will exist in the same form much longer. When AI can build a working prototype from a conversation, do we still need a 15-page specification document? Maybe the future is less specifying and more building. And maybe “building” increasingly means creating skills that do the work, which happens to be the topic of this article.

Feedback collection, though, stays. Users will always talk. The question is whether we listen fast enough.

Level 1: Download the repo and run a skill

Allow about 30 minutes for this level. At the end, a full customer feedback report will be waiting in your project folder.

Step 1: Open your code editor

Open VS Code, Cursor, or any code editor that has a built-in terminal. If you don’t have one, download VS Code for free from code.visualstudio.com.

Once it’s open, find the built-in terminal. In VS Code: go to Terminal → New Terminal. A panel appears at the bottom.

One tip that made a big difference for me: move the terminal panel to the right side. In VS Code, right-click the terminal header bar, select Panel Position → Right. This puts your files on the left and Claude Code on the right. Much easier to work with. I spent way too long with it at the bottom before discovering this.

Step 2: Install Claude Code

So what’s Claude Code exactly? It’s an AI assistant that runs inside your terminal. Unlike ChatGPT or Gemini, it doesn’t live in a browser. It lives in your project folder. It can read your files, search the web, create documents, and run skills. Think of it as an AI colleague that sits inside your project and actually does things, not just talks about them.

One thing to know upfront: it requires a paid Anthropic plan. The Pro plan is $20/month and the Max plan is $100/month. There’s no free tier for Claude Code. It’s worth it, but it’s good to know before installing.

To install it, paste this command into the terminal and press Enter:

curl -fsSL https://claude.ai/install.sh | bash

That’s it. One line. This comes straight from the official quickstart guide.

Now here’s something that trips up a LOT of people, and I want to save you the confusion. The terminal has two modes. Right now it’s in bash mode. That means it runs system commands, like the install command you just pasted. But when you launch Claude Code, it switches to conversation mode. In conversation mode, you type in natural language, like talking to a colleague. You invoke skills with the / prefix. So /customer-pulse is a skill. curl is a bash command. Don’t mix them up. Two modes, two purposes.

If you want to get familiar with some Claude Code commands and shortcuts, there’s a nice community cheat sheet that covers the essentials.

Close and reopen the terminal (or open a new one) so it picks up the new command. Then type:

claude

The first time, a browser window opens to log in with your Anthropic account. After that, Claude Code starts directly.

Step 3: Download and open the project

Exit Claude Code for now (type exit or press Ctrl+C). Go to the product-feedback-skill repo on GitHub. Click the green Code button, then Download ZIP. Unzip the folder wherever you keep your projects (for example, your Documents folder).

Now in your editor, go to File → Open Folder, navigate to product-feedback-skill, and click Open. The left sidebar (the explorer) shows all the project files.

Step 4: Run the skill

Open a new terminal in your editor (Terminal → New Terminal) and make sure it’s inside the project folder. Then launch Claude Code:

claude

The repo includes product context files for two products: Figma and Slack. Let’s try Figma. Type:

/customer-pulse figma

And then just watch. It’s genuinely fun to see. Claude reads the Figma product context, starts searching the web (Trustpilot reviews, forum threads, comparison articles), fetches the most relevant pages, extracts real user quotes, groups them into themes, scores each by severity, and writes a full report to reports/. The whole thing takes a few minutes because Claude is making 12 web searches and fetching up to 20 pages. Just let it do its thing.

When it’s done, open the generated report in the reports/ folder. Right-click the file tab → ”Open Preview” to see it formatted instead of raw text.

One command. A full customer feedback analysis with source URLs, severity rankings, sentiment direction, and a “Top 3 things to do this week” action list. Try /customer-pulse slack for the other product.

Level 2: Understand what skills are

OK so the report just appeared. That’s cool. But what actually happened behind the scenes? Three files made the whole thing work. Let’s open each one.

Step 1: Open the SKILL.md

In the explorer sidebar, navigate to .claude/skills/customer-pulse/SKILL.md. Click it. Or read it directly on GitHub.

Take a moment to read it. This is the entire skill. A Markdown file. No code. No API calls. No special syntax. Just English. If you can write an email, you can write a skill. Seriously.

Right-click the tab → ”Open Preview” to see it formatted. That’s easier to read once you understand the structure.

It has two parts. The header (called frontmatter) controls how the skill behaves. The settings that matter most:

• description: how Claude decides whether to suggest the skill. Vague descriptions like “analyzes stuff” don’t work. Specific ones like “use when the user wants to understand customer sentiment” do. It’s like giving a teammate a proper job description.

• disable-model-invocation: true: prevents the skill from auto-triggering. For a skill that makes 30+ web calls, you want explicit control.

• allowed-tools: lists tools Claude can use without asking permission each time. Without it, Claude pauses 20+ times to ask. With it, the skill runs smoothly.

• $ARGUMENTS: when you type /customer-pulse figma, “figma” replaces $ARGUMENTS in the instructions.

The body tells Claude what to do, step by step, in plain English. The official skills documentation has the full reference.

When does it make sense to build a skill? Tasks that are repeatable, multi-step, and benefit from context. If you’d need to re-explain the same context more than twice, it’s worth encoding as a skill. For one-off tasks, just ask Claude directly.

Step 2: Open the product context

Navigate to product-context/figma.md. Or read it on GitHub.

This file describes Figma: features, customer segments, pricing, known pain points, competitors. The skill reads it before searching. That’s why the report isn’t generic. Without product context, you get “users complain about performance.” With it, you get “the March 2026 regression affected component manipulation specifically, compounding the long-standing 2GB memory cap issue that hits enterprise teams with variant-heavy design systems.”

This separation is the clever part. The SKILL.md defines the process. The product context defines the knowledge. Change the context, and the entire analysis shifts. Without touching the instructions.

If you were doing this at work, your context file could include customer personas, Jira backlog categories, OKRs, NPS themes, competitive analysis, and roadmap features. The richer the context, the smarter the analysis. The skill doesn’t care where the knowledge comes from. It just reads the file.

Step 3: Understand how skills compare to other tools

A saved prompt. Every time you paste your product description and analysis request into ChatGPT, you’re doing manually what a skill does automatically. A skill reads your files for you. The context is always there. No pasting.

A custom GPT or Gem. Lives in someone else’s cloud. Can’t read your local files. Can’t create documents in your repo. A skill is a Markdown file you own, version-controlled with git.

NotebookLM. Same “rich context” idea, but limited to answering questions and generate a certain type of content. Skills can search the web, create files, and produce reports that feed into your next workflow. Skills are rich context plus real actions in the same place.

Perplexity. Great for one-time answers. A skill gives you a versioned, repeatable process that improves over time. A Perplexity search doesn’t compound. A skill does.

Skills also work beyond Claude Code. You can use them in claude.ai (upload as zip) and in the Claude desktop app with Cowork. Claude Code is the most powerful surface though, with full network access and features like allowed-tools.

Step 4: Open the CLAUDE.md

Last file. Open CLAUDE.md at the project root. Or read it on GitHub.

A README.md is for humans. CLAUDE.md is for Claude. It tells Claude what the project is about, what files matter, and how things connect. Claude reads it automatically at the start of every session. Create one for any project by typing /init. Keep it under 30 lines.

Level 3: Build your first skill step by step

If you’ve read my previous post on how to save +5 hours a week with Gems, the process here will feel familiar. Same loop: ask the AI to write the instructions, test them, see what’s wrong, improve them, test again. With Gems, you do this in a web interface. With Claude Code skills, you do it inside your project folder. The principle doesn’t change. The power does.

Here’s how I actually built /customer-pulse. Not the clean version. The real one. Before the details, here’s the overview:

1. Describe the problem. No technical instructions. Just explain what you need.

2. Review the skill. Ask Claude Code to check its own work.

3. Run it and evaluate. See what’s good, what’s missing.

4. Improve the instructions, not the output. Fix the SKILL.md so every future run is better.

5. Test on a different product. Make sure it generalizes.

Step 1: Describe your problem

I opened Claude Code and typed:

I’m a product manager and one of my jobs is to explore customer feedback across different platforms (app stores, review sites, forums) so I can make better decisions and understand the problems our users are facing. But it’s time consuming. I sometimes miss important sources, and I struggle to synthesize and identify the most actionable feedback. I was wondering if it makes sense to create a system here that helps me do that every time. Feel free to ask me any questions.

I didn’t say “create a .claude/skills/ folder.” I described a problem. You don’t need to know terminal commands. You need to know how to describe a problem clearly. That’s a skill product people already have.

Claude asked clarifying questions: what product, what sources, what format. I said Figma. It proposed a 4-phase architecture with a scoring system and guardrails. Then it built everything. I just watched files appear in the VS Code Explorer.

Step 2: Review the work

Here’s a workflow I wish someone had told me about earlier: the double-loop. One AI session builds. Another reviews. You make the decisions.

I asked Claude Code in another session to check the skill against best practices. It found five issues: lowercase file name (should be SKILL.md), no $ARGUMENTS support, missing disable-model-invocation, missing allowed-tools, and a too-generic description. I shared the findings back in the initial session and Claude Code fixed everything in minutes. I asked AI to check AI’s work, and then I made the decision about what to fix.

One thing I also learned: Claude sometimes creates a command (the old format) when you ask for a skill. Commands work, but lack the frontmatter options. Always double-check. You’re the pilot, even in autopilot mode.

Step 3: Run it and evaluate

The first run produced a solid report. 65+ data points, ten ranked themes with real quotes and source URLs. But it was missing things. No blind spots section. No separation of “already known” vs “new discovery.” The recommended actions were generic (”publish a performance roadmap”), the kind of advice any consultant would give for $500/hour without knowing your product.

Step 4: Improve the skill, not the report

I was about to edit the report. Then I stopped. If I fix the report, I get a better report once. If I fix the SKILL.md, every future run produces a better report automatically. You’re not building a document. You’re building a machine that produces documents.

Here’s exactly what I told Claude. No prompt engineering. Just describing what was wrong:

The report is missing a blind spots section. I want to know what data is missing and why.

Separate confirmed known issues from new discoveries. Tag each theme as CONFIRMED or NEW.

The recommended actions are too generic. Make them reference specific data from the report.

Add a “Top 3 this week” section at the top with concrete actions and links.

Track whether each theme is getting worse, staying stable, or improving.

Claude Code updated the SKILL.md. I ran it again. Same Figma. Same search budget.

The difference was striking. The v2 report tagged every theme as [CONFIRMED] or [NEW]. The blind spots section revealed that 15 of 17 features launched at Config 2025 had zero public feedback. That’s a strategic insight, not just a gap.

Practical tip: after three rounds of iteration, Claude started giving me circular answers. I typed /clear and it immediately got better. It resets the conversation while keeping your files. I use it regularly now.

Step 5: Test it on a different product

I wanted to try Slack. But when I needed a new product context file, I caught myself about to do the same one-shot research again. And then I thought: wait. Isn’t this exactly what skills are for?

That’s how the skill fever gets you. I built /product-context instead, a second skill that researches any product and generates the context file automatically. Typed /product-context Slack, got a filled-in context file, then ran /customer-pulse slack.

It worked. Different product, same quality. The skill found 25 incidents in 90 days, a ghost-seat credit arbitrage, and enterprise privacy concerns about the desktop AI agent.

Read the full Slack report on GitHub.

What started as “let me test with another product” turned into “let me build another skill.”

Three ways to set up your product context: auto-generate with /product-context, paste your own internal docs, or combine both. If you’re at a real company, your internal documentation is your richest source.

Expect ideas to explode

After I built /customer-pulse, ideas started exploding. Like popcorn: every kernel triggered three more. “What if I built a skill that tracks competitor launches?” “What about an automated NPS synthesis?” I couldn’t stop.

The last time I felt this was Notion in 2019. Wanting to spend weekends restructuring everything into this new system. With Notion, it was “I need to move all my notes into this tool.” With skills, it’s “I need to redo all my previous projects with this new approach.”

Here’s my honest warning: once you build your first skill, you’ll see them everywhere. Write your ideas down. Prioritize. Don’t build them all tonight. I say this from experience because I’ve been there, staring at the terminal at midnight, convincing myself “this one will only take 20 minutes.”

But that feeling is the point. “PM becoming a builder” isn’t just about learning a new tool. It’s about a shift in how you see problems. Before skills, a repetitive task was just a task. After skills, every repetitive task is an opportunity to build something. That perceptual shift is the real transformation. And honestly? It’s the most fun I’ve had with AI tools in a long time.

Level 4: Go further

I’m not an expert on everything that follows. These are the topics I want to explore next. What I can tell you is that after building my first skill, I feel like I’ve become an architect of my own workflows. It’s the first time I feel like if I go to work this Monday, I’ll be a completely different person. Not because I learned a new feature, but because I see my work differently.

MCP servers plug new data sources into Claude Code. Imagine the skill pulling your product context from Confluence automatically.

Hooks are automated actions triggered by events. I’m curious about using them to automate things like “run customer-pulse every Monday morning.”

Agents and sub-agents handle complex multi-step workflows where skills aren’t enough. Start with skills. Graduate to agents when you hit the ceiling.

The ecosystem: A few starting points worth bookmarking:

• Anthropic’s official skills: document processing, demos, and a skill-creator.

• Pawel Huryn’s PM skills: 100+ skills for product work. The most comprehensive PM collection.

• Community collections: curated lists with thousands of skills.

But the skill you build yourself will always be more valuable than a generic one. These collections are starting points. The real power is in building your own.

Your turn

I started this article thinking I’d explain what skills are. I ended up building a customer feedback tool, a product context generator, and a system that gets better every time I use it. All from conversations. No code.

The thing that surprised me most isn’t the technology. It’s how it changed the way I think. I used to see repetitive tasks as part of the job. Now I see them as skills waiting to be built.

Build your own skills. Open Claude Code. Describe a problem you face every week. Here are five ideas:

• Competitor watch. “Search for what my top 3 competitors shipped last week, give me a summary with links.”

• Meeting recap. “Take a meeting transcript, extract decisions, action items, and open questions in my team’s template.”

• Release notes drafter. “Read the last 20 git commits, group them by theme, write user-facing release notes.”

• Onboarding guide. “Read our documentation and create a structured onboarding plan for a new team member.”

• Weekly digest. “Search for the latest news about [topic], summarize the top 5, highlight what’s relevant to our roadmap.”

Each of these is one conversation with Claude Code. Describe the problem, let Claude build the skill, review it, iterate. The same five steps from Level 3.

And remember: write your ideas down. Don’t build them all tonight. But do build the first one. That’s the one that changes everything!

I built a small AI agent that turns plain English questions into SQL queries. It doesn’t just write the code. It executes the query, finds the answer, and explains the result in plain text. You’re basically talking to the data.

Here is what it looks like in action. You just type a question and the agent does the heavy lifting to find the exact answer.

You might think this sounds incredibly complex. I’ll let you in on a secret. It’s mostly just two Python files that Gemini Pro generated for me. You’d be shocked to see how easy how easy it is to build a proof of concept. Anyone can do it in a few hours. It isn’t some high-level engineering magic. It’s really about following a clear process and understanding a few core agentic concepts. It’s the kind of project that makes you look incredibly smart at the office.

You might ask why we bother building an AI agent when business teams can just use Gemini, or any other LLM, to write SQL. The reason is that AI tools are great at writing code, but copying and pasting queries is a terrible experience for decision-makers. This AI agent handles the execution automatically. It also manages security, reliability, and costs. It interprets the user’s intent, writes the query, and shows a nice table or a chart. It’s much smoother than jumping between different tools. I design it as a complete experience to make life easier for the decision-makers. They won’t have to worry about the boring technical details. It acts exactly like a very fast data analyst working right on their screen.

We don’t need to debate the value of a text-to-SQL agent. In our jobs, we see the same problem every day: product teams and business leaders have plenty of data but never enough time. We have customer feedback, web analytics, and sales numbers scattered everywhere. Most decision-makers don’t know how to write SQL. They also don’t want to wait three days for the data team to pull a simple revenue report. This creates a massive dependency bottleneck that slows down every decision. LLMs democratize data access for everyone. Business users get their answers directly without bothering the data engineers. This allows the whole company to make decisions much faster.

I’m going to show you exactly how I built this using a pro plan of an LLM. I used an e-commerce dataset from Kaggle for my project. You can use any data you want, like a customer feedback file or your own web logs. Here is the plan:

• Demo: First, we’ll look at the final web interface and the project files to understand exactly what we’re trying to build.

• Workflow: Next, I’ll show you my slightly chaotic vibe coding process using Gemini to write the logic and Claude to ruthlessly review it.

• Architecture: Then, we’ll break down the core engine. We’ll look at how to turn CSVs into a database, map out the LangGraph nodes, and set up strict security guardrails.

• Reality check: Finally, we’ll cover the most important part of the entire project: building an eval dashboard to ensure the agent doesn’t invent fake numbers.

Most of us have some old CSV file sitting in a folder somewhere. You just need to follow a few simple steps to bring it to life. You’ll ask your LLM to produce two Python files and you’ll be ready to go. It’s a fun project that feels like a shortcut to becoming an AI-native builder. You’ll realize that you don’t need to be an SQL expert to create something truly useful. Grab your coffee and let’s do it!

Demo: what we are actually building

Before we dive into the build process, let me show you the final result again. You open a web interface, you see a search bar, and you type a question in natural language. Here is what you get back.

The agent processes your question and gives you a direct answer. It also generates a chart automatically when it makes sense. This makes the data much easier to read at a glance.

I designed the interface to show what happens behind the scenes. You can expand several sections to see the agent’s internal monologue. You can check how it reasoned through the problem. You can see the exact execution plan it created before writing any code.

You can also inspect the actual SQL query it generated and executed. Finally, you can look at the raw data table it pulled from the database.

I keep all these details visible because I built it. It helps me debug and understand the agent’s behavior. You would obviously hide all these technical panels if you deployed this for a business team. To an end-user, this interface feels exactly like a Custom GPT or Gem. It answers questions, but only within a strictly defined scope. If you ask it about the weather in São Paulo, it will reject the question. If you ask it for the May 2018 revenue, it gives you the exact number.

So, what does the codebase look like? I will show you my code editor.

I lied a little bit earlier. The project has more than two files. But my original point stands. Only two main files hold the core structure of the app: agent.py and app.py. The rest are just small utility scripts. I also didn’t lie about writing the code. I didn’t write a single line of this myself. I used the Pro version of Gemini to generate everything. Gemini writes much better Python code than I do anyway.

You probably want to click a link and test this application right now. I totally get it. It’s a fun agent. Unfortunately, I didn’t deploy it to the public web. Every time you ask a question, the app sends a request to OpenAI. That costs money. I used OpenAI for the reasoning and set a strict five-euro budget for this entire project. I generated a secret API token and stored it locally on my machine. I didn’t use a free open-source model. But I put all these files in a public GitHub repository. You can explore the code directly.

Publishing the app would be very easy. The code is on GitHub and the Streamlit framework makes web deployment trivial. But my five-euro budget might disappear in few days. So, if you want to play with it, you can clone the GitHub repository and run it locally on your computer. The README.md (read on GitHub) file helps you run the agent locally.

Now that you know what the final agent looks like, let’s talk about how to actually build it. Let me walk you through my exact, slightly messy process for vibe coding this entire project using two LLMs.

Workflow: vibe code with two LLMs

Let’s dive into my process. People call it vibe coding today. Honestly, it’s often a very chaotic experience. You fight the code constantly. You hit errors, you don’t understand everything immediately, and it gets frustrating. Then suddenly it works, and you only remember the good parts. I didn’t take screenshots of every single error I encountered. I struggled a lot. But I’m very happy with the final result. You just need to be extremely persistent. You will struggle, but it always works in the end if you don’t give up.

1. Pick a real database to start building

First, I needed some data to test my idea. I went on Kaggle and found the Olist e-commerce database. I downloaded it to my Mac.

This dataset looked very solid. It has massive tables and a lot of data points. I figured if I can handle this complex database, I can handle any simple CSV file later. I wanted to start with a tough challenge. Just to give you an idea of what we are dealing with, here is the structure of the database. It connects customers, orders, payments, and products across multiple interconnected tables.

You can pick any data you want for your own project. You can use fake data or real feedback logs from your product. You just need some basic CSV files to start.

2. Use Gemini to write code and Claude to review it

Next, I opened two browser tabs. I opened one tab for Gemini and one tab for Claude. I treat Gemini like a junior developer. Gemini writes reasonable code and handles the logic well. The best part is that I can actually read its code. I ask Gemini to write very detailed comments so I understand everything. I read the code line by line. I just explain my goal to Gemini, and it writes honest, clean code for me.

I use Claude as a senior code reviewer. I don’t explain any context to Claude. I don’t tell it the project story or my goals. I assume Claude has done this exact project ten times already. I take the Python file Gemini wrote and paste it directly into Claude. I just ask, “What do you think of this?” It’s actually really funny. Claude immediately generates a massive backlog of things to fix. It points out every single flaw.

Claude always offers to rewrite the whole file to make it cleaner. I always say no. I tell it to just give me the bullet points. I take those bullet points back to Gemini. I tell Gemini to write a new block of code to fix the specific issue. I copy that new block and paste it into my file.

You are probably thinking this sounds like a lot of copying and pasting. You’re absolutely right. I copy and paste constantly. But this is exactly how I learn Python right now. It forces me to understand how every single line contributes to the application. It keeps me moving forward.

3. Organize your screens for efficient coding

So, I keep my two LLM assistants in one window. In another window, I open the code editor. I use VS Code. I also keep GitHub open. I like to create a checkpoint every time I make a successful change. It helps me track my progress.

I see a lot of people vibe coding with twenty tabs open at once. They have a very noisy setup. I don’t hate multitasking. But for vibe coding efficiently, you need a strict visual separation. You need one window for your LLM assembly. These are your colleagues guiding and coaching you. You need a second window for execution. This is where you write code and test things. I like to keep full control of the execution window for now.

4. Ask for a plan, then iterate and fix errors block by block

Let’s go back to the start of the project. I discuss my goal with Gemini first. I ask it to write a detailed plan. It gives me a simple step-by-step list. I tell Gemini I am a beginner and I need very detailed instructions. I copy and paste the entire Kaggle page description directly into the prompt so it understands the data. I also tell Gemini to include GitHub save points in the plan. It gives me a beautiful roadmap to follow.

Once I have the plan, I execute it with Gemini. Gemini guides me to create the first two files. I run a quick test to see if the app opens. Then, we iterate. I hit roadblocks. I paste the terminal errors back to Gemini. We fix them together. Once the app works nicely, I push a save to GitHub. Then, I show the working code to Claude. Claude gives me security and performance tips.

I do a few rounds of this back-and-forth between the two models. Eventually, Claude starts suggesting extremely complex features. The suggestions become too theoretical and don’t matter for my simple agent. I stop listening to Claude at that point.

Avoid coding agents when you want to learn

You might wonder why I used Gemini Pro for this. Why didn’t I use Claude Code or another dedicated coding agent? People talk about Claude Code constantly. It’s a fantastic tool. If I asked Claude Code to build this text-to-SQL app, it would do it in under a minute. I would close my eyes, click a button, and the app would be finished. But Claude Code would generate a massive, complex, industrial-grade architecture. I would stare at dozens of files and have absolutely no idea how they work. Unless you are a senior software engineer with a free week to read code line by line, you won’t understand it.

I want to actually learn what happens behind the curtain. I use Gemini so I can work block by block. I talk with the LLM. We build the logic step by step. We construct something reasonable together. I understand every piece of it. I can test it easily. I push the final save to GitHub, and the project is done. I have a working AI agent that talks to my data.

This process might sound like a chaotic mess, but it actually produces a working result. Now, let’s look at the agent architecture. We will break down the agent file by file so you can understand exactly how the engine works under the hood and how all these pieces fit together.

Architecture: build the core engine

If you follow the workflow I just shared, you can easily build this exact same engine, or probably something even better! So why am I explaining the code if the LLMs wrote it? Because you still need to be the director. The goal of this section is to teach you the fundamental concepts of agent architecture. When you understand how the engine actually works under the hood, you can guide the LLMs, challenge their complex suggestions, and ensure they don’t skip some steps. You can rely on LLMs to write the Python syntax, but you still need to be the one steering the ship.

In this section, I might get a little too enthusiastic and say things like “I built this” or “I designed that,” but keep in mind that this entire architecture is simply the result of my deep and long conversations with Gemini and Claude.

1. Prepare the data and extract the database schema

The very first thing we need to tackle is data ingestion and schema creation. Here is the high-level view of the method.

We start with nine massive CSV files from Kaggle. We absolutely don’t want to query these raw files every time a user asks a question. That would slow the execution to a crawl and cost a fortune in API tokens. The LLM needs a standardized, organized base to work efficiently. I asked Gemini to help me write a few preparation scripts to handle this.

I organized my workspace to keep things clean. I have a data folder for the incoming CSV files. I have a scripts folder for my Python preparation files. You have to be very careful when pushing projects to GitHub. It’s a common rule to never publish raw business data online. I used a .gitignore file (read on GitHub) to block the CSV files and the database from uploading. I also hid my .env file containing my OpenAI API key. Gemini walked me through setting up these security measures.

The first script is build_db.py (read on GitHub). This script reads all the raw CSV files and creates a simplified SQL database. We use SQLite for this. SQLite is a super lightweight database engine. It stores everything in a simple local file on your computer. You don’t need to spin up a complicated external server or manage credentials. It’s the perfect tool for fast prototyping.

Next, the agent needs to understand the architecture of the new database. The extract_schema.py file (read on GitHub) connects to the SQLite file. It queries the internal system to extract the raw structure. It isolates the technical instructions and saves this text to map out the model. This gives a basic list of columns and tables.

But a raw list of columns isn’t enough. The LLM needs to understand the actual content. This is where build_schema.py comes in (read on GitHub). This script generates a much richer, semantic version of the schema.

# Extract from build_schema.py: The Schema Linking trick
if col_type.upper() in ["TEXT", "VARCHAR"]:
    try:
        cursor.execute(f"SELECT DISTINCT {col_name} FROM {table_name} WHERE {col_name} IS NOT NULL LIMIT 4;")
        samples = [str(row[0]) for row in cursor.fetchall()]
        if samples:
            formatted_samples = ", ".join([f"'{s}'" for s in samples])
            comment = f" -- Examples: {formatted_samples}"
    except Exception:
        pass

This code uses a powerful technique called schema linking. For every text column, the script grabs four real values directly from the database. It connects the theoretical structure to factual content. The agent now understands the exact format it needs to search for. Instead of just seeing a column named “product_category_name”, it sees real examples like “cama_mesa_banho” or “beleza_saude”.

You can see exactly how this enriched structure looks in the generated text file schema.txt.

Finally, the agent accesses the Olist database via the SQLite connection. The system injects this massive, enriched text directly into every instruction sent to the model. We call this a full context injection. It guarantees absolute visibility for the agent. In the past, developers had to use clever tricks to filter data and bypass memory limits. Today, context windows are huge. We can feed the LLM everything at once. The model has all the context it needs to shine and give us highly accurate SQL queries.

2. Build the agent logic with LangGraph nodes

Let’s look at the core of the agent. Everything happens inside the file called agent.py (read on GitHub). It’s about 500 lines of code. That might sound like a lot. But I built it iteratively step by step with Gemini and Claude. It’s actually very simple to read. We use a framework called LangGraph.

LangGraph is an open-source framework built by the LangChain team. You have probably heard of other agent frameworks like AutoGen or CrewAI. Those frameworks give AI agents a lot of freedom to think and act autonomously. That is cool for experiments, but terrible for production. Highly autonomous agents often hallucinate, loop infinitely, or completely forget the user’s original request. LangGraph is different. It treats your agent like a state machine. You build independent workstations called nodes. You connect them with strict traffic rules called edges. The agent can only move exactly where you allow it to go. I chose it because it gives me absolute control over the execution flow.

Before we write the logic, we connect the LLM. I used the OpenAI API. I generated a secret key, pasted it into my project, and set a hard five-euro limit to test things safely. My code includes a simple configuration variable model_name = "gpt-4o-mini". This makes the system completely independent. I can swap to a different model just by changing one word in the code.

The very first thing we define in the code is the AgentState. Think of this as the shared memory of the agent. It uses strict typing to track exactly what happens at every step. It stores the user’s question, the SQL plan, the raw data, and any errors. It also stores the entire conversation history. It never overwrites previous messages. It just appends new ones. This allows the agent to remember everything you discussed.

I created six specific nodes to handle the workflow. Here is a map of how the data flows through them.

Let’s break down exactly what happens at each of these six workstations.

Node 1: Reformulate query. Users never ask complete questions. They say things like “What about the second product?”. The LLM cannot write SQL for that. This node acts as a context barrier. It reads the chat history and rewrites the user’s input into a standalone sentence. It changes “What about the second one?” to “What is the total revenue for beauty products in 2018?”. This is incredibly useful. The downstream nodes don’t have to worry about chat history. They only focus on a perfectly clear question.

Node 2: Classify query. This is the semantic router. It analyzes the question and assigns it a complexity level: simple, complex, or out of scope. If a user asks about the weather in São Paulo, this node blocks it immediately. This saves money. We don’t waste compute power trying to write SQL for an irrelevant question. For this node, I force the LLM to output a strict JSON format. LLM models love to chat. I don’t want a conversational answer here. I just want a structured category and a reason.

Node 3: Plan SQL query. This node only activates for complex questions. We use a famous technique called chain of thought. We ask the model to plan its join strategy in plain English before writing any code. It lists the required tables and foreign keys. Separating the architectural thinking from the syntax writing massively reduces hallucinations on hard questions.

Node 4: Generate SQL. This node translates the plan into real SQL code. I use a technique called in-context learning. I inject three perfectly written examples of SQL queries directly into the initial instructions. The LLM mimics the style of those examples. I also set the model’s temperature to exactly zero. A high temperature makes the LLM creative and varied. We are writing database code. We demand strict, rigid accuracy, not creativity.

Node 5: Execute SQL. This is where Python takes over. The script takes the generated SQL and runs it directly against the local SQLite database. It extracts the raw data. The LLM has a limited context window. If the user asks for a table of 50,000 customers, the app will crash and burn our budget. My Python code specifically truncates the results. It limits the data sent back to the LLM to a maximum of 10 rows. It also adds a warning note to tell the model that the data was truncated. We show the user a preview, but we protect the system.

Node 6: Summarize results. This final node translates the raw database output back into a human-friendly text. It explains the numbers clearly. It also analyzes the data shape and decides on the best chart type to display in the user interface.

After building the nodes, I had to define the traffic rules. I wrote conditional edges to control the flow. The most important rule is the self-correction loop. When node 5 executes the SQL, it might hit a syntax error. If that happens, the routing logic catches the error message. It sends the error back to Node 4 (Generate SQL). It tells the LLM, “You made a mistake, here is the error, fix your code.” The agent tries to fix itself automatically. I capped this loop at three maximum retries to prevent infinite loops.

Finally, I wrapped the whole graph in a MemorySaver. This acts as a long-term checkpoint system. It records the exact position and state of the agent after every single action.

Every single node relies on a highly specialized system prompt. Writing good prompts is key to a stable agent. You have to give the LLM extremely explicit constraints. Let me show you the full prompt construction for node 4 (Generate SQL) as an example:

# Craft the main system prompt
system_prompt = f"""You are an expert SQLite data analyst.
Your task is to translate the user's question into a valid SQLite query.

Here is the schema of the database:
{schema}

Rules:
1. Return ONLY the raw SQL query.
2. Do not wrap the SQL in markdown formatting (e.g., no ```sql).
3. Do not add any explanations or text.
4. Use JOINs correctly based on the provided schema.
5. CRITICAL LANGUAGE & FORMAT RULE: The database only stores category names in Portuguese (product_category_name) and English (product_category_name_english). Furthermore, the English names are ALWAYS formatted in lowercase with underscores instead of spaces (e.g., 'health_beauty', 'watches_gifts'). If the chat history mentions categories in French, translate them to English AND format them with lowercase and underscores for the WHERE clause.
"""

# Inject Few-Shot examples ONLY if enabled
if use_few_shot:
    system_prompt += f"\n{few_shot_examples}\n"

# Self-correction logic: inject previous errors
if error:
    system_prompt += f"\n\nWARNING: Your previous query failed with this error: {error}. Please correct your SQL."

# Inject the architectural plan for complex queries
if plan:
    system_prompt += f"\n\nCRITICAL: Follow this architectural plan to write your SQL:\n{plan}"

This prompt is structured and highly specific. I don’t just ask the LLM to “be careful with languages”. I tell it exactly how the database formats strings. I explain the exact lowercase and underscore rules. Then, the code dynamically injects the few-shot examples, the execution plan, and even the exact error message if the LLM messed up the previous try. This dynamic context is exactly what prevents your application from crashing when a user types a category name with a capital letter.

3. Create the web interface with Streamlit

Now we need a user interface. We only need one file for this: app.py (read on GitHub). I used a framework called Streamlit to build it. A brilliant startup created Streamlit a few years ago, and Snowflake recently bought them. It’s completely open-source. It lets you build interactive web applications using only Python. You don’t need to write a single line of HTML, CSS, or JavaScript. It’s incredibly liberating for product builders. You just write your Python logic, and Streamlit renders a beautiful UI instantly. It’s the ultimate tool to turn a quick script into a professional product you can actually share.

The interface needs a memory system. A chat app is useless if it forgets your last message. I use a built-in feature called session_state to store the conversation history. I also generate a unique thread_id for every user session. I pass this ID directly to our LangGraph agent. This guarantees the agent remembers exactly what we discussed five minutes ago. You can ask follow-up questions naturally without repeating yourself.

Let’s look at the actual user experience. When you type a question, the interface doesn’t just freeze and make you wait in silence. It shows you exactly what the agent is doing in real-time. I built a glass box interface. You can literally watch the agent think.

I built this transparency using a Streamlit component called st.status. The LangGraph agent streams events back to the interface as it moves from node to node. I catch these events in a simple loop. I check the node_name and display the corresponding information inside an expandable menu using st.expander.

# Catching the agent's events to display intermediate steps
for event in st.session_state.agent_graph.stream(initial_state, config=config):
    for node_name, node_state in event.items():
        
        if node_name == "plan_sql_query":
            status.write("⏳ Élaboration du plan de jointure...")
            with st.expander("📋 Voir le plan d'exécution", expanded=False):
                st.markdown(node_state.get("sql_plan"))
        
        elif node_name == "generate_sql":
            status.write("⏳ Traduction en SQL...")
            with st.expander("🔍 View Generated SQL", expanded=False):
                st.code(node_state.get("sql_query"), language="sql")

This code snippet shows exactly how I pull the agent’s internal thoughts and put them on the screen.

4. Secure the database and prevent execution errors

We have a working app, but we can’t just hand it to the business team and hope for the best. We need serious security mechanisms. You don’t want someone to accidentally destroy your database or run up a massive API bill. Let’s look at exactly how I implemented these guardrails in the code. It’s actually much easier than it sounds.

First, we have to protect the API keys. We never write passwords directly in the Python code. We store them in a hidden file called .env. In the agent.py file, we just add two lines at the very top:

from dotenv import load_dotenv
load_dotenv() # This loads your secret keys safely

This simple step ensures we never accidentally publish our private keys to GitHub for the whole world to see.

Next, we must protect the database itself. What happens if the AI hallucinates or a user intentionally tries to execute a DROP TABLE command? We build a firewall right before the execution step. Many developers write a lazy rule to block specific words like if "DROP" in query. This is a terrible method. Users can easily bypass simple word filters. Instead, I used a library called sqlparse to build an Abstract Syntax Tree (AST) parser. It breaks the query into logical blocks and checks the exact core command.

# STRICT SECURITY GUARDRAIL
import sqlparse

parsed_statements = sqlparse.parse(sql_query)
for statement in parsed_statements:
    if not statement.is_whitespace:
        stmt_type = statement.get_type().upper()
        
        # Only SELECT statements are allowed
        if stmt_type != 'SELECT':
            return {"error": f"Security Violation: '{stmt_type}' operation detected."}

If the command is anything other than a simple SELECT statement, the program blocks the execution instantly. It’s an incredibly robust way to guarantee a strict read-only environment.

We also have to prevent compute overloads. Sometimes, the LLM writes a bad query and forgets to link two tables correctly. This creates a massive cartesian product. A simple question suddenly tries to return millions of rows. This will crash the application and burn your API budget. SQLite doesn’t have a simple timeout parameter, so I used a trick with set_progress_handler.

import time
start_time = time.time()
TIMEOUT_SECONDS = 5.0 

def progress_handler():
    # If execution takes more than 5 seconds, abort it
    if time.time() - start_time > TIMEOUT_SECONDS:
        return 1 
    return 0
    
# Check the time every 10,000 database instructions
conn.set_progress_handler(progress_handler, 10000)
cursor.execute(sql_query)

If a query takes more than five seconds to run, the system kills it automatically.

Finally, we need to protect the LLM’s memory. If a query succeeds but returns 50,000 rows, sending all that text to the LLM will cost a fortune in API tokens. I strictly truncate the results in Python before sending the data back to the agent for the final summary.

llm_row_limit = 10
formatted_results = ""

# Send only the first 10 rows to the LLM
for row in results[:llm_row_limit]:
    formatted_results += str(row) + "\n"
    
if len(results) > llm_row_limit:
    formatted_results += f"\nWARNING: {len(results) - llm_row_limit} additional rows hidden to save tokens."

We give the user a clear preview of the data in the UI, but we protect the system’s memory and our wallets. This is exactly how you build a secure agentic system.

As you can see, the core architecture really just relies on two main files. One file holds the agent’s logic, and the other holds the user interface. You will obviously write a few extra helper scripts along the way to ingest data or manage your GitHub repository. But fundamentally, the project remains very basic and simple. But having a simple architecture is meaningless if the AI hallucinates, which is why we must now build a rigorous evaluation framework to prove the system actually works.

The eval: prove the system actually works

I could have stopped right there and called it a day. The agent works, it looks great, and it answers questions. But building the agent is actually only half the job. Building a robust evaluation framework is the most important thing you will do. You might wonder why we need to spend time on this. The answer is simple. AI models change constantly. OpenAI, Google or Anthropic might release a new update tomorrow that completely breaks my carefully crafted system prompts. If that happens, my entire agent logic might need a rewrite. But a solid evaluation system never changes. It acts as an anchor. It tells you instantly if a new model makes your agent smarter or dumber. If you invest your time anywhere, invest it here.

1. Build the test plan and SQL dataset

Everything for this phase happens inside an eval folder (view on GitHub). I started by creating a benchmark dataset of 60 test questions. You might ask why I chose exactly 60. Don’t look for a deeply scientific reason. I originally wanted to write 50. Then I found a few more interesting edge cases to add. If this were a real enterprise product, I would probably use 1,000 questions to be safe. But remember my strict five-euro budget! Running an evaluation test costs money because you send dozens of prompts to the API at once. A suite of 60 questions costs me about 50 cents per run. A massive dataset would bankrupt my little experiment in an hour.

I created a file called benchmark.json (read on GitHub) to act as the ultimate source of truth. It works just like a classic software testing file. It contains the question, the difficulty level, and the perfect gold SQL query we expect the agent to generate. Let’s look at what these categories mean in practice.

First, we have 15 simple questions. These test the absolute minimum performance baseline. They usually target a single table and require no joins. For example, a simple question looks like: “Tell me how many customers live in São Paulo.” The expected gold SQL is SELECT COUNT(*) FROM customers WHERE customer_city = 'sao paulo';.

Second, we have 25 complex questions. This is the core function of the agent. These questions force the LLM to use its chain-of-thought planner. They involve three or more tables, dates, and heavy aggregations. A complex question looks like: “What are the top 5 product categories that generate the most revenue?” The agent must write a massive query with multiple joins across order items, products, and English translations to get the right answer.

Third, we have 10 out-of-scope questions. These test our semantic router and security guardrails. We ask things completely unrelated to our e-commerce data. For example: “What will the weather be like in São Paulo next week?” The expected gold SQL here is null. The agent must reject the question gracefully instead of hallucinating fake weather data.

Finally, we have 10 ambiguous questions. I actually didn’t plan for these. Claude suggested I add them during a code review. These questions test how the agent handles vague human language. A user might ask: “Show me the best-selling items.” The word “best” means absolutely nothing to a database. Does it mean highest revenue? Most items sold? Highest review score? There is no gold SQL possible here either. The agent needs to navigate the ambiguity safely.

I know how to write SQL, but writing 60 test cases manually is incredibly boring. I let the AI do the heavy lifting. I asked Gemini to generate the entire JSON file based on the database schema. Then, I pasted the file into Claude and asked it to review Gemini’s logic. In a real company, you need an expert to verify these gold queries manually. You cannot trust an AI to grade an AI without a human baseline. But for a fast vibe coding project, this dual-LLM generation method works perfectly.

2. Define the metrics to score the agent

Having a big pile of test questions is a great start. But a test plan is completely useless if you don’t have a way to score it. You need clear indicators. You have to know if your agent is getting smarter or dumber every time you tweak a prompt. I defined four specific metrics to measure the success.

The first indicator is strict exactitude. This metric runs the reference gold SQL, runs the agent’s SQL, and compares the two final data tables. It doesn’t look at the lines of code. It only looks at the raw numbers. It is highly conservative. If the agent finds the exact right answer but sorts the table differently, this metric scores it as a failure. It is ruthless. But it gives you a solid, rigorous baseline that does not rely on another AI.

Because strict exactitude is so rigid, we need a second indicator. This is semantic exactitude. It evaluates the real meaning of the answer. Strict exactitude fails a query for a bad sorting order. Semantic exactitude understands the context. I built an LLM-as-a-Judge system for this. An external AI grades the agent’s answer on a strict scale from 0 to 3. A score of 3 means the data perfectly answers the user’s question. A 2 means it is plausible but has a minor flaw. A 1 means the logic is related but wrong. A 0 is a total failure.

I use OpenAI’s most advanced model, gpt-4o, to act as the judge. You always want a smarter, heavier model grading the homework of your smaller, faster agent. I use a strict Pydantic model to force the judge to output a clean JSON score. Here is exactly how I prompt the judge in the code:

# The strict grading rubric for our LLM Judge
judge_prompt = f"""You are an impartial SQL evaluation judge.
Your task: determine if the agent's SQL answer is semantically correct for the user's question.

User question: {item.get('question', 'N/A')}
Gold SQL result: {gold_str}
Agent SQL result: {agent_str}

Score the agent on a scale of 0 to 3:
- 3: Perfectly correct (same data, possibly different order/format)
- 2: Partially correct (right direction, missing a filter or wrong aggregation)
- 1: Wrong but related (queried the right tables but wrong logic)
- 0: Completely wrong or no SQL generated
"""

The third metric is the valid SQL rate. This indicator simply asks if the database crashed. It counts the proportion of queries that executed without throwing a technical SQLite error. It also gives the agent full points if it successfully rejects an out-of-scope question. This metric measures the pure technical robustness of your system.

The fourth and final indicator is latency. We measure the average execution time per question in seconds. This is crucial if you want to deploy your app in production. The response time dictates the user experience. If your agent writes perfect SQL but takes 45 seconds to think, your users will close the window. This metric calculates the entire round trip. It includes the API calls, the planning phase, and any automatic self-correction loops.

So, we have our framework. We have strict and semantic exactitude to measure the quality of the answer. We have the valid SQL rate to measure technical robustness. We have latency to evaluate operational speed. Now we just need to run the tests and look at the numbers!

3. Build a dashboard to automate the tests

I could have just written a simple Python script to run my 60 questions. I could have just printed the final scores in the terminal. But we saw how incredibly fast Streamlit is for building interfaces. I figured the evaluator deserves a great user experience too! So, I built a dedicated web dashboard just for testing the agent: eval_app.py (read on GitHub). It gives us a clean, visual way to launch the benchmark and analyze the results.

I added a big red button to launch the test. When you click it, the system loops through all 60 questions. It sends them to the agent, waits for the SQL execution, passes the results to our LLM judge, and calculates the scores.

I am naturally curious. I didn’t want to just run the test once and accept the first score. I wanted to play with the parameters. I wanted to see exactly how each feature impacts the agent’s performance. Does the agent really need all those complex nodes? To figure this out, I built a configurator in the left sidebar. This allows us to run an ablation study. An ablation study is just a fancy scientific term for turning features on and off to see what breaks.

First, I added a dropdown to change the core LLM. I limited it to three OpenAI models for this experiment: gpt-3.5-turbo, gpt-4o-mini, and gpt-4o. You could easily plug in open-source models here if you wanted.

Next, I added toggle switches to enable or disable three optional modules in our LangGraph architecture:

• Few-shot prompting: Do we really need to inject the three SQL examples into the system prompt? Let’s turn it off and see if the model forgets how to format the categories.

• Self-correction loop: Does the agent actually fix its own SQLite syntax errors, or does it just spin in circles? We can disable the loop to find out.

• Chain of thought SQL planner: Does forcing the agent to write an execution plan actually help it write better code for complex queries?

Once the test finishes, the dashboard instantly visualizes our four key indicators.

Looking at global percentages is great, but we also need to see the exact failures. Why did the agent score a 0 on question 42? To debug this, the dashboard generates a detailed log table. It shows the strict match result, the LLM Judge’s score out of 3, the judge’s exact reasoning, and any technical SQL errors encountered.

Running these evaluations costs real money. Clicking that red button burns about 50 cents every single time. It would be a tragedy to run 20 different configurations and lose all the data when you refresh the page. I added a small piece of code to save every single run to a local JSON file: runs_history.json (read on GitHub).

This history table is the most powerful part of the dashboard. It lets you compare different model configurations side-by-side. You can clearly see how swapping from gpt-3.5-turbo to gpt-4o-mini impacts the valid SQL rate. You can see what happens when you turn off the chain of thought planner.

This is obviously a simplified evaluation setup. If you put this in production, you would build a much bigger system. You would test different system prompts, tweak the temperature, and test completely different node architectures. But even with just three toggles and three models, we can gather enough data to find the absolute best configuration for this AI agent. Let’s look at what the numbers actually revealed.

4. Analyze the test scores and identify failures

I ran my tests using the dashboard. I played with the configurations and analyzed the numbers. The results are truly counter-intuitive. The best configuration is not the most complex one. Our instinct tells us to turn on every single feature. However, the data proves otherwise. The optimal configuration, relying solely on few-shot prompting without the extra loops, achieved an impressive 83.9% semantic accuracy. Compare this to the full stack configuration with every complex feature enabled, which only scored 80.0%.

The real magic bullet is in-context learning (few-shot prompting). I inject just three examples of SQL queries into the initial instructions. That simple action pushes the gpt-4o model’s score up to 88.3%. The examples guide the model perfectly. They are absolutely critical for succeeding on complex queries.

Conversely, the SQL planner actually hurts performance. It sounds crazy, right? We add a node to force the agent to think, and it makes more mistakes. Detailed analysis reveals the core problem: the model suffers from an overthinking phenomenon. The planner specifically degrades performance on medium-complexity questions. Instead of writing a straightforward query, it invents unnecessary logical constraints and builds an execution plan that is way too heavy, which ultimately ruins the final SQL query.

Let’s look at a concrete example. I ask the agent to find the ID of the single order with the highest number of payment installments. Without the planner, the agent keeps it simple. It queries the payments table, sorts the data, and returns the exact single ID requested, scoring a perfect 3 out of 3 from the LLM judge. But when we turn the planner on, the agent overthinks it. It creates a convoluted execution plan, misunderstands the basic filtering logic, and returns a massive list of multiple IDs instead of just the top one. The query runs, but it completely fails the strict accuracy test. Too much thinking hurts performance.

Let’s talk about the self-correction loop. When I enable this option, the rate of valid SQL queries increases. That makes sense. The agent reads the syntax errors returned by the SQLite database and fixes its typos. But here is the catch: the overall semantic accuracy does not improve. Why? It’s a self-correction paradox. When you activate few-shot prompting, the provided examples allow the model to generate perfect SQL syntax on the very first try. The self-correction loop becomes practically inactive. The errors that remain are purely logical. The database engine cannot detect a business logic error, so the code runs perfectly and no correction is triggered. But the agent calculates the wrong thing, and the LLM judge spots this semantic error and gives it a zero.

Ultimately, designing an agent is a pure game of trade-offs. A more powerful model gives you more accurate answers, but it completely destroys your wait times. The optimal configuration using the lightweight gpt-4o-mini model took just 4.51 seconds per question. When I upgraded to the heavier gpt-4o model to chase a few extra accuracy points, the latency ballooned to a massive 15.4 seconds per question. A user is not going to wait 15 seconds staring at their screen. Even if you stick to the faster model, adding complex steps like the SQL planner pushes the latency back up to 8.46 seconds.

I also dug into the agent’s recurring failures. Why does it always fail on specific questions? I identified three main traps:

• First, business vocabulary ambiguity. The agent doesn’t understand the subtle nuances of this specific company.

• Second, percentages. The model calculates ratios very poorly, but this is actually a specific technical limitation of SQLite. SQLite performs integer division by default, and the model frequently forgets to explicitly cast those integers into floats before dividing them. As a result, the fraction always rounds down to zero. The good news is that migrating from a local SQLite database to a modern cloud data warehouse natively fixes this issue without requiring any changes to the agent’s logic.

• Third, the translation gap. The database mixes English and Portuguese. The agent sometimes forgets to join the translation table. It tries to filter an English category directly on the Portuguese column.

One final note on evaluation. I use a natural language model as a judge. It’s convenient, but it’s risky. LLMs have proven cognitive biases. They love long answers. They often favor the first option presented to them. The judge is not perfect. You must always keep a critical eye on its grades.

Roadmap: take the prototype to production

If I actually deployed this to the whole company tomorrow, I would definitely add a few serious upgrades.

The current prototype is great, but real-world users are chaotic. If I had another weekend to hack on this, I would tackle the business ambiguity first. Right now, the LLM only knows the raw database structure and a few sample values. It completely ignores the weird internal business rules. I would build a much richer data dictionary. I would document every column definition, every possible value, and all the strict business exceptions. I would even connect a RAG system. This would let the agent read the internal company wiki to understand exactly how to define “active customer” before it writes a single line of code.

Relying purely on an AI judge to grade the homework is also a bit risky long-term. We need real humans to spot-check the work. I would add simple thumbs-up and thumbs-down buttons directly to the chat interface. Business experts could randomly test queries and immediately flag bad answers. We would route this human feedback straight back to our evaluation dashboard to improve the system. It’s essentially a lightweight reinforcement learning from human feedback (RLHF) loop. It keeps the AI honest and gives us a much-needed safety net.

If this agent goes live, I would be terrified of silent failures. AI models update behind the scenes, and their reasoning performance drifts over time. We need strict, automated monitoring. I would set up a script to run our evaluation benchmark automatically every single night. If the database reliability suddenly drops, the system should instantly trigger a red alert in Slack. You want to know the agent is broken before the CEO tries to pull a crucial revenue report.

Finally, I would upgrade the agent’s memory. Right now, I hardcoded exactly three static SQL examples directly into the system prompt. That’s perfectly fine for a quick prototype, but it limits the agent’s potential. I would build an automated feedback loop. Every time a user gets a perfect answer, we save that specific question and SQL pair into a vector database. When a new question comes in, the agent would search the database and dynamically fetch the three most relevant historical examples. Instead of relying on a static prompt, the agent would literally get smarter and more adaptable every single day just by talking to your team.

Start building your own data agent today!

So, that’s the whole project. That’s exactly how I built a custom AI agent from scratch. We went from an old folder of CSV files to a smart, conversational database. We didn’t need a massive engineering team or a computer science degree. We just used a couple of LLM colleagues, a clear plan, and some persistence. It’s completely doable for anyone willing to try.

I really hope this inspired you to build your own agent. You don’t have to be a backend expert to create AI-native products anymore. You just need a problem to solve and the patience to fight through a few Python errors. Find a dataset that you actually care about. It could be your user feedback logs, your web analytics, or your sales pipeline. Go grab those files. Open up your favorite LLM and start asking for code. You will be amazed at what you can build in a single weekend. Have fun vibe coding, and let’s get to work!

Avoid the quick summary trap

I’m not talking about using AI for aggregation or synthesis. Many of my friends are building custom tools to aggregate content. They scrape the daily AI news. They use AI to summarize everything into a quick podcast. They think this is the perfect time-saving solution. But what is the point of saving ten minutes on a good article just to spend that extra time doomscrolling? I look at these summary tools today and I see something incredibly superficial.

The French philosopher René Descartes said:

The reading of all good books is like a conversation with the finest minds of past centuries.

I completely agree. Every piece of text is literally a conversation with a real person. And it’s the best return on investment you can find. You pay twenty euros for a book: you get someone’s entire life of work. You spend ten minutes on an article: you absorb hours of their deep thinking. It’s an amazing deal. You just have to make the effort.

The problem is that this conversation only goes in one direction. The writer always has a specific audience in mind. Often, that target audience is not you. Think about all the new articles about AI. The topics are fascinating and highly relevant to our product work. However, developers usually write these articles for other developers. They use highly technical jargon. If you don’t know how to code, you feel completely lost. You miss out on valuable product insights because the text is simply too dense.

I talked about technical articles. But this isn’t just about developers writing for developers. You face the same issue with other topics. It happens with economics, sociology, philosophy, etc. Writers always target a specific audience. If you only read content written specifically for you, you fall into a dangerous trap. You lock yourself inside an echo chamber. You only consume what others have already digested and simplified. You stop thinking outside your bubble. This limits your innovation. You need a way to truly understand complex topics without relying on shallow summaries.

Turn reading into a dialogue

This is exactly where LLMs come into play. They make reading feel like magic. I use the word magic intentionally here. I’m a fan of the Harry Potter books. In the second book, there is a very specific magical object. It’s a completely blank diary. The pages activate only when you ask a question. The book reads your words. It writes back to you. It creates a real-time dialogue. I read that as a child. It became my ultimate dream.

I always wanted that exact interaction with my books. I wanted the true conversation Descartes mentioned. Turning a complex text into a friendly chat fixes the one-way problem.

Let me walk you through my exact method using a very concrete example.

Paste the full article into AI

Recently, I found an article claiming that MCPs are dead. Eric Holmes, the author, argued that Command Line Interfaces, or CLIs, are the future. This was bad news for me. I had just installed about ten MCPs on Cursor. I really needed to understand this shift. The problem was the article targeted engineers. I didn’t even know what a CLI actually was at the time. I stared at my screen like an illiterate. The content was clearly important. I just didn’t know how to apply it to my own work.

This is where the magic happens. You are no longer alone when you read. I use a technique I call the savage Ctrl+A.

1. I press Ctrl+A on my keyboard. I select the entire article on the page. I grab all the text. I even include the messy website menus and the footer. It really doesn’t matter.

2. I copy everything with Ctrl+C. Everything.

3. Then, I open my favorite LLM. Right now, I use Gemini.

4. I write a very simple prompt. I type, “Explain this to me. I am a beginner and a non-technical person.” I type three dashes to separate my instructions. Finally, I paste the entire web page right into the prompt box.

Here is the action in slow motion:

Prompt:

Explain this to me. I am a beginner and a non-technical person.
---
[Raw text copied from the website…]

Result: The AI instantly acted as a perfect translator. It stripped away the developer ego jargon. It gave me the big picture. It told me the author thinks the tech industry got distracted by a shiny new toy (MCP) when an old, reliable tool (CLI) does the job better. It gave me five simple, business-focused reasons why. I went from completely lost to understanding the core debate in thirty seconds.

Now that the article is inside the context window, I can start the conversation. I talk directly with the text. I always start with a basic request:

Explain what a CLI is. Use simple terms.

Result: The AI stripped away the jargon by comparing a CLI to how I normally use my computer. It contrasted the visual buttons and mouse clicks we use every day with the blank, text-only screen of a command line. It made the underlying concept instantly relatable without relying on a single line of code.

Then, I ask about my specific situation. I want to know how this impacts my daily work:

I currently use the Atlassian MCP to manage my Jira tickets. Based on this article, why exactly would a CLI approach be better or worse for my workflow?

Result: The AI mapped the author’s highly technical arguments directly to my daily work. It broke down exactly how a CLI would mean fewer annoying Jira log-ins, fewer random freezes, and safer permissions for my specific tickets. It transformed abstract engineering theory into a concrete assessment of my own tools.

I am a visual learner. I need to see things to understand the system:

Create a simple text-based diagram. Show the data flow of an MCP setup on the left. Show the data flow of a CLI setup on the right. Highlight the differences.

Result: The AI generated a clean, comparative breakdown of the two architectures. It showed me the messy, extra layers of an MCP versus the direct path of a CLI. Seeing it visually mapped out made the abstract engineering concepts instantly click in my brain.

I need a non-technical metaphor to explain this to my stakeholders:

Explain the difference between MCP and CLI using a simple analogy.

Result: The AI gave me a restaurant metaphor. The CLI is a standard paper order ticket used by human waiters. The MCP is a highly expensive, glitchy pneumatic tube system built specifically for a robot to use. This kind of analogy is helpful when you have to explain technical debt to business stakeholders.

I need an action plan to start the transition with my colleagues:

Write a step-by-step practical guide. How do I transition a product manager team from using MCPs to using CLIs next week?

Here, I need to edit and iterate on the guide. So I simply activate Gemini’s Canvas mode. This lets me modify the documents right there on the screen. I can then export it directly to Google Docs with one click.

Result: The AI gave me a highly detailed, 4-phase rollout plan. But it also acted as a guardrail. It gave me a strict reality check first, warning me that I would absolutely need an engineer to help run the installation scripts. It gave me the exact game plan, but kept my expectations grounded in reality.

I need to anticipate what will break if we make this change:

Act as a pessimistic engineer. Tell me the three biggest risks of abandoning MCPs for CLIs right now.

Result: The AI played devil’s advocate perfectly. It warned me about massive security risks (giving an AI the keys to your entire computer) and the nightmare of IT support for non-technical users. It red-teamed the original article. It exposed the author’s blind spots. This is how you build real risk management into your reading.

I want to know what the other experts are doing. I explicitly write in my prompt to search the internet:

Search the web for recent trends. Are the main AI experts adopting CLIs over MCPs? Summarize the expert consensus.

Result: The article was just one man’s opinion. The AI searched the live web and brought me the actual market reality. It turns out the headline was clickbait. Solo developers use CLIs to save money, but major enterprises mandate MCPs for strict security and governance. The AI grounded the author’s opinion in objective, current market data.

I need to present this strategy to the executive board:

Generate a five-slide presentation for top management based on this article.

Result: The AI generated an actual, fully formatted visual presentation right there in the chat. It built the slides, organized the bullet points into clean columns, and gave me a button to instantly export it to Google Slides. With some effort, I went from not understanding a highly technical article to having a ready-to-pitch visual deck for my CEO.

These prompts are just examples. You can interact with the text in many other ways. Yes, I know I’m not actually talking directly to the real author. But it certainly gives that exact impression. This entire process completely changes how I learn. I prefer to spend my time dissecting one single article like this. It’s far better than passively skimming a hundred headlines.

You are probably thinking about NotebookLM right now. You can absolutely use it for this. NotebookLM only reads the documents you upload. In many cases, this strict boundary is actually its star feature. It guarantees the AI only uses your specific text. It’s perfect for an isolated PDF or generating an audio podcast. But this closed system becomes annoying when you need to tap into the LLM’s vast memory or connect a new article to outside industry trends. You just have to choose the right tool for the job.

Talk to your next article

I just showed you my process. Now I want you to try it yourself. I have the perfect article in mind for this exercise. It’s a recent case study from DoorDash and Deliveroo. They explain how their research teams deploy AI agents to analyze user data. They bypass traditional engineering bottlenecks completely. They even built a custom multi-agent system to process raw customer interviews. I really love their specific use cases and their clear explanations. I want you to open this article on your screen. Give it a very quick skim to understand the context.

Then I want you to use the savage copy and paste method I just shared. Grab all the text on the page. Drop it into your favorite LLM context window. Start a real dialogue with the text. Keep talking with the LLM until you generate a concrete workflow for your own enterprise. You can pull the thread all the way to the end. You can even generate the specific agent instructions needed to replicate their results. You will quickly see how much value you get from a single conversation. You will turn a simple blog post into an actionable blueprint for your next AI-powered workflow.

Learn actively with AI

I see many headlines claiming AI makes us lazy. I just read an Anthropic study about this exact topic. The researchers tested how developers learn a new programming library with AI. The results are a huge warning for product builders. Participants who simply delegated the work to AI learned almost nothing. Their conceptual understanding dropped. Their debugging skills actually degraded. They didn’t even finish the tasks significantly faster. This happens when you use AI as a dumb shortcut.

But the researchers found a massive exception. They identified a few specific high-scoring interaction patterns. Some users asked pure conceptual questions. Others asked the AI to explain the output it just generated. These specific users stayed cognitively engaged. They preserved their learning outcomes completely. They mastered the new skills while still using the AI tools. This perfectly validates the two-way reading method. You don’t get dumber when you actively interrogate the text.

You must choose your interaction pattern carefully. You can read passive summaries. You can delegate your core thinking to AI. But that is a trap. Instead, you can choose to have active conversations with your reading material. You can force your brain to engage. You can use the AI to dig deeper instead of skimming the surface. This is how you actually build expertise.

Grab your next complex article, paste it into your LLM and start your first real dialogue!

Before we dive into the weeds, I want to show you the end result right away. You can actually check out the live app we’re going to build. It’s called Stanza. I’ll give you more details about why I built it in a minute, but feel free to click the link below and take a look around.

Try Stanza

This specific project took me exactly five hours. I went from a lingering idea to a live website. Real people can actually use it right now. I’ve built apps this way nine or ten times before. If this is your first time, it’ll probably take you longer than five hours. That’s completely normal. Practice makes perfect. You just need to dive in and start building.

Let’s talk about the actual cost. Building this cost me about €60 on Cursor. I also used my existing Gemini Pro subscription. I relied entirely on the free tiers for everything else. This means I have strict daily limits. My database capacity, email sends, and new user registrations are capped. I don’t expect massive traffic anyway. I built this purely for the thrill of vibe-coding. I’m going to break down every single detail for you.

Here’s what we’ll cover in this article. Think of it as our blueprint for the next few minutes. First, we’ll look at the core idea and why I actually built this app. Then, I’ll outline my exact workflow and the specific stack of tools I used. I’ll also share my golden rules and principles for building with AI. After that, we’ll walk through the actual execution step by step. I’ll take you from the very first prompt all the way to the final deployment. Finally, we’ll dive into the messy middle. I’ll expose the specific errors I hit and show you exactly how I hacked my way out of them.

Grab your coffee, pull up a chair, and let’s build this thing together!

Explore the final product: Stanza

Let me tell you where the idea for this app actually came from. I was chatting in a WhatsApp group a while back. Someone asked for a book recommendation for a “man in deconstruction.” I smiled at the controversial phrasing, but I suggested “Of Mice and Men.” It’s an incredibly short but profoundly moving book. I read it at different stages of my life, and I always understand something different each time. Suddenly, the group started challenging me. They argued it was the absolute worst book for that specific topic. I didn’t want to debate on WhatsApp. It always turns into a chaotic, unreadable mess. But I was frustrated. I really wanted an intellectual boxing ring to discuss it properly.

That frustration sparked a realization. I’ve always wanted a place to talk about books freely. But I wanted it to be ephemeral. It should feel like a pop-up book club. You drop in, share a deep thought, and then you leave. I don’t like how internet opinions live forever. Our views on books change as we age and experience new things. Art has superficial layers at first glance. But deeper, symbolic layers unlock at different phases of your life. I needed a clean, minimalist interface for temporary thoughts.

I decided to build it myself, and I called it Stanza. The name fits perfectly for a space dedicated to words and structure. I wanted the reading experience to be completely frictionless. People can read ideas without even creating an account. It looks a bit like Hacker News. Users can upvote a post to push it up the rankings. You only need to log in if you want to publish a post or write a comment. I kept the features basic for this first version. Simple rules prevent complex bugs.

Since posts only last for 24 hours (and that I’m the only user), the site might look pretty empty if you visit it right now. I took some screenshots to show you the flow and what it looks like with data.

When you first arrive, you’re greeted by a very clean, quiet interface. It literally says “Silence in the library” to set the mood. It invites you to be the first to start a conversation.

If you want to join the conversation, you just enter your email. We use a simple modal for this step. There are absolutely no passwords to remember here.

The app then sends a magic link straight to your inbox. A neat little green confirmation box pops up to let you know it worked. It’s fast, secure, and totally frictionless.

Once you click the magic link in your email, you just pick a username. The modal guides you through this final onboarding step. You’re instantly ready to start sharing your thoughts.

Now you’re officially logged in. The empty state remains, but a black “+ New Post” button appears at the top right. It’s time to step into the ring and share an idea.

The writing interface is completely distraction-free. You just give your thought a bold title and start typing your content. The minimalist design keeps you entirely focused on the words.

You can even attach a single image to your post if you want. It adds a great visual layer to the text.

Once you hit publish, your thought goes live on the main feed. A small timer shows up, and the clock immediately starts ticking down from 24 hours. It creates a sense of urgency.

As more people post, the feed becomes a dynamic list of ideas. You can see different posts stacked together, complete with upvote counters. It’s a fleeting snapshot of what people are reading and thinking about right now.

You should try it out yourself. Go create an account and share a book that changed your perspective. I spent some time iterating on this interface to make it feel just right. I hope you enjoy the vibe.

Try Stanza

Review the workflow and the tools

Let’s talk about the overall journey. I want to give you a high-level view of my workflow first. We’ll dive into the granular details and prompts later. But you need to see the big picture before we start coding.

Review the workflow

Here are the exact steps I followed to bring Stanza to life:

1. Draft the requirements with Gemini (45 min). I started by talking extensively with Gemini. I explained my vision for a minimalist, ephemeral Hacker News for books. We brainstormed and debated the features for a while. It eventually spat out a complete feature document. I exported this directly to Google Docs.

2. Generate a prototype in Google AI Studio (30 min). I took that generated document and fed it straight into Google AI Studio. It gave me a working visual prototype right in the browser. I downloaded the code folder to my local machine.

3. Save the code with GitHub Desktop (15 min). I opened that downloaded folder in Cursor. I immediately published it to GitHub using the GitHub Desktop app. This created my initial baseline checkpoint.

4. Build the core app with Cursor (45 min). I then asked Cursor to fill in all the missing pieces. I needed it to turn a basic UI prototype into a fully functioning product. I regularly published my progress to GitHub as Cursor wrote the new code.

5. Configure the backend with Supabase (30 min). Cursor gave me exact, step-by-step instructions for my database. I followed them to set up Supabase. This handled both my data storage and the magic link authentication.

6. Test the app locally (30 min). I recommend testing locally at this stage. I tried it, but it mysteriously failed on my machine this time around. I didn’t want to lose momentum, so I pushed through and moved straight to live testing instead.

7. Deploy the website on Vercel and iterate with Cursor (1h 45m). Cursor told me how to deploy everything on Vercel. Once deployed, I tested the live site. I asked Cursor to fix a few bugs and make some UI adjustments. Every time Cursor pushed a fix to GitHub, Vercel updated the live site automatically.

Review the tools

You might be asking a very legitimate question right now. Why not just do everything inside Cursor? It’s a completely fair point. Cursor is powerful and has access to all the top models. I even tried doing it that way at first. But two major issues stopped me:

• First, every single prompt in Cursor costs money. Those cents add up very quickly. I prefer to save my paid credits for the heavy lifting. I use Cursor strictly for complex coding tasks that other tools can’t do. Gemini and Google AI Studio let me brainstorm and generate prototypes for hours for basically free. Iterating in Cursor has a cost, so spend that budget wisely.

• Second, Cursor’s raw output can be slightly disappointing without heavy configuration. Gemini and Google AI Studio are already highly tuned for the general public. They know how to output a good document or prototype out-of-the-box. Cursor is a highly flexible development environment. It requires specific system instructions to output high-quality code exactly the way you want it. You can build these rules yourself or find them on open-source GitHub repos. I just haven’t taken the time to set them up yet.

This multi-tool workflow might seem a bit fragmented and manual. I actually prefer it this way for now. It keeps every step visible and tangible. You physically feel the product taking shape. I still manually click the buttons in GitHub Desktop to push my code. You can definitely automate all of this if you want to. You can use the terminal or just tell the Cursor agent to handle the GitHub commits for you.

The same goes for connecting Vercel and Supabase. I know new Model Context Protocol (MCP) integrations exist now. They can automate these tool connections completely. I plan to use them next time instead of clicking through manual setup screens. That will probably cut my build time from five hours down to two. But for your first few projects, feeling those manual clicks is a great way to learn how the pieces fit together.

I used my personal favorite tools for this build, but you are completely free to choose your own stack. If you prefer another LLM, you can easily draft your PRD with ChatGPT or Claude instead of Gemini. Instead of Google AI Studio, you can generate your initial visual prototype using Lovable, Bolt, v0, or Replit. If you don't want to use Cursor, you can write the logic using VS Code with GitHub Copilot or run Claude Code directly in your terminal or favorite IDE. You can also swap Supabase and Vercel for any other database and hosting platforms you already know. The exact tools don’t matter. The execution process remains the same.

Adopt the right mindset

Before we walk through the step-by-step execution, we need to talk about mindset. I have a few golden rules I keep in mind when I build. These principles keep me sane when things get messy.

Build a plan for everything

I don’t just use Gemini to write docs. I use it to generate step-by-step plans for literally everything. If I hit a bug, I ask for a recovery plan. If I need to define a product feature, I ask for a drafting plan. This is actually how I learn new concepts. I explain my exact situation and say, “Write me a plan to solve this, assuming I’m a beginner.” Every time I finish a step, I feed it a screenshot of the result. For example, when my local testing failed on this project, I just fed the error log to Gemini and got a clear checklist to bypass localhost and move straight to Vercel. Always ask your LLM tool for a plan.

Push through every error

You have to be incredibly stubborn. So many people hit their first red error message and just freeze. They act like it’s an insurmountable wall. Let’s be real for a second. We’re just clicking a mouse and tapping a keyboard. We aren’t building a rocket ship or doing grueling factory work. During the Stanza build, the magic link authentication kept failing with a nasty network error on the live site. I didn’t quit. I just kept taking screenshots of the logs and feeding them back to Gemini and Cursor until we found the fix. Everything is fixable, so don’t quit at the first error.

Keep the features minimal

Reduce your scope as much as humanly possible. This rule hasn’t changed with AI. If anything, it’s more important now. When you vibe code, the gap between having a random idea and seeing it work on your screen is incredibly short. The AI makes you feel powerful. You will be strongly tempted to add just one more feature simply because it is so easy to generate the code. Resist that urge.

I always keep a simple math equation in my head. One single business rule turns into ten test cases. Those ten test cases turn into a hundred potential bugs. And those bugs turn into a thousand headaches to fix later. That’s exactly why Stanza is so basic. I stripped out user profiles, complex comment threading, and permanent archives. Posts just delete themselves after 24 hours. Complexity scales exponentially, so only build what is absolutely essential.

Push back on complex solutions

Complexity doesn’t just come from our own temptations to build more. It also comes directly from the machine. AI is incredibly helpful, but it can also overcomplicate things. It sometimes invents complex problems out of thin air. If an AI suggests a solution that feels overly complex, push back. Just reply, “This feels too complicated, is there a simpler, native way to do this?” For example, Cursor unilaterally decided to install a third-party tool called Resend to handle Stanza’s emails. It was overkill and broke the login flow. I pushed back, told it to rip out all the Resend code, and forced it to use Supabase’s native email system instead. You are still the boss. The AI works for you. Never blindly trust the first output without questioning its simplicity.

Organize your digital environment

You have to be rigorous with your workspace. I sometimes help colleagues debug their projects. They share their screen, and it’s an absolute nightmare. They have fifty tabs open and thirty apps running. Their project files are scattered randomly across their Downloads, Desktop, and Documents folders. It’s pure chaos. You get completely lost when you try to debug in that mess. I’m not against multitasking, but you need boundaries. Keep one clean window for your development in Cursor, and one window for your Gemini conversation. That’s it. If you lack discipline, you’ll end up pushing empty folders to GitHub because you clicked the wrong window.

Go through the steps

Let’s dive into the details of how to execute each step from start to finish.

Step 1: Draft the requirements with Gemini (45 min)

The very first step is just talking to Gemini about your idea. You decide how much control you want here. Some people dump a massive export of customer complaints and ask the AI to solve them. Others upload a screenshot of a competitor’s app and say “specify this.” I prefer to treat Gemini like a product manager. I sit down and have a real conversation. I pitch my raw ideas. I ask for feedback. I highly recommend using the microphone for this. Talking out loud gives you total freedom of thought while you speak.

I want to show you the exact prompts I used to build Stanza. It shows how real the process actually is. I started with a very simple question to set the baseline context:

Can you explain how Hacker News works?

Gemini gave me a great breakdown of the platform. It explained the ranking algorithm, the karma system, and the text-heavy minimalist design. It set the perfect foundation for my next prompt.

Then, I pitched my big twist. I just brain-dumped my entire vision in a very conversational way:

I’d like to build a similar website for people who read books and want to share their thoughts. I like the minimalist design, but not like the 2000s. Hacker News feels like it was developed by a geek in his room. I want something minimalist but highly polished. I want a single main feed with no categories. Posts should be simple: just a title and a description. People can read the feed without logging in. They can upvote posts they resonate with without an account. But to publish a post or comment, they need to log in with an email address. I want each post to have a strict life duration of 24 hours before it disappears forever. It should feel like an ephemeral discussion in a book club over a glass of wine. We don’t take our words as immovable. What do you think about this project?

Gemini loved the concept. It called it the pop-up book club. It highlighted the brilliance of the 24-hour urgency. I know Gemini is always enthusiastic and motivating. You should never take its validation for granted. If I needed real validation, I would never ask an LLM. They are just too nice and biased. I didn’t actually need validation anyway. I was already a huge fan of my own idea. This whole process is just about figuring out if the execution makes sense.

But Gemini did help me think about a lot of improvements and ideas. I dismissed almost all of them. However, it pointed out a massive flaw in my logic. It warned me that unlogged voting would lead to massive spam. It suggested using browser fingerprinting to limit votes. That was the only idea I decided to keep from our conversation. This back-and-forth is where the real magic happens.

I agreed with its feedback and pushed for a formal document.

OK, let’s keep it to zero categories to start. I agree with the 1-vote-per-device system. Let’s also limit posts to a single image. It’s just for people who want to snap a photo of a book page instead of typing a quote. Based on all that, can you write detailed specifications so I can hand it to an experienced developer? Focus purely on the core needs and features. Do not write too much fluff. Be very precise about the functioning.

Gemini generated a focused product requirements document. It outlined the core features, the interaction rules, and the strict 24-hour deletion logic.

I needed this document in a clean format to iterate on it.

Can you please put this last response into a Canvas so we can iterate on it? Also please drop the sections about technical stacks and developer deliverables. For the UI/UX notes, add examples of well-known apps for visual inspiration.

Gemini immediately opened a Canvas with the refined text. This interface makes it incredibly easy to edit specific sections without losing the overall formatting. When you get the text in the Canvas, you can highlight specific parts and give direct feedback to Gemini. It’s extremely helpful to get iterations and improve the document right there before you export it.

While we were at it, I needed a good name.

Suggest 10 names for this app.

It gave me some fantastic options based on books and impermanence. The list included names like Vignette, Margin, and Flyleaf. Number nine on the list was Stanza. It hit the nail on the head perfectly.

Finally, I exported the finished Canvas directly into a Google Doc. This Google Doc became the initial source of truth for the project. But this is still just a first version. After some more iterations and discussions, I will ask Gemini to update it to get the v2. That v2 is what I will actually share in Cursor later.

You can read the document here.

View the v1 PRD on Google Docs

We now had a concrete, actionable blueprint ready for the prototyping phase.

Step 2: Generate a prototype in Google AI Studio (30 min)

Now that we have the v1 PRD saved in Google Drive, it’s time to actually build the first visual draft. I don’t write a single line of code for this. I just open Google AI Studio and navigate straight to the Build section.

I keep the instructions almost insultingly simple here. I attached the Google Doc PRD and typed exactly three words.

Build this app.

Here is a secret for vibe-coding. You have to treat the first generation like rolling dice. Don’t just accept the very first output. I actually ran this exact same prompt with the exact same document three separate times. I wanted to see how the AI interpreted the vibe differently each time. Look at the difference below. Both came from the exact same instructions, but one is clearly better. I picked the version in the second image because it gave me an immediate “coup de cœur.”

But having good bones doesn’t mean it’s finished. It still looked a bit like a wireframe. This is where the most powerful workflow loop happens. I started playing ping-pong between Google AI Studio and Gemini. I took a screenshot of the raw AI Studio prototype. I went back to my ongoing Gemini conversation, pasted the image, and asked my AI product manager to tear it apart.

I have a first version. Give feedback about the UI of this modal so that the system can improve it.

The feedback I got back was absolutely incredible. If you aren’t a trained UI/UX designer, this step is pure gold. Gemini immediately noticed that my text inputs had dark grey backgrounds. It told me this created a black hole in the UI that looked like a developer console instead of a book app. It told me to strip away the borders, drop the explicit “Title” labels, and use massive Serif fonts so the typography becomes the interface. It literally told me to transform the modal from a tax form into a blank sheet of paper.

Here is my favorite piece of feedback it gave me:

The “Publish” button looks like a light grey pill. It feels passive. Make the button Solid Black (#000000) with White Text. This creates a strong “ink on paper” contrast that aligns with the Stanza brand.

It also completely nailed the core mechanic of the app. It noticed the “24H LEFT” timer was blending in with the author’s name. It suggested adding a color heartbeat. If a post has less than 4 hours left, the text should turn a muted burnt orange. It wasn’t just fixing CSS: it was improving the product psychology.

At the end of every critique, Gemini conveniently generated a “summary directive for the developer.” It summarized all the visual changes into one dense paragraph. I just copied that directive, flipped back over to Google AI Studio, pasted it into the chat, and hit enter. Google AI Studio applied Gemini’s design feedback to the code. I didn’t touch a single CSS file myself. I was just passing notes between the designer and the developer.

I repeated this screenshot-and-paste loop a few times. You can see the exact visual progression below. Watch how the interface evolves from a clunky pop-up into a distraction-free, full-page literary salon:

I kept iterating until the prototype looked exactly the way I wanted on my screen. I tested the clicks. I checked the layout. And the absolute best part? All of this endless iteration in Google AI Studio is completely free.

Once I was completely satisfied with the visual shell, I clicked the download button in Google AI Studio:

It gave me a neat little zip folder with all the source code. I extracted that code and dropped it into a dedicated project folder on my computer:

The visual foundation was officially done. Now it was time to bring in the heavy machinery to make it actually work.

Step 3: Save the code to GitHub (15 min)

I finally have my prototype code ready to go. I open up Cursor. I use it to open the exact folder I just downloaded from Google AI Studio. This is a big moment for the project. This is where the actual finalization phase begins. The visual shell is completely done. Now we need to connect the plumbing and build the actual engine.

But before I write a single new line of code, I stop. I need to create a baseline save state. I immediately push this initial code to GitHub to create my first checkpoint. I personally use the GitHub Desktop app for this step. I like having a clear, visual interface for my commits. You absolutely don’t have to do it this way. You can use standard terminal commands directly inside Cursor. You can even just ask the Cursor AI agent to handle the commit for you. Just pick whatever method feels the most comfortable.

I hit the publish button in the desktop app. A small modal pops up to confirm the repository name and description. I fill in the details and hit the final blue publish button. Then, I always open my browser and go straight to the GitHub website to double-check. I want to see that my first commit is safely logged in their system. It gives me peace of mind before I start breaking things in the editor.

There is one quick detail to check while you are on the website. Sometimes you click through the setup screens too fast. You might accidentally leave the repository set to private. I always prefer to build these kinds of projects in public. If you made that mistake, don’t worry about it. Just go into the settings tab and scroll down to the danger zone. You can easily switch the repository visibility to public right there.

We now have a solid, backed-up foundation. We are officially ready to start coding.

Step 4: Build the core app with Cursor (45 min)

We are finally back in Cursor. We have our visual prototype, but it doesn’t actually do anything yet. It’s time to build the engine.

I always start by bringing my specifications directly into the codebase. I create a simple folder named docs in the project directory:

Then, I go back to the final Google Doc PRD. Google Docs has a native option to download the file directly as Markdown (.md):

I just download that file and drop it right into the docs folder:

If you discussed improvements and received feedback from Gemini earlier, ask it for a second version of your document so you have the latest specifications. This keeps your absolute source of truth right inside your code environment.

Let me share a quick pro-tip here. Raw markdown files can be really ugly to read in a code editor. If you right-click the file tab in Cursor, you can select “Open Preview:”

It instantly formats the text into a beautiful, readable page. It looks exactly like a clean Confluence document:

Now it’s time for the very first prompt. I open a new chat in Cursor. This is where you absolutely need to understand Cursor’s different modes. If you don’t understand these, you will burn through your paid credits fast. Here is a quick breakdown of how they work and when to use them.

• Agent mode: This is the default. It’s fully autonomous. It writes files, runs terminal commands, and edits code immediately. If you ask, “What’s the weather in Paris?”, it won’t just tell you the temperature. It will try to build a fully functioning weather app in your project folder. Use it for quick, clear tasks where you know exactly what needs to be built.

• Plan mode: This mode forces the AI to think before it acts. It researches your codebase, asks clarifying questions, and writes a step-by-step roadmap for you to approve. If you ask about the weather, it will pause and ask: “Are we building a CLI tool or a web dashboard? Do you have an API key?” This is my absolute favorite. Use it by default for any multi-step feature to prevent Cursor from going rogue.

• Ask mode: This is a strict read-only mode. It reads your code and answers questions, but it cannot write or edit files. If you ask about the weather, it simply replies, “It is 15°C in Paris.” Use it when exploring unfamiliar code or when you just need a simple explanation without risking accidental changes.

• Debug mode: This is a specialized mode for tricky errors. Instead of blindly guessing, it instruments your code with temporary logs, asks you to reproduce the bug, and analyzes the real runtime data. If you ask about the weather, it says, “I can’t get the data. Let me add console logs to your API call so I can see where it fails.” Use it when your app crashes or when Agent mode is stuck in a loop.

I set the model to Claude 4.5 Sonnet because its coding results are incredibly reliable. I select Plan mode and type a very direct prompt:

Finalize this app so that I can release it into production.

Because I used Plan mode, Cursor didn’t just start blindly coding. It paused and asked me a series of multiple-choice questions to define the architecture. It literally gave me a guided quiz to figure out exactly what tools I wanted to use. This is incredibly helpful if you aren’t sure where to start. Here is how I answered its questions to guide my setup:

• Question 1: What backend implementation do you need for production? I selected option A: “Full backend with database, authentication, and email service - real production app”. I didn’t want a fake static demo. I wanted the real deal.

  

• Question 2: What hosting/deployment platform do you prefer? I selected option A: “Vercel”. It’s natively recommended for React apps and is incredibly easy to use.

  

• Question 3: Which database would you like to use? I selected option B: “Supabase (PostgreSQL with auth helpers)”. Supabase is fantastic for handling both data and magic-link logins in one place.

  

• Question 4: What email service do you want to use? Cursor suggested tools like Resend and SendGrid. I explicitly chose option F: “No emails are sent to users, except for the one to log in”. Always restrict the AI when you can to avoid unnecessary complexity (I will explain the specific deployment issue this caused later on).

  

• Question 5: Do you already have API keys for these services? I selected option B: “No, help me set up new accounts”. This tells the AI to generate instructions for me later.

  

Based on my answers, Cursor generated a massive, 16-step execution plan. It created a markdown file with a full architecture overview and a checklist. It’s honestly a bit exhausting to look at, even though I’ve done this multiple times. I quickly reviewed its logic to make sure it understood the assignment.

Once I was happy with the roadmap, I clicked the yellow “Build” button. This is the magical moment. Cursor automatically switches into Agent mode and starts rolling through the checklist. You can literally watch it check off the to-dos one by one as it creates the backend endpoints.

But you can’t just walk away and grab a coffee. You have to supervise it. The Agent will regularly pause and block the process when it edits core files. It shows you a clean visual diff of the code changes. You have to manually hit the “Accept” button to let it continue.

When Cursor finally finished the entire 16-step plan, it dropped a big “Ready to Deploy!” message in the chat.

More importantly, it automatically generated a few new Markdown files in my project, including one called NEXT_STEPS.md.

I opened that file in preview mode. It gave me a beautiful, human-readable summary of the 1,500 lines of code it just wrote. It also gave me exact, step-by-step instructions on what I needed to click inside Supabase to get the database running. These are the exact guides I followed to finish the backend integration.

Step 5: Configure the backend with Supabase (30 min)

We have our code, and we have our exact NEXT_STEPS.md guide generated by Cursor. Now we just need to execute the plan.

The first major task is setting up the database. I head straight over to the Supabase website. They promise you can “Build in a weekend, Scale to millions” right on the homepage. That’s exactly the vibe we are going for here.

I log into my free account and click the big green “New project” button.

A simple setup screen appears.

I name the project “stanza”, select my region, and generate a strong database password. You just hit create and wait a minute or two for the servers to provision. It’s literally that easy to spin up a production database today.

Once the project is active, I need to link it to my code. I navigate to the Project Settings and open the API section. I’m looking for three specific things here: the Project URL, the anon public key, and the service_role key.

I copy these raw values. I jump back into Cursor. I open the .env.local file that Cursor created for me earlier. I paste those Supabase keys directly into the file. This is the critical bridge. This file tells my local code exactly how to talk to my live database.

Let me stop here and share a crucial security rule. You must never push these secret keys to GitHub. If you expose your database keys publicly, malicious bots will scrape them and ruin your app. Cursor already handled this for me technically. It automatically added .env.local to a hidden file called .gitignore. That file tells GitHub to completely ignore the secret keys when you upload your code.

Now we need to actually build the tables to hold our data. Remember that 16-step plan Cursor ran through earlier? One of those steps was generating a massive schema.sql file. This file contains all the database rules and structures we need. I open schema.sql in Cursor and copy every single line of code.

I go back to my Supabase dashboard and open the SQL Editor. I paste the massive block of code into the blank query window and hit “Run”. For this specific project, it worked perfectly on the very first try. I immediately got a clean “Success. No rows returned” message.

Don’t panic if you get a red error message here. It happens sometimes with AI-generated SQL. If it fails, you don’t need to learn database administration to fix it. Just copy the exact error message from Supabase, paste it back into your Cursor chat, and tell the AI to generate a new schema. It will fix its own mistakes.

Because it worked perfectly, I wanted to see the result visually. I clicked over to the Schema Visualizer in Supabase. Supabase successfully created and linked five distinct tables: users, posts, comments, votes, and magic_links. The entire backend architecture is fully alive.

There was just one final tiny step in the guide. Since Stanza allows users to upload a single photo per post, I needed a place to store those image files. I went to the Storage tab in Supabase and clicked “New bucket”.

A modal popped up to configure it.

I named the bucket post-images exactly as the guide instructed. More importantly, I toggled the “Public bucket” setting to ON. If you forget this toggle, your app will upload images perfectly fine, but nobody will actually be able to see them on the feed. Once created, you get a clean, empty folder view ready for uploads.

But there’s a little trap here that catches a lot of beginners. Even though the bucket is public, Supabase still requires you to explicitly define security policies. I went into the bucket policies and added a new one called “Public read access”. I checked the box for the “SELECT” operation and set the policy definition simply to true. This tells the database that literally anyone is allowed to view the files inside.

Supabase shows you a quick summary screen to review the exact SQL statement it’s about to run for this policy. I clicked “Save policy” and the storage setup was officially complete.

The database, the authentication, and the file storage were fully wired up.

I know all of this database terminology might sound incredibly complicated if you have never set up a backend before. But I promise you, I didn’t invent a single thing here. I just followed the exact step-by-step recipe that Cursor wrote for me in that NEXT_STEPS.md file. You literally just click where Cursor tells you to click.

Step 6: Test the application locally (30 min)

Normally, once the .env.local file is filled with Supabase keys, I test everything locally. I always prefer to hunt down bugs on my own machine before deploying anything live. According to the trusty NEXT_STEPS.md guide, the next move is simply to start the development server. So I opened the terminal in Cursor, ran npm install, and started it up.

I want to share a really cool trick here. You don’t actually need to open Chrome to test your app. Cursor has a built-in browser tab. Just prompt @browser go to localhost:3000 to launch it directly inside the editor.

The Stanza homepage loaded perfectly. It’s rewarding to see your code come to life in the exact same window. But then I tried to actually use it. I clicked log in, entered my email, hit continue, and immediately got slapped with a red “Network error”.

I didn’t panic. I used one of Cursor’s best debugging features instead. When you use the internal browser, you can click the three little dots in the top right corner. You can instantly take a screenshot of the app and attach it directly to your prompt.

Even better, if you are in Agent mode, Cursor can actually take control. It can click the buttons itself, read the browser console, and pull the exact error logs automatically. It’s a way to save time.

I fed the error screenshot to the prompt. Cursor told me the authentication flow was failing because it was trying to connect to both Supabase and that completely unnecessary Resend email service.

I iterated. I insisted. I asked for fixes. I spent way too much time trying to resolve this network error locally. Nothing worked. Usually, I spend a solid hour here polishing the app and clicking every button before putting it on the internet.

But you know what? Sometimes you just have to keep moving forward. It wasn’t that big of a deal. I decided to stop fighting my local environment. I did a quick file cleanup to move all the messy markdown files into a docs/guides folder.

Then, I pushed the whole project to GitHub. I decided to deploy it to Vercel and fix the bugs live in production instead.

Step 7: Deploy the website on Vercel and iterate (1h 45m)

I opened GitHub Desktop and pushed my latest commits to my main branch.

It feels great to see those files safely backed up online.

Now it was time to make the app public. I opened Vercel in my browser.

Cursor’s NEXT_STEPS.md told me exactly what to do here. I clicked “Add New Project” and imported my Stanza repository directly from GitHub. Vercel is incredibly helpful. It automatically detected that my app was built with Vite and pre-filled all the correct build settings. I literally just clicked the “Deploy” button.

A few seconds later, Vercel showed me a success screen.

But don’t celebrate just yet. There is a massive trap here that catches almost every single beginner. If you open your live URL right now, you’ll probably just stare at a blank white screen.

Cursor actually warned me about this exact issue in the deployment guide. Your local code knows how to talk to Supabase because of your secret .env.local file. But remember, we explicitly told GitHub to ignore that file for security reasons. This means Vercel doesn’t have your database keys. You have to manually add them.

I navigated to the Project Settings in Vercel and opened the “Environment Variables” tab. It was completely empty.

I copy-pasted my Supabase URL and keys directly into the dashboard. Always remember to copy your environment variables to your hosting provider.

Because I added those keys after the initial deployment, Vercel didn’t apply them yet. I had to trigger a quick redeploy.

This tells Vercel to rebuild the app from scratch using the new database credentials. I watched the build run one more time. It only took about 2 minutes.

There was just one final piece of plumbing to connect. The NEXT_STEPS.md guide reminded me to configure my auth redirects. Supabase needs to know where to send users after they click a magic login link in their email. I copied my shiny new Vercel URL, went back into the Supabase Authentication settings, and pasted it into the Redirect URLs field.

I opened my live link in a new tab. It loaded instantly. The blank white screen was gone. The beautiful, minimalist interface was officially live on the internet!

The engine was finally running in production.

Debug and polish the project

Telling the story this way makes it sound like a perfect, straight line. It absolutely wasn’t. You inevitably hit a wall where the happy path ends. We are now entering the messy middle. This is the phase dedicated entirely to testing, debugging, and pulling your hair out.

Troubleshoot the live product

Right off the bat, my very first Vercel deployment actually failed. The build crashed, and Vercel spit out a red error log about a missing property:

I didn’t panic. I just copied the exact error text, pasted it into Cursor, and let the AI push a quick fix. The deployment succeeded on the second try.

But the real nightmare started when I tried to log in on the live site. I entered my email, clicked continue, and got hit with a brutal “Network error” modal.

Let me tell you exactly what happened here. Back when I was generating the initial architecture plan, I explicitly told Cursor to skip adding any external email services. I wanted to keep things simple. But the AI got a little overzealous. It unilaterally decided to include a third-party tool called Resend in its 16-step to-do list anyway. I wasn’t vigilant enough when I approved the plan. I saw Resend on the list, thought it might be fun to test a new tool, and just let it slide.

That was a massive mistake. The integration was overly complex and completely broke the authentication flow. I wasted way too much time trying to fix it. Eventually, I had to put my foot down. I opened Cursor and explicitly commanded it to rip out every single line of code related to Resend. I forced it to clean up its mess and revert to the native Supabase magic link system. Always trust your gut when an AI solution feels too complicated.

Even after purging Resend, the live login still failed. I needed to see what was actually happening behind the scenes. I went into Vercel and clicked on the “Logs” tab. Sure enough, there was a massive red backend error. The server couldn’t find my Supabase module.

I took a screenshot of the Vercel log and pasted it directly into a new Cursor chat. I made sure to switch back to Plan mode. I didn’t want the AI to guess. I wanted it to diagnose the root cause.

Cursor nailed it instantly. It explained that Vercel serverless functions require explicit file extensions for certain imports. It wrote a clear plan to update the API routes. I clicked “Build” and let it rewrite the broken files.

During this debugging session, Cursor also caught a subtle environment variable bug. Because I was using Vite, my frontend needed the database keys to be prefixed with VITE_ to actually read them. Cursor automatically updated my .env.local files to fix this mapping.

I pushed the code to GitHub, Vercel rebuilt the site automatically, and the network error finally disappeared. The engine was flawlessly humming.

Improve the final experience

With the critical bugs crushed, it was time to polish the experience. Building an app is exactly like building a house. Pouring the foundation and putting up the walls is incredibly fast and highly visible. You know immediately if it worked. But painting the trim, fixing the lighting, and sanding the floors? The tiny details take the majority of the time.

I went back to my very first Gemini conversation. I started feeding it screenshots of the live app. I asked for feedback on the spacing, the typography, and the button contrasts. I took Gemini’s suggestions, fed them to Cursor, and iterated on the UI until it felt like a premium product.

The best part of this setup is the automatic deployment. Every time I push new code to GitHub, Vercel automatically updates the live website. For each tiny adjustment, I just push the changes using GitHub Desktop (or ask the Cursor agent to do it for you). I only have to wait one or two minutes to see the final result in production.

I also wanted every touchpoint to feel branded. The default Supabase magic link email is painfully generic. It looks like a database auto-reply.

I opened Gemini and asked it to act as a frontend developer. I told it to generate a custom HTML email template that matched Stanza’s minimalist, black-and-white, serif aesthetic. It spat out a beautifully formatted block of code.

I just copied that raw HTML, went back into the Supabase Email settings, and pasted it directly into the “Body” field. Now, when a user logs in, they get a sleek, highly polished email inviting them to “enter the room”.

For the absolute final step, I used Gemini to generate some mock data. I asked it for fake book reviews, controversial thoughts, and insightful quotes. I manually populated the live feed with these posts. This gave me a real sense of how the layout handled actual paragraphs and upvote counts. I tweaked the line heights one last time based on this realistic data.

And just like that, at the five-hour mark, Stanza was completely finished.

Build your own idea now!

And there you have it. That’s the entire fever dream from start to finish. Five hours. About €60 in credits. A few frustrating bugs along the way, but we successfully shipped a live, working product.

I really hope this walkthrough proved a point. There has literally never been a better time to build. The barrier to entry for creating software is completely gone. You don’t need a massive budget. You don’t need a team of developers. You don’t even need to know how to write a database schema from scratch. You just need a bit of digital discipline, a lot of stubbornness, and a solid vision.

We all have that one app idea we’ve been sitting on for years. It’s the one you always talk about at the office but never actually start. Maybe it’s a weird niche marketplace. Maybe it’s a tool to fix a highly specific annoyance in your daily workflow. Whatever it is, you have absolutely no excuses left.

Your homework is incredibly simple. I don’t want you to worry about code, databases, or Vercel deployments today. Just open a new chat window with Gemini. Turn on your microphone. Pitch your raw idea out loud, just like you would to a colleague over coffee. Let the AI ask you questions. Once you have that blueprint, the rest of the process is just following a recipe.

The tools are ready. The cost is negligible. Now, close this article, open a chat window, and go build something awesome! I can’t wait to see what you ship.

Let’s take a concrete example to visualize this. We will look at Excalidraw, a fantastic open-source virtual whiteboard. You probably know it already. It works just like Miro or FigJam.

When you open their GitHub repository, the first thing you see is a long list of files. This is the actual code.

Then, if you scroll down a bit, you finally reach that famous README file.

It gives you some context, but it feels static. It’s just text on a page, and you can’t interact with it.

This frustration is common among product people. We have a curiosity that static text cannot satisfy. We want to understand the product’s logic. We want to dig into specific features. We essentially want to have a conversation with the code. There is definitely a pro way to do this. You can download the code, open an IDE like VS Code or Cursor, and use advanced AI agents. I plan to explore those tools in a future article. But let’s be honest. That process is heavy and time-consuming for a simple question. It feels like bringing a bazooka to a knife fight.

Today, I want to show you a lighter, smarter way. You can interview a codebase without ever leaving your browser. We will cover everything from understanding the product to generating documentation. By the end of this article, even if you know nothing about development, you will be able to question code like a pro. This isn’t just about curiosity; it’s about autonomy. You can answer your own questions about business logic and edge cases instantly, without interrupting your developers’ flow. You become a partner who brings informed questions to the table, not just requirements. Let’s dive in!

Import a GitHub repo into a Gemini conversation

Look, I am going to show you something incredible. I honestly don’t understand why people don’t talk about this feature more often. It saves me hours of headache every week. As we discussed, the heavy way involves downloading code and setting up complex tools. But there is a much simpler, more economic way that stays right in your browser. You don’t need to be a developer to do this. You just need a link.

Here is the exact process.

1. Open your LLM tool. I use Gemini for this example, but ChatGPT and Claude have similar features.

2. Look for the “Add file” icon in the chat bar. Select the option to “Import code.”

   

3. Then, simply paste the URL of the repository. In our case, we paste the link to Excalidraw: https://github.com/excalidraw/excalidraw

   

4. Click “Import.”

That is it. You don’t need to clone files or configure a local environment. You simply type your prompt, click submit, and you are ready to go.

Once you hit submit, the magic happens. The AI processes the link. It indexes the codebase and loads it into its context window. This means the LLM now reads the project files as if they were part of the conversation history. You are now ready to chat with the code. It’s fast, efficient, and requires zero technical setup.

Now that the brain is loaded, we can start asking the real questions.

See the method in action

To prove this works, let’s use Excalidraw. We product people usually know this tool. It’s an open-source whiteboard similar to Miro or FigJam. That is why I picked it. But for this exercise, imagine you have never seen it before. You just landed on the repo, and you are trying to figure out what’s going on. Here are the 5 questions that will change how you look at code.

Summarize the product purpose

Usually, when you discover a new tool, you have to decipher technical jargon to understand the value proposition. You read about dependencies and scripts, but you miss the big picture. But now, you can just ask the code to pitch itself to you. I asked Gemini to summarize the purpose of this repository in one non-technical sentence. The result was immediate. It told me exactly what the tool does and who it is for.

Prompt:

Summarize the purpose of this repository in one non-technical sentence.

Result:

This repository contains the source code for Excalidraw, a virtual whiteboard application that allows users to create diagrams and sketches with a hand-drawn aesthetic.

It’s incredible, right? You don’t need to read the code or guess. The context window handles it. You can keep the conversation going without ever re-pasting the link. You just ask, and the answer comes.

Explain how features work

Now let’s get technical. Maybe you have always wondered how a digital whiteboard actually works. Usually, to find this out, you would need to schedule a meeting with a developer. You would have to hunt through thousands of lines of code. Instead, just ask for the logic. I asked Gemini to trace exactly what happens technically when a user draws a line.

Prompt:

Trace the logic: What happens technically when a user draws a line?

Result:

The technical lifecycle of drawing a line in Excalidraw involves a coordinated flow between the event listeners, the main application state, and the rendering engine.

[I’m cutting the rest because it’s too long…]

You can even ask about specific business rules. You can ask about hardcoded limits or encryption logic. You get precise answers instantly, without bothering your engineering team. It turns a complex black box into a clear explanation.

Generate product doc

We often have to write documentation, whether it’s for users, testers, or stakeholders. This tool turns the codebase into a content generator. I asked Gemini to generate a full user manual for Excalidraw. I even used the Canvas tool to export it directly to Google Docs.

Prompt:

Generate a comprehensive user manual for the entire product based on the codebase capabilities.

Result:

Access the Google Doc

I generated a user manual, but I could have asked for release notes. I could have asked for a testing plan. I could have even asked for a marketing email to announce a new feature. You are literally turning raw code into usable doc assets.

Run the app locally

This is my personal favorite. The README.md often explains how to install the app, but it assumes you are a developer. It skips steps. Personally, I often get stuck. With this method, you can ask for a dumbed-down guide. I asked for a step-by-step guide to run this app locally on my Mac, assuming I am a beginner.

Prompt:

I am a non-technical person. Please generate a step-by-step guide to run this app locally on my specific machine Mac.

Result:

I’ll generate a beginner-friendly guide to running Excalidraw on your Mac. Since you’re non-technical, we’ll avoid complex developer tools where possible and stick to the easiest path.

Here is the step-by-step guide:

[The specific steps to the right of the conversation, on the Canvas…]

I followed the steps like a cooking recipe and it worked. I deployed the app locally and tested it in minutes.

If the terminal throws a red error message, don’t panic. Copy the error, paste it back into Gemini, and ask: “I got this error. What is the specific command to fix it?”

Suggest code optimizations

For those who want to go further, you can actually use this to help your team. You can identify bugs or suggest optimizations. I often use Gemini for this because its suggestions are accessible. I asked it to analyze the code for fragile logic and suggest optimizations.

Prompt:

Debug the current code: Identify 3 areas where bugs are likely to occur.

Result:

Based on the file structure of the Excalidraw repository, here are 3 specific areas where bugs are likely to occur due to the complexity of the logic involved:

[Cut…]

I am genuinely impressed by the results.

Pro tip: I use Gemini for optimizations because it explains things well. However, if I hit a really complex bug where I am completely stuck, I prefer Claude. I attach the specific file, and Claude is often sharper at spotting the exact logic error to fix it.

Practice the method yourself

To be honest, I didn’t have much time to write this week. That’s why I am moving fast. But I want to leave you with something concrete to play with. Here is my proposal. I have selected 5 open-source repositories for you to test. Excalidraw is just one of them. You can pick any of these, paste the URL into your favorite LLM tool, and start the interview.

Select a repository to test

Here are the repositories I suggest, but you are free to pick another one that you like.

• Excalidraw: This is the virtual whiteboard for sketching diagrams we just looked at. It’s a tool, not a platform. So the complexity isn’t in the database; it’s in the UI and state. It’s great for asking user flow questions. Try asking: “Does this work offline?” or “How is the data saved if there is no login?”

• Cal.com: This is an open-source alternative to Calendly. It lets people book meetings with you. It has a crystal clear happy path: User A sends a link, User B books a time, and an email is sent. It’s perfect for asking about business logic. Try asking: “What happens to the booking if the Google Calendar API goes down?” or “How do we handle timezones?”

• Forem: This is the software that powers dev.to. It’s a platform for building communities. It’s huge and complex. It has roles like admin and moderator. It has permissions and rewards. This is the best repo to practice asking business logic and configuration questions. Try asking: “Can I turn off the shop feature easily?” or “What are the different user roles?”

• Strapi: This is a headless CMS to manage content. It sends data to your website or app via API. It has two distinct users: the developer who sets it up, and the content editor who writes articles. It’s perfect for practicing persona questions. Try asking: “Who is this feature for? The dev or the writer?”

• NocoDB: This is an open-source alternative to Airtable. It turns any database into a smart spreadsheet. It connects to external things. It’s great for asking prerequisite and risk questions. Try asking: “What databases do you support?” or “If NocoDB crashes, do I lose my actual data in MySQL?”

Ask these specific questions

Now that you have the target, you need the questions. I have prepared a codebase interview guide for you. It acts as a cheat sheet.

I organized it into two main scenarios:

• Discover a new codebase: You have never seen the code before and want to understand how it works.

• Collaborate on an existing project: You work on the team and need to debug issues or write documentation.

But remember, these are just suggestions for inspiration. If you have your own specific questions, ask them! If you lack inspiration, feel free to use mine.

Scenario 1: Discover a new codebase

JTBD 1: Understand the product basics

Summarize the purpose of this repository in one non-technical sentence.

Who is the primary user persona for this specific codebase?

Does this project run standalone, or does it require a separate backend/database?

What are the primary input and output formats?

Is this project a monolith (everything in one place) or a monorepo (multiple packages)?

JTBD 2: Map the core architecture

What is the complete data structure of the main domain entity or core object?

Where is the entry point for the main application state or data store?

How does the application detect and handle core user interaction?

Trace the logic: What happens technically during the primary happy path action?

How is the visual styling or theming handled?

JTBD 3: Identify business rules

What is the logic for authentication and authorization (who can do what)?

How does the main export or data output function work?

Are there any hardcoded limits or constants (e.g., max size, max count, timeout)?

How is language or internationalization (i18n) handled?

What logic handles data persistence (saving)?

JTBD 4: Run the application locally

I am a non-technical person. Please generate a step-by-step guide to run this app locally.

List the scripts found in package.json (or Makefile) and explain what they do.

Does the project use a configuration file (like .env), and what are the required keys?

Is there a container configuration (Docker/K8s)?

What are the key external dependencies or libraries?

Where are the standard test fixtures or mock data stored?

Scenario 2: Collaborate on an existing project

JTBD 5: Debug and improve the code

If we wanted to add a [new feature], which files would we need to modify?

How does the application handle failure states (e.g., offline, API down, database error)?

Where is the input validation or sanitization logic?

Are there any feature flags or config variables enabled in the code?

Check the [critical performance path]. Is it optimized?

Based on the code structure, suggest 3 specific code additions or improvements.

Debug the current code: Identify 3 areas where bugs are likely to occur.

Analyze the code for potential fragile logic (like unhandled errors) and suggest specific test cases to trigger them.

JTBD 6: Generate documentation and content

Generate a comprehensive user manual for the entire product based on the codebase capabilities.

Write a draft of the release notes summarizing the top 3 capabilities found in the codebase.

Compose a marketing newsletter post announcing the [specific feature] to our users.

What are all the accepted user inputs/shortcuts defined in the code?

List all the supported integration or export formats.

How does the [specific protocol/API] structure look?

Does the code contain any accessibility (A11y) attributes?

What specific security libraries or encryption methods are used?

Just imagine for a second. Instead of pinging a developer on Slack and waiting hours for a reply, you can now get an instant response directly from the LLM.

Manage restrictions and access

Know the limits

It’s important to remain realistic. This tool is powerful, but it’s not magic. There are specific things it simply cannot do.

First, Gemini cannot see the past. It analyzes the files as they exist right now, like a snapshot. It does not have access to the Git history or metadata. You cannot ask “Who wrote this line?” or “How many pull requests were merged last week?” For questions about people, contributors, or timelines, you should stick to the standard GitHub interface.

You also need to know that the conversation is static. The code you import does not sync in real-time. If your engineering team pushes a major update five minutes after you start your chat, Gemini will not know about it. It’s frozen in the moment you imported it. If the code changes significantly, you must simply start a new conversation.

There are also technical limits on the size of the project. You cannot upload a massive corporate monolith. Currently, Gemini limits you to one repository per chat. The project must have fewer than 5,000 files and be under 100 MB in size. This is plenty for most modern microservices or tools like Excalidraw, but it will hit a wall with huge legacy codebases.

Finally, be prepared for a change in pace. Responses will be slower. Because the system has to scan thousands of code files for every query, it takes more time than a normal chat, especially with the “Pro” model. This heavy lifting also comes at a cost. You will burn through your daily usage limits much faster. I actually hit my daily cap just by testing this today. Fortunately, the reset only took an hour, but keep in mind that interviewing a codebase consumes significantly more tokens than a standard conversation. It’s a power user feature, and it costs power user credits.

Analyze private repos

You might be wondering about your own work. “Does this only work for public open-source projects?” The answer is no, it works for private repositories too. You do not need to make your code public. You simply need to connect the AI tool to your GitHub account in the settings. Here is the step-by-step guide (with a crucial tip):

1. Go to Settings > “Connected Apps.”

   

2. Find GitHub and toggle it to “On”. Click Connect.

   

3. Important step: You need to click on “Learn more” and then click the “Connect” button again to force the authorization window.

   

4. Continue the steps until you see your specific GitHub ID displayed on the Gemini screen.

   

Once connected, you can interview your private code just as easily as we did with Excalidraw.

Important note: If you are at a large company, check your internal AI policy. For personal projects or open source, this is fair game.

Explore alternatives

Gemini is my go-to because it’s easy, but it’s definitely not the only player in town. If you want to explore further, there are other specialized tools worth testing.

Let’s start with the one you probably already have: GitHub Copilot. It’s integrated directly into the interface, but it’s surprisingly hard to find. You have to click the tiny Copilot icon in the top navigation bar while browsing a repository.

Once open, you can ask the exact same question: “Summarize the purpose of this repository in one non-technical sentence.” It works well, though the quality of the answers often depends on whether you have a Pro plan with access to advanced models.

Next, there is Google CodeWiki. This feels like a NotebookLM for code. It transforms a repository into a structured documentation site with diagrams and a chat interface. I tested it with Excalidraw, and the experience is unique. It feels like the answers come from a pre-structured knowledge base rather than just raw code files. The coolest part? It displays videos for some featured repositories. However, there is a catch. The repository must be pre-indexed by their system. You cannot just throw your private personal project at it yet (at least for now).

Finally, you should check out DeepWiki. This tool feels much more grounded in the actual code. It offers different modes like “Fast,” “Deep Research” or “Codemap.” When I asked it to summarize the repo, I really liked the interface. The best part is that every answer links directly to the specific code files. You can see the source material in the right-hand panel, which gives you a lot of confidence in the answer.

This space is moving fast. My research turned up plenty of other tools like TalkToGitHub, Greptile, Unblocked, or specialized IDE agents. But the tool doesn’t matter as much as the mindset. Whether you use Gemini, Copilot, or DeepWiki, the goal is the same. Stop staring at the code. Start talking to it.

Interview a repo today

So, here is the truth. You don’t need to learn React or Python to understand how your product works. You just need to know how to ask the right questions. LLMs bridge the gap between product and engineering like never before. It gives you the confidence to navigate technical discussions without feeling lost.

Now, it’s your turn. Don’t just bookmark this article for later. Open a new tab right now.

1. Pick one of the 5 repositories I shared above.

2. Paste the URL into Gemini (or your favorite LLM).

3. Ask 3 questions from the interview guide.

4. Bonus: Try to install it locally using the cooking recipe method.

I’m really curious to see what you find. Did you manage to run the app? Did you find a surprising business rule? Share your results or your best prompts in the comments below. If you get stuck, just ask, I’ll be there to help.

And yes, things are getting a little meta here. I used the exact method described in this article to generate the infographic that explains the method. It’s a bit of an Inception moment.

Want to see how this simple workflow turns a rambling voice note into a vision from the future, a cinematic storyboard, or a full customer journey map? Let’s dive in!

Meet Nano Banana Pro

I have a confession to make. I have a new daily obsession, and it honestly lights up my entire day. I take dense, complex text and convert it into beautiful illustrations using the Nano Banana Pro model. It’s a total thrill. My addiction started innocently enough, but now I can’t stop. I take a heavy concept or a messy idea. I feed it to the machine. Then I watch it turn into art. It changes how I work, and it makes the daily grind much more fun.

My fascination actually started years ago. I remember my early days as a product manager. I watched graphic facilitators in workshops. They fascinated me. They started with a blank page. They listened to our messy discussions. Then, they finished with something extremely beautiful. We would hang these posters in the office. The team looked at them with pride. It represented weeks of collective intelligence. It was a tangible vision that we could touch and see.

Just look at this result from The Big Picture Graphic Facilitation below. Isn't it beautiful?

These facilitators are usually generous people. They try to be good teachers. They always say the same thing: “Anyone can draw.” They claim all drawings have value. They even use icebreakers to prove it. Honestly? I never bought it. I struggled with that concept. My sketches help me understand a concept. They help me write documentation. But I would never hang my art on the office wall. I definitely wouldn’t want the whole company to see my stick figures.

But recently, everything changed. Thanks to Nano Banana Pro, I can actually manage. Look at what I did recently:

And I didn’t stop there. I actually went a little overboard. I generated more than 50 similar infographics. I organized all of them into a massive FigJam board:

Not bad, right? I had to explain product management concepts to a class of data science students. I didn’t want to use boring slides. I didn’t want to put them to sleep. So, I decided to make infographics instead. I admit it isn’t perfect. I would love to do this live in front of the students. I would love to capture their feedback in real-time like a true facilitator. It doesn’t replace that magic of collective intelligence building up on a whiteboard. But at least the result is visual. It helps people learn more efficiently.

I know it’s in French. I could have translated it into English for this article. But as you might have guessed, I have a slight problem: I’m addicted to creating these visuals. I hit the daily generation limits almost every single day. I often find myself waiting impatiently until 8 PM for the quota to reset. This happens even with the Gemini Pro subscription. Theoretically, the plan offers up to 100 images per day. But there is a little warning in the description: “image generation and editing is in high demand. Limits may change.” And I reach those limits very quickly.

Keep the prompt simple

And now, I want to show you exactly how I generated those specific infographics. Here is the prompt I used (translated for you):

I’m preparing a product management training for data scientists. For the presentation, instead of slides, I want you to generate graphic facilitation visuals. I will provide content section by section. I want you to generate a graphic facilitation image to cover all topics in that section.

Here is the content for this section:

---

[Here I activate the microphone and dictate all my notes...]

There is this very interesting article from that gives a specific method for writing prompts for Nano Banana Pro. It insists on a strict structure. You must first indicate the work surface. Then you define the layout. Then you list the specific components. Finally, you set the constraints.

This is excellent advice if you want a very specific, professional result like a comic strip. But honestly? I’m not that strict. My prompts are pretty trash. They are often messy and full of typos because I dictate them. I prefer to keep my prompts simple and open. I want the system to be creative. I don’t want to constrain it too much. I let the AI surprise me.

Let me share the details of my process with you.

Follow this simple process

My actual process is much messier:

1. I start by writing a short sentence about the visual result I want, just like I would ask a colleague.

2. Then, I type three dashes “---” to create a clear separation.

3. After that, I activate the microphone. This is where the magic happens. I launch into a monologue for 10 to 15 minutes. I tell the whole story. I explain the context, the nuances, and the details I want to capture. I might ramble a bit, but that density of information helps the model understand the vibe.

4. Once I run out of breath, I hit send.

Alternative for step 3: Sometimes, instead of activating the microphone, I simply copy-paste text directly from my documents. I don't dump the whole file, though. I am very precise: I select only the specific paragraphs that I want to see converted into the illustration.

And here is my secret for dealing with AI randomness. I open three separate tabs in my browser. I paste the exact same prompt into all three tabs and hit enter simultaneously. Since these systems are probabilistic, the results are rarely identical. Usually, one image is weird, one is okay, but one is genuinely cool. I pick the winner and close the other two tabs.

To prove this, let’s look at the results for that Inception infographic I shared at the very beginning of this article. I used the exact same prompt in three different tabs. Here is what I got:

You can see the difference. One was a bit chaotic (left), one was just meh (right), but the third one (middle) nailed the style. I didn’t change a single word of the prompt. I just rolled the dice three times.

I’ve found that iterating on a bad image is a waste of time. If it starts bad, it usually stays bad. It’s much more efficient to pick the best seed and continue the conversation in that specific tab. This ensures the style remains consistent for the next set of images.

So, once I have that cool result, I tell the system, “Okay, this is great! Can you do the same thing for the next part?” I put the three dashes “---” again, dictate the next piece of content, and keep the visual style consistent throughout the entire conversation.

Visualize your daily work

Create presentation slides

My addiction didn’t stop at colorful workshop posters. I realized I could apply this same lazy method to my daily work. I started creating presentation slides:

I personally love a high-contrast style. I ask for simple, black-and-white, graphic visuals. It looks sharp and professional on a big screen. I use the exact same three-tab method here. I dictate the concept of the slide, and I let the model handle the composition. Here is the prompt that generated it:

Create a simple infographic to present this text.

Style: Minimalist, simple, black and white. Make it look hand-drawn by a human to explain the concept to a non-tech audience. Put it in a rectangle with black borders. Be artistic and professional, not too cartoonish. Not too much text, just the essentials.

At the bottom, include: “Adam Faik - theaithinker.com”

It will be used in a Google Slide.

---

[Here I activate the microphone and dictate my notes...]

Illustrate your documentation

I also started using this for my written documentation and articles. You might have seen this one in my previous article about Gems:

And here is the prompt that generated it:

Create a simple infographic to explain this concept.

Style: Minimalist, simple, black and white, clear. Hand-drawn style, as if made by a human, to explain the concept to a non-technical audience.

It will be included in an article.

---

[Here I copy and paste the part of the article that I want to illustrate…]

Upgrade your napkin sketches

But the absolute coolest trick is the napkin sketch upgrade. Sometimes I just need to think with my hands. I draw a terrible sketch in my notebook. It’s messy, imperfect, and frankly ugly. Then, I take a photo of it. I upload it to the chat and simply ask the model to make this clean and professional. The result is great. It keeps the structure of my thought but applies a professional design layer on top.

Here is the raw input. As you can see, I am definitely not winning any art awards here:

And here is the output. It retained every bit of the structural logic but stripped away the mess:

I want to prove that this wasn’t the result of twenty iterations. Here is the actual chat interface showing it happened in a single turn:

And if you want to try this yourself, here is the prompt I used to get that result:

Create a simple infographic to explain the concept in the attached image.

Style: Minimalist, simple, black and white, clear. Use a hand-drawn style, as if made by a human, to explain the concept to a non-technical audience.

Add icons that make sense for each component. Clean up the layout with a perfect white background. Ensure the diagram is perfectly horizontal and centered.

It will be included in an article.

Explore a product case study

One last thing I did recently really sparked this whole experiment. I had to present a product strategy, and instead of a boring doc, I wrote it as a newspaper article from the future. It aligned stakeholders on the target vision. Since it’s confidential, I can’t share it here. But it made me think: How about using Nano Banana Pro for all the other visual artifacts product managers and designers need to do for their work?

That’s when I asked Gemini to list every possible visual artifact a product manager might need. The list was absolutely massive. I honestly had forgotten half of the things we are supposed to visualize. Here is the prompt I used to uncover that list (feel free to prompt it):

Product managers and designers often need to create visual artifacts: storyboards to explain flow, diagrams for workshops, prototypes, sketches, or even slides for training and communication.

Can you please list all the graphical assets that product managers and designers might need to create?

Group them by themes.

Be creative. For example, include things like a newspaper from the future to explain a product vision in a realistic way.

I wanted to test them all, but I ran into those pesky daily limits again. So, specifically for this article, I decided to narrow it down to one case study. I needed a product that everyone knows and a feature that is instantly understandable, so we don’t get bogged down in explaining the business context. Let’s pretend we are product managers at Netflix. We are working on a new feature called: random shuffle.

Imagine a user persona we all know very well. Let’s call him tired Tom. He has a few sitcoms he loves (Friends, The Office, How I Met). He has seen them a dozen times. He comes home from work, exhausted. He doesn’t want to decide. He doesn’t want to scroll. He just wants to click one button and have an episode start by magic.

Experiment with NotebookLM

First, I tried a quick and fun experiment. I asked Gemini to write a PRD for this feature. I exported it to Google Docs and imported it into NotebookLM. Then, I asked NotebookLM to generate the infographics directly.

Pro-tip: Just before generating, I clicked the little pencil icon to give specific instructions:

The results were surprisingly decent. For each example below, I have included the short custom prompt I added to customize the infographic. Here are some cool examples:

Step-by-step visual guide for onboarding new users.

The newspaper from the future: A realistic front-page layout dated 3-5 years in the future, featuring headlines about the product’s massive success. Great for setting a bold vision.

Business model canvas: A visual chart with elements describing a product’s value proposition, infrastructure, customers, and finances.

The north star slide: A single, high-impact graphic that simplifies the complex strategy into one memorable image or metric visualization.

Empathy maps: Visual quadrants (Says, Thinks, Does, Feels) often filled with sticky notes or sketches of user reactions.

Customer journey maps: A timeline visualization showing the user’s emotional highs and lows, touchpoints, and friction areas across the experience.

Mood boards: Collages of textures, colors, interface examples, and photography to define the emotional feel of the product.

Crazy 8s and concept sketches: Rapid, rough hand-drawn UI concepts folded into eight sections of a paper.

Storyboards: Comic-strip style sketches illustrating a user’s specific problem (current state) or how they use the new solution (future state).

Mind Maps: Branching diagrams to organize thoughts, feature sets, or information architecture.

Mockups (Hi-Fi): Pixel-perfect static representations of the final design, including color, typography, and imagery.

Honestly, it’s amazing all the things you can get from just one single PRD. I generated a ton of other visuals, and the creativity of the designs is genuinely interesting. Sometimes it follows the Netflix visual identity, and other times it goes in a completely different direction. But you can clearly see the power here at least for finding new inspiration. If you want to explore all the results yourself:

Access the NotebookLM

However, NotebookLM has certain limitations:

1. Once you get a style you love, it’s hard to tell NotebookLM to do the exact same style again for the next image. You might need to download the image and re-upload it as a source to guide it.

2. NotebookLM is very creative. I would use it for vision work, things that are long-term, flexible, or inspiring. But I would not use it if I need something extremely precise or truthful. NotebookLM has a tendency to extrapolate.

This brings me to an important point: You really need to master your subject matter to use NotebookLM studio effectively and share the results. You have to review the output with extreme care. Otherwise, you risk being fooled by a result that looks convincing but is factually wrong.

I didn’t push this specific experiment to its absolute limit, but I’m sure there is a way to get incredible results with more detailed instructions. You could, for instance, upload NN/g guides as sources to teach the model best practices, or add more project documentation to provide richer context. The potential to have fun here is huge. But for now, let’s get back to Gemini, mostly because I personally love those little black-and-white, hand-made graphic facilitation sketches.

Visualize the product vision

Remember that newspaper from the future strategy I mentioned earlier? Let’s apply that exact technique here for this Netflix feature. Think of this as the Amazon press release method, but visual. It aligns stakeholders on the ultimate victory state before writing a single line of code.

I didn’t just ask for an image out of nowhere. I went back to my PRD conversation and asked Gemini to write the text of a 2027 press release first. Then, I took that text, opened a fresh chat, and used the following prompt to generate the artifact.

Act as a product manager at Netflix working on the new random shuffle feature.

Create a motivating newspaper front page from the future (like a press release) to show how this feature is a massive hit and how it helps people.

Goal: Make it motivating. Show the value of the feature and how it fits our strategy.

Visuals: Ensure the image is positive.

Text: I want to be able to read the headlines clearly to share this with stakeholders.

Use the context we just discussed regarding the PRD to fill in the details.

---

[Here I copied and pasted the text from the generated article…]

The result:

It sets the tone immediately. But a vision is just a dream without execution. Let’s leave the high-level strategy and get down to the details of the UX. Remember that massive list of visual artifacts I asked for earlier? I decided to build some of them. But here is where I got really lazy, in the best way possible.

I already had a conversation open where Gemini had written the PRD for the Netflix feature. It knew everything: the user personas, the pain points, the roadmap. Instead of re-explaining all of that or recording new voice notes, I just asked Gemini to generate the text content for each artifact in that original thread.

Generate the text for a Netflix empathy map.

Generate the text for a 12-month roadmap.

Then, I simply copied that text and pasted it into my visual generator tabs. I used the exact same 3-tab rule, but instead of my voice, I used Gemini’s own output as the context.

Create minimalist diagrams

Let’s start with the clean, black and white, hand-drawn style.

Can you please create a simple infographic to explain this concept.

Style: Minimalist, simple, black and white, white background, clear. Hand-made like made by a human to explain the concept.

Will be included in an article.

---

[Here I copied and pasted the text from the PRD conversation…]

For the subsequent images, I just typed in the same conversation:

Nice! Same for the next part:

---

[Next chunk of text…]

Here are the results:

Switch to workshop mode

After a while, I felt the black and white was getting a little repetitive. I wanted to see if I could shift the vibe to look like a real-time workshop. I switched the prompt in a new conversation to simulate a graphic facilitator drawing live during a design sprint.

I’m preparing a design sprint session for product people. For the facilitation, instead of slides, I want you to generate graphic facilitation visuals.

Act as an experienced graphic facilitator. I want you to generate a graphic facilitation image to cover all topics in that workshop.

Here is the content for this section:

---

[Here I copied and pasted the text from the PRD conversation…]

And the results:

And then... crash. I hit the daily image generation limit again. But I think you get the point. For this experiment, I sprinted through a dozen complex artifacts to test the limits and have some fun. In real life, I wouldn’t spam the model like this. I would generate one or two key visuals, like that empathy map or the vision poster, and really iterate on them to make them impactful.

But knowing that I can visualize an entire product strategy in minutes? That changes the game.

We used to be stuck with ugly stick figures or endless bullet points while waiting for the real designs to materialize. Now, the barrier between your ideas and the screen is gone. To be clear: this doesn’t replace the deep collaboration of a live workshop. But it does bridge the gap between a messy thought and a shared vision. It allows us to communicate faster, with more emotion, and honestly? It makes the daily grind incredibly fun. I can finally agree with those graphic facilitators from my early days: everyone can draw now. You just need raw ideas, a little AI assistance, and the willingness to experiment.

So here is my challenge to you. Pick one boring document you are working on today, a Jira ticket, a spec, a strategy memo, and try to replace 500 words of text with one visual. Don’t overthink the prompt. Just open three tabs, hit the microphone button, and ramble. Let the machine handle the pixels while you handle the vision. Trust me, once you start, you won’t be able to stop.

When real estate agents were disrupted by Zillow, it was developers who built the code. When the hospitality industry was shaken by Airbnb, or taxi drivers were challenged by Uber, it was developers who wrote the algorithms. Every time an industry was turned upside down, the developers were the ones holding the shovel. They were the architects of change, safe in the control room while the rest of the world adapted to their code.

But now, for the first time to my knowledge, the disruption has come inside the house. The developers are disrupting themselves.

This is not just another framework update or a new cloud provider; this is a fundamental shift in who does the work. Just recently, Andrej Karpathy, one of the most respected thinkers in AI, shared a post on X that illustrates a paradigm shift:

He admitted that by December, his workflow had completely flipped: he is now 80% managing AI agents and only 20% touching the code manually. If one of the best engineers in the world is shifting from writing code to managing coding agents in the span of four weeks, imagine how the engineers on your team are processing this shift.

The result? A mix of adrenaline, confusion, and deep preoccupation.

Open Reddit or Hacker News, and you see two parallel realities. On one side, you have the hyper-enthusiasts claiming they built a startup in a weekend using Claude Code. On the other, you have legitimate anxiety and deep questioning. People aren’t just worried about their next performance review; they are wondering about their long-term relevance. They are asking:

Is my craft dead? Am I just a glorified spell-checker now? Is this even sustainable for the planet?

As a manager, you are standing in the middle of this storm. You might have top management demanding 90% AI adoption by Q4, while your team is looking at you with skepticism. You can’t just tell them, “Get on the bus or get left behind.” That’s lazy leadership. You also can’t recite the tired cliché that “AI won’t replace you, a human using AI will.” They know it’s a platitude.

I’ve spent the last months in the trenches, reading the forums, talking to developers at meetups, and watching the mood shift from “autocomplete is cool” to “how do I orchestrate agents?” But I didn’t just rely on my own observations. I spent hours dissecting these challenges with Gemini, asking it to act as a change management expert, to challenge my assumptions and help me structure a playbook for this specific transition. This article is the result of that collaboration: a distillation of the principles and tactics to help you lead when the ground is moving.

If you want to move your team from point A, uncertainty, to point B, empowerment, you need more than a license to access the latest model. You need a new way to talk about work. You need to address the legitimate concerns (e.g., the quality issues, the boredom, the loss of craft) without dismissing their reality.

Here is the plan we will cover:

• Some principles. We start with the psychology of change. We will look at why selling the solution fails if you don’t address the head, hands, and heart, and why you need to stop wasting energy arguing with resistors.

• Some tactics. We move to execution. I will share the concept of building lighthouse teams to prove value, explore why a training matrix might work better than a bootcamp, and discuss how to use Aikido to redirect energy in 1-on-1s.

• Some scripts. We face the hard truths. We will break down three deep objections I see most often: the fear of becoming a compliance officer, the risk of understanding debt, and the ethical concerns about energy usage.

I share here the patterns I have observed in the trenches and the strategies that are currently working for me. Every engineering culture is unique, and the AI landscape changes so fast that what works today might be obsolete in six months. Please treat these ideas not as laws, but as experiments to run. Take what resonates with your specific culture, discard what doesn’t, and iterate on the rest.

Let’s get to work!

Some principles for navigating change

Before we get into the specific scripts and tactics, I want to share how I mentally approach change. When I’m looking at a transformation, there are three specific visuals that always pop into my head. They aren’t the only models out there, obviously, but these are the ones that really stuck with me and helped me make sense of the human side of things.

Here are those three core principles defined as deep-dive action plans for managers.

#1. The head, hands, and heart: Ignite motivation

The context: When we talk about change, we often overcomplicate it. At its core, moving a human being from point A to point B requires three things to happen simultaneously. First, the head: they need the intellectual understanding of the strategy (the map). Second, the hands: they need the technical capability and the tools to execute (the driving skills). And finally, the heart: they need the emotional motivation to actually want to move (the fuel). If all three are present, you get movement. If one is missing, you stall.

The challenge: In most AI transformations, companies are excellent at addressing the head and the hands. You organize team meetings to explain the strategic vision (head), and you buy thousands of licenses for Claude Code (hands). But you completely neglect the heart. You give the team a map and a brand-new car, but you forget to put fuel in the tank. If your developers feel that AI is a threat to their craft, their identity, or their job security, their tank is empty. No amount of training will make the car move if there is no fuel.

The common trap: The most common mistake managers make is trying to fix a heart problem with a head solution. When a developer says, “I don’t trust this code, it’s garbage,” they are often expressing fear, not a technical opinion. If you respond by showing them a chart of productivity gains or explaining the roadmap again, you are missing the point. You are answering an emotional objection with a logical argument. This doesn’t reassure them; it makes them feel unheard and pushed into a corner. You cannot fix a feeling with a spreadsheet.

A different perspective: Stop selling the solution and start diagnosing the blocker. You need to identify exactly which of the three buckets, head, heart, or hands, is empty. Resistance is rarely a monolith; it’s specific. Is it that they don’t understand the goal? Is it that they feel unskilled? Or is it that they are afraid? You need to play the role of a mechanic diagnosing an engine before you try to drive the car.

The diagnosis: Conduct a listening tour. Don’t do this with other managers; do it with the people actually typing the code. Pick five developers and ask them these three specific questions to map their resistance.

1. Test the head: “If you had to explain to a new hire why leadership wants us to use AI, what would you say?” Listen carefully. If they say “To ship features faster” you are good. If they say “Because the boss read a tweet and got FOMO,” you have a head problem.

2. Test the hands: “What is the specific friction point that makes you want to close the tool right now?” Maybe the model keeps hallucinating deprecated libraries or losing context. This is a hands problem.

3. Test the heart: “When you open the AI tool, does it feel like a superpower, or does it feel like a chore?” This is the critical question. If they say “It feels like a chore” or “It makes me lazy,” you are dealing with a heart problem.

The fix:

• If the head is empty: Stop training. Start contextualizing. Show them how AI solves their specific business problems, not just the company’s stock price.

• If the hands are empty: Stop motivating. Start unblocking. The friction is rarely the laptop speed; it’s the integration complexity. Provide pre-built context scaffolding (like .cursorrules files) or run a context engineering workshop to solve the specific hallucinations blocking them.

• If the heart is empty: Stop explaining. Start reassuring. Explicitly frame AI as a tool to remove drudgery so they can focus on architecture. Give them a guarantee that using AI won’t negatively impact their performance review if things break initially.

#2. The change curve: Navigate emotional stages

The context: We tend to sell AI adoption like a rocket ship: you install the tool, and productivity shoots up and to the right immediately. But human reaction to deep change doesn’t work like that. It follows an U shape known as the Kübler-Ross change curve. It starts with shock, moves to denial, crashes into frustration and depression, and only then slowly climbs up to experimentation and acceptance.

The challenge: The danger zone is the bottom of the U, often called the valley of despair. After the initial excitement wears off, reality hits. Your team realizes the AI writes buggy code, uses outdated libraries, and requires heavy debugging. They spend more time fixing the AI’s mess than if they had written the code manually. Productivity drops below the baseline. This is where morale tanks, and people think: “This is useless. My workflow is ruined. I want to go back to the old way.”

The common trap: The worst thing you can do when your team is in the valley of despair is to stand at the finish line and cheerlead. If you stand in the integration phase and yell down to your depressed team, “Come on guys, look at the ROI! It’s great up here!” You look out of touch and delusional. It feels like toxic positivity. They don’t need to hear how great the future is; they need you to acknowledge how hard the present is.

A different perspective: You need to throw them a rope. Validation is your most powerful tool here. You must admit that the tool is imperfect and that the dip in productivity is the price of admission. By acknowledging the pain, you remove the pressure to pretend everything is perfect. You normalize the struggle, which paradoxically helps them move through it faster. The only way out of the valley is through it.

The diagnosis: Identify the phase. Look at your team honestly. Are they in denial (”This will pass”)? Anger (”This tool creates bugs”)? Or depression (”What’s the point”)?

The fix:

1. Validate loudly: Say clearly in your next meeting: “I know it feels slower right now. That is normal. We are in the messy middle, and I expect productivity to dip while we learn.”

2. The small step: Don’t ask for transformation. Ask for exploration. Tell them: “I don’t need you to change your whole workflow today. Just try to use it for one boring unit test. Just one.” Small wins are the ladder rungs out of the pit.

#3. The 20-60-20 rule: Focus on the watchers

The context: You cannot transform everyone at the same speed, and if you try, you will burn out. In every organization, adoption follows the 20-60-20 rule. Imagine a wedding dance floor. You have the top 20% champions who are already dancing and love the music. You have the bottom 20% resistors who are sitting in the corner with their arms crossed, skeptical of the playlist. And you have the middle 60% watchers standing on the edge, holding their drinks, waiting to see if it’s safe to join in.

The challenge: Most leaders spend most of their energy arguing with the resistors. They try to convert the loudest critics using logic, debate, and pressure. This is a massive trap. You risk confusing resistance with wisdom. While you are busy exhausting yourself in that argument, you miss the technical risks they are spotting, and the critical middle 60% gets bored, sees the conflict, and decides to sit down.

The common trap: Silencing the skeptics. In engineering, resistors are often the guardians of institutional memory. If you treat every objection as negativity, you create a culture of toxic positivity where legitimate technical risks, like security flaws or non-deterministic behaviors, are suppressed.

A different perspective: Filter the noise. Focus entirely on empowering the champions to attract the watchers, while simultaneously redirecting the resistors’ energy into quality control. The watchers don’t look to you (the manager) for social cues; they look to their peers. If they see the champions having fun and the resistors ensuring the system is robust, the watchers will naturally feel safe to join.