Skip to content
  1. How-to
  2. In real projects
  3. Take over an unfamiliar project

Take over an unfamiliar project

In one lineStart with "don't change any code yet" and let it walk you through. Then ask about details with /pstack:how and /pstack:why.

Half an hour on day one, then ask as you goFor: You're taking over someone else's project, or coming back to your own after months, and want to understand it firstFull guide step 4: Understand before you change

Copy this first

Your first prompt
/pstack:poteto-mode Help me understand this project: what it does, how to run it locally, and where the main code lives. Tell me which files you read and what sources you used. Don't change any code yet.
  • “Don’t change any code yet”: until it understands the code, it only reads. It investigates and opens no PR.
  • “Tell me which files you read”: it keeps what it read apart from what it inferred.

Where to look after you send it

You get back a write-up, with a source for each point. It usually covers:

  • Overview: what the project does.
  • Key ideas and how it works.
  • Where things live.
  • Traps to watch for.

Then ask about details: four commands

Command Answers Example
/pstack:how How it works now How are alerts deduped?
/pstack:why Why it was built this way Why 5 retries max?
/pstack:teach Until you really get it Teach me this retry change
/pstack:recall Where you left off Where’s the export work?
  • /pstack:why checks Git history first, then issues and docs. If it finds nothing, it says so. “Nobody wrote down why” is an answer too.
  • /pstack:teach: add “convince me,” and the explanation becomes an argument you can check.
  • /pstack:recall reads only your own history in this project, from the last 7 days by default.

A member site example

A friend hands you a member site on Cloudflare Workers, with data in D1. You need to change how membership expiry works. Start with the first prompt above, then ask:

First, ask how it works now
/pstack:how After a user logs in, how does their membership status make its way to the page? Where is the session stored? Where is membership expiry checked?
Then ask why
/pstack:why Why is the membership expiry check written twice, in two different places? Does that reason still hold?
Finally, until you really get it
/pstack:teach I need to change the membership expiry logic. Teach me how this part works, and convince me that changing it in only one place won't kick out users who already paid.

After these three, let it make changes. By then you both have the same picture.

Picking up a half-finished branch

Last week’s you, or another AI conversation, got halfway through a branch. Send this:

Pick up where it left off
/pstack:poteto-mode Take over this branch. Read the decision log, work out what's already done, and continue from there. Don't redo anything that's already done.

It finds the earlier records (conversations, branches, the decision log) and says which step it will continue from. If the earlier conversation said “passed,” it checks again itself.

/pstack:recall versus picking up a branch

To continue one specific conversation, use the prompt above. To recover the story of your last few conversations before starting something new, use /pstack:recall. For example: “/pstack:recall my work on the virtual list yesterday, then read this bug report.”

Stuck?

I said don't change anything, and it changed code anyway.

For a new question in the same conversation, start with “new task”: “/pstack:poteto-mode new task. Figure out why the cache is still there after logout. Don’t change any code yet.” Without it, it treats your question as the next step of the last job.

/pstack:why says it can't find the original reason.

That’s a normal result. If you know where the answer might be, like an issue link or an old doc, paste it in.

It explained everything, but I didn't follow.

Type /pstack:bro. It retells its last reply in plain words, shorter.

Picking up a branch, it redid work that was already done.

Reply: “The earlier records are trustworthy. Don’t start over. Tell me which step you’ll continue from.”

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.