Contents
pstack helps coding agents understand a system before making changes and verify results before declaring completion. Start by running /poteto-mode and describing your desired outcome and acceptance criteria so it can select the right workflow.
Key Points#
/poteto-modeselects a playbook suited to tasks such as bug fixes or repository investigations.- Its development principles emphasize understanding existing behavior, modeling valid states, and keeping changes focused.
- Completion requires evidence from actual behavior, including checks that catch the original bug.
- Installation and model configuration are separate steps, and stopping for a design review requires explicit instructions.
How pstack Works#
pstack is a collection of agent skills from poteto for Cursor and Claude Code. Its entry point, /poteto-mode, selects a “playbook”: a task-specific procedure that invokes the skills needed for the work.
The documented bug-fixing workflow has four stages:
1. Reproduce the bug. 2. Form hypotheses and gather runtime evidence. 3. Design a fix and delegate implementation. 4. Repeat the original action and verify the results.
Investigations use a different playbook. It answers questions about a repository without changing code and produces evidence-backed explanations and recommendations. Playbooks are internal procedures; there is no directly executable /bug-fix command.
Principles That Guide Changes#
The how skill investigates how existing code works. For a caching issue, it traces where values are stored, when they are read, and how failed results affect subsequent calls. This helps prevent adding retry conditions to callers when the cache itself needs fixing.
“Model the Domain” asks agents to represent business rules and valid states through data structures. A clearly defined state machine can be easier to understand than several independent boolean flags. The architect skill applies this principle by outlining types, function signatures, and module boundaries, then comparing structurally different designs. If a simple representation already expresses the rules clearly, it keeps that representation.
“Laziness Protocol” emphasizes the smallest sufficient change and reducing repeated decisions. Shorter code helps when it reduces complexity, but unrelated abstractions do not help identify a bug’s cause and expand the scope of review. A related requirement, “Fix Root Causes,” calls for investigating why incorrect behavior or data exists before choosing a local workaround.
Installation and Configuration#
The README for Claude Code provides these commands:
/plugin marketplace add cursor/plugins
/plugin install pstack@cursor-plugins
/setup-pstack/setup-pstack checks the available models and configures a model and reasoning budget for each role. The guide recommends Opus for roles that require substantial judgment, while implementation and investigation roles inherit the current session’s model. Check the options offered in your environment before relying on those defaults.
The configuration is saved to ~/.claude/rules/pstack-models.md. To change it, run /setup-pstack again. If you need help choosing skills or using the collection, use /poteto-help.
Writing Useful Task Requests#
Tell the agent about the observable problem, relevant differences between environments, and how to verify completion. For example: “The tag page shows an error in the browser, but curl returns 200. Reproduce this in a local production preview, identify the cause, and verify that the tag list renders. Show the HTTP status and browser errors before and after the fix.”
This distinction matters. In the example presented, an empty tag slug caused duplicate keys and hydration failures. The server returned 200, but the browser displayed an error page. Checking HTTP alone would therefore have missed the bug. The proposed solution was to correct the invalid tag data and address the bug in tag generation.
If you want to review a design during architecture work, ask the agent to pause. According to the documentation, architect proceeds through implementation by default. Specifically, say: “Review the cache design. Show the public functions and state representation before implementation, and wait for my review.”
Checking Evidence and Review Recommendations#
“Prove It Works” requires checking actual results rather than simply accepting successful compilation or an agent’s completion report. For bug fixes, repeat the action that originally failed. A regression test must fail with the original behavior and pass after the fix. A test that already passed cannot demonstrate that the bug has been fixed.
Match verification to the bug. Browser rendering issues require browser checks, while production-specific data access requires a configuration that reproduces those conditions. Reusable verification scripts help repeat these checks.
The interrogate skill consolidates reviews from multiple models and classifies findings as act on, consider, record, or dismiss. It does not automatically apply every recommendation. Agreement among models is evidence to consider, and each finding still needs to be checked against the code and requirements.
Next Steps#
Choose one reproducible bug and run /poteto-mode, specifying the failing action, the environment, and the concrete behavior that will demonstrate the fix.
Source: https://azukiazusa.dev/blog/pstack-agent-skills/
Contents
