Foundations Scenarios

These scenarios are designed for your first day with your agentic CLI. Each one uses your own codebase — no starter projects or sample repos required. They focus on the fundamentals: writing good prompts, feeding the agent useful context, and building the habit of iterating on responses.

If you have not used your coding agent before, start with the first scenario and work through them in order.

---

Your First Prompt

Time: 5 min | Technique: Prompting patterns

The situation: You have a file in your project that you wrote a while ago, or that someone else wrote. You know roughly what it does, but you want to see how the agent explains it — and you want to practice the difference between vague and specific prompts.

What to do:

1. Pick a file from your project and ask the agent: What does this code do? — note what you get back.
2. Now try a specific prompt: Read @path/to/your-file and explain each function. Which ones have edge case bugs? — compare the two responses.
3. Follow up with: Add type hints (or equivalent) to all functions and add a docstring to each one. Review what the agent produces and iterate: That's close, but also handle the case where the input is empty.

Success looks like: You have seen the difference between a vague and specific prompt, you have used @file to give the agent direct context, and you have iterated on at least one response to refine the output.

---

Debugging with Your Agent

Time: 15 min | Technique: Debugging workflow

The situation: You have a failing test, a known bug, or a section of code that is not behaving as expected. Instead of debugging alone, you want to use the agent as a debugging partner by feeding it real error output and working through fixes incrementally.

What to do:

1. Run your test suite (or reproduce the bug) and copy the error output — stack trace, test failure, or log lines.
2. Paste the output into the agent and ask: Here are the test failures from running [your test command]. Analyze each failure, identify the root cause in the source code, and fix the bugs one at a time. After each fix, explain what was wrong and why your fix is correct.
3. After the agent fixes the first issue, re-run the tests. If more failures remain, feed the new output back: Here are the remaining failures after your fix. Fix the next one.

Success looks like: At least one bug is fixed and verified by a passing test. You have practiced the pattern of feeding the agent structured error output and guiding it to fix issues incrementally rather than all at once.

---

Codebase Navigation

Time: 5 min | Technique: Explore-Plan-Code-Commit

The situation: You need to understand how a specific feature works across your codebase — for example, how authentication flows from the frontend through the backend, or how a particular data model is used. Reading files one at a time is slow. You want the agent to map the relevant parts of the codebase for you.

What to do:

1. Ask the agent to survey the landscape: I need to understand how [feature X] works in this codebase. List the files and packages that are involved, and explain how they connect to each other.
2. Once the agent identifies the relevant files, narrow in: Now read @path/to/file-a and @path/to/file-b together. How does data flow between them? Are there any mismatches or inconsistencies?
3. Ask the agent to produce a summary: Write a 5-sentence explanation of how [feature X] works that I could share with a new team member.

Success looks like: You have a clear mental map of how a feature works across multiple files, produced in a fraction of the time it would take to read every file yourself. You have practiced the “start broad, then narrow” investigation pattern.