lauren
02c03a9ded
* pstack: add public usage tutorial Co-authored-by: lauren <poteto@users.noreply.github.com> * pstack: document verification skill workflows Co-authored-by: lauren <poteto@users.noreply.github.com> * pstack: mention verification setup offer Co-authored-by: lauren <poteto@users.noreply.github.com> * pstack: clarify optional verification setup Co-authored-by: lauren <poteto@users.noreply.github.com> * pstack: rewrite tutorial prompts to match real usage The example prompts read like specs. Real prompts are short, informal, and goal-first, so every example now uses that register. The prose reshapes around them: friendly second-person tutorial voice, goals before mechanics, pitfalls where readers actually trip, and the playbook reference table replaced with prompts in context. Every skill claim re-checked against the skill files at this commit. * pstack: make the README guide link an invitation Point new readers at what the guide walks them through instead of listing its topics. * pstack: drop the version bump This PR only adds documentation, so the plugin manifest stays at main's 0.11.7. * pstack: add illustrations to the guide One hero image per major guide page (routing, understanding, design, verification, overnight runs, recipes), 1200px JPEGs under docs/guide/images/. --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com>
4.2 KiB
Verify the result and open a PR
"It compiles" is not evidence. The Prove It Works principle makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, generating a verification skill for your app, and shipping.
State the finish condition up front
Put what done means in the first prompt, in whatever words fit:
/poteto-mode add json output to this command. text output stays byte-identical, the json parses, both run against the sample project. show me the evidence.
Now the agent has three checks it can run, not a mood to satisfy. When the reply comes back, it should carry the exact commands and outputs. If a check couldn't run, a good reply says "inconclusive", and you should treat a confident reply without evidence as a red flag.
Match the check to the change:
- A CLI change runs the real command.
- A UI change walks the changed flow in the running app.
- A parser or migration replays a saved input.
- A perf change compares before and after profiles.
- A storage change reads back the written value.
For a small diff you don't fully trust, /blast-radius finds what it could break elsewhere. It picks the one fact the change is safe because of and proves it by running code instead of writing an essay about it.
Create a project verification skill
The UI bullet above hides a real requirement. The agent needs a scripted way to drive your app. If your project has one, great. If not, run:
/create-verification-skill
/create-verification-skill interviews the repository, not you. It works out what a user touches, how the app launches locally, what can drive it (an existing harness first, otherwise browser and CDP, a PTY, or plain HTTP), what evidence proves behavior, and whether two instances can run side by side. It asks you only what the code can't answer.
It writes .cursor/skills/verify-<app>/, agent-facing instructions with exact Launch, Doctor, Drive, Evidence, and Cleanup sections, plus a feature map under features/ that indexes what the app does and what result proves each feature works. Before handing it over, the generator proves the skill once end to end: launch, doctor check, drive one feature, capture evidence, clean up. If that proof fails, don't use the output.
From then on, "verify it in the app" is a step any agent can execute, in this repo, with no setup conversation.
Keep the verification skill honest
Apps change and feature maps rot. When yours drifts, run:
/maintain-verification-skill
/maintain-verification-skill audits the generated skill: one read-only source reader per feature in parallel, then one live pass that drives every mapped feature. It ends in exactly one of three outcomes. clean means full coverage and nothing to ship. changed means one PR of proven corrections, confined to the verification skill's own directory. blocked names the blocker. It never edits product code. If the live pass catches a product regression, it reports the regression instead of papering over it in docs.
Ship it
/poteto-mode open the pr. small ordered commits, evidence in the description.
The Opening a PR playbook works from a worktree, rebases the work into small ordered commits, cleans the diff, unslops the prose, and returns the PR link. Five narrow PRs beat one fat one, and stacked follow-ups beat a growing branch.
Note
pstack doesn't bundle PR monitoring or stacked-PR tooling. After the PR opens, use Cursor's built-in PR tools to watch CI and process review comments. Judge each comment against your intent before changing code. Reviewers, human and bot, file real catches and noise in the same list.
Next: Run work while you sleep.