Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/guide/02-poteto-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ load pstack:poteto-mode im stepping away. keep going until the migration check r

Work you'll review later routes through [`pstack:figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases and keeps a [`pstack:show-me-your-work`](../../skills/show-me-your-work/SKILL.md) decision log. [Run work while you sleep](./07-overnight.md) covers the full overnight contract.

**Pitfall:** don't enumerate skills in your prompt ("use pstack:how, then pstack:architect, then pstack:interrogate..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.
**Pitfall:** don't enumerate skills in your prompt ("use pstack:architect, then pstack:interrogate, then pstack:unslop..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.

Read [`poteto-mode`](../../skills/poteto-mode/SKILL.md) itself for the full routing rules.

Expand Down
4 changes: 2 additions & 2 deletions docs/guide/03-understand.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ Editing code you don't understand is how subtle regressions ship. pstack gives y
load pstack:how do we dedupe notifications? is there an n+1 when we look up subscribers?
```

Ask the question you actually have. [`pstack:how`](../../skills/how/SKILL.md) reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, the key types, and the non-obvious parts. For a big subsystem it fans out two to four read-only explorers first. For a narrow question it just reads and explains.
Ask the question you actually have. [`pstack:how`](../../skills/how/SKILL.md) reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, the key types, and the non-obvious parts. It starts one read-only `delegate_task` subagent that explores the code and writes the explanation.

## Dig up history with `pstack:why`

```text
load pstack:why was the retry limit set to five? does the reason still hold?
```

[`pstack:why`](../../skills/why/SKILL.md) works like a detective on a cold case. It starts from source control, then queries whatever evidence categories your MCPs expose, such as the issue tracker, long-form docs, team chat, observability, error tracking, and analytics, all in parallel. The report cites everything, separates direct evidence from inference, and says "appears to" when the record is thin. A null result gets reported too, because "nobody wrote down why" is itself an answer.
[`pstack:why`](../../skills/why/SKILL.md) answers from the record, not the code. It reads the commits and PR discussions that introduced the code and each later change, and looks at other sources when that trail is thin. The answer cites what the authors wrote, marks the agent's own inferences as inferences, and says what the record does not answer, because "nobody wrote down why" is itself an answer.

The two compose naturally. `do why first then how` is a perfectly good prompt when you suspect the history explains the mess.

Expand Down
2 changes: 1 addition & 1 deletion docs/guide/04-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ One attempt at a hard design locks in the first shape the model thought of. `pst
load pstack:architect design the import pipeline before writing any code. i care most about how callers use it.
```

[`pstack:architect`](../../skills/architect/SKILL.md) grounds itself first, running `pstack:how` over the code the design touches and `pstack:why` when it moves ownership or layers. Then it runs a competitive design round to produce competing design sketches, with the caller's usage written first in each, followed by types, signatures, and a module map.
[`pstack:architect`](../../skills/architect/SKILL.md) grounds itself first, tracing the code the design touches and running `pstack:why` when it moves ownership or layers. Then it runs a competitive design round to produce competing design sketches, with the caller's usage written first in each, followed by types, signatures, and a module map.

By default it proceeds straight from the synthesized design into implementation. If you want to see the design first, say so:

Expand Down
2 changes: 1 addition & 1 deletion plugin.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: pstack
version: "0.3.5"
version: "0.3.6"
description: "Poteto's engineering rigor stack. Playbooks, principles, multi-model review."
author: poteto (adapted by Madeleine)
2 changes: 1 addition & 1 deletion skills/architect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Before building a new subsystem, feature, or significant refactor. When the shap

### A. Ground the Problem

Run `pstack:how` over relevant existing subsystems. Understand what's already there before designing something new. Read the code the new work will touch and integrate with.
Trace the relevant existing subsystems. Naming a file isn't grounding. Read the code the new work will touch and integrate with, and write an architectural explanation of each. If the design redefines ownership or layering, also run `pstack:why` on the existing shape so the rationale becomes a constraint, not a guess.

### B. Sketch

Expand Down
4 changes: 2 additions & 2 deletions skills/blast-radius/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,10 @@ Step 4 is usually one small script that imports the same library the app ships a

## Steps

1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Use `why` step 2 to pull the PR and commits.
1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Pull the PR and its commits.
2. Find the one fact it's safe because of. Most changes that look risky are safe because of a single fact, like "this call only drops already-dead cache entries and does nothing else". Find that fact. If it holds, most risky cases are cleared at once. Spend your time here, not on a long list of maybes.
3. Look where grep stops. Read the source of the library you call, and check its pinned version and any local patch. Work out when things run: microtasks, unmount and teardown, Solid versus React. Follow what a symbol search misses: the JSON an API returns, a DB column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream.
4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Same rules as `why`. Cite a real `file:line`, a search that finds nothing is still an answer, and never make up a caller or an API.
4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Cite a real `file:line`, a search that finds nothing is still an answer, and never make up a caller or an API.
5. Prove the one fact. Write a script or test that runs the real code, run it, and paste what happened.
6. For a big or wide change, run it as an `arena`. Ask several models the same question and merge the answers. Different models catch different real bugs.

Expand Down
58 changes: 8 additions & 50 deletions skills/how/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: how
description: "Use to explain how code works, with walkthroughs."
version: 0.1.0
version: 0.2.0
author: poteto (Hermes adaptation)
license: MIT
platforms: [linux, macos, windows]
Expand All @@ -13,58 +13,16 @@ metadata:

# How

Answer "how does X work?" with clear architectural explanations grounded in actual code.
Explore the codebase to answer "how does X work?" questions.

## When to Use
If the scope is ambiguous, state your interpretation and explore. The user can redirect.

When the user asks how a subsystem, feature, or mechanism works. Also invoked by other pstack skills (e.g. `pstack:architect`) to ground design in existing code.
## 1. Explain

## Modes
Spawn one read-only `delegate_task` subagent (tools limited to `search_files` and `read_file`) that explores and explains in one pass. Give it the user's question and this brief:

### Explain (default)
> You are writing an architectural explanation for a senior engineer. Explore the codebase and write an explanation that a senior engineer unfamiliar with this area could read and walk away with a solid mental model. They should understand the architecture well enough to start working in it confidently. You have read-only access to the codebase.

Explore the codebase and produce an explanation.
## 2. Present

**Simple questions** (single module, one concept): do it in one pass - `search_files` to locate, `read_file` to understand, write the explanation.

**Complex questions** (multi-file subsystem, cross-cutting concern): decompose into 2-4 exploration angles, delegate each as a read-only subagent via `delegate_task`, then synthesize results into a single explanation.

### Critique

Explain first (as above), then spawn multiple `delegate_task` subagents to independently identify architectural issues. Each critic works from the explanation plus direct code access. Synthesize their findings into a problems section appended to the explanation.

## Exploration Technique

Explorers use `search_files` and `read_file` to trace code. The approach:

1. **Start broad** - glob for directories (`search_files` with `target="files"`), grep for key types/interfaces/exports. Understand the shape before the details.

2. **Follow the thread** - from entry points, trace callers and callees. Follow data flow: where is it created, transformed, consumed? Read actual code at each hop.

3. **Read actual code** - don't stop at file names or function signatures. Read the implementation. The interesting behavior lives in the body, not the type.

4. **Note surprises** - anything that violates the expected pattern is worth calling out. Implicit dependencies, side effects, hidden state, fallback paths.

## Output Format

Structure the explanation as:

- **Overview** - one paragraph, what this subsystem does and why it exists
- **Key Concepts** - types, abstractions, or domain terms needed to follow along
- **How It Works** - step-by-step walkthrough of the main flow, referencing files and functions
- **Where Things Live** - file/directory map of the relevant code
- **Gotchas** - surprises, implicit contracts, known quirks, easy mistakes

## Delegation Pattern

When decomposing for `delegate_task`:

```
Each subagent brief:
- Goal: "Trace how [specific aspect] works in [scope]"
- Constraint: read-only, no modifications
- Tools: search_files, read_file only
- Output: structured notes with file paths and line references
```

Synthesize by merging notes, resolving contradictions (re-read code if needed), and writing the unified explanation.
Present the subagent's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
2 changes: 1 addition & 1 deletion skills/no-comments/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Use the caller's files or diff. Otherwise use the current diff against the base
## Steps

1. Spawn one `delegate_task` with the scope and Comment Sicko's review prompt. Pass the scope. Do not restate its rules.
2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, run `/how` or `/why` on their symbol. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`.
2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, trace their symbol or run `pstack:why` on it. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`.
3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, run `/architect` once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements.
4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The **principle-fix-root-causes** and **principle-redesign-from-first-principles** skills guide intent only. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards.
5. Constraint comments say `do not remove`, `do not change wording`, or `talk to X before changing`. Leave keeps about things we cannot change. Offer the cheapest in-scope type, runtime, test, or CI lint. Wait for interactive approval. Unattended and eval require caller pre-approval. If approved, encode then delete. Otherwise delete, report the constraint open, and sketch out-of-scope work.
Expand Down
2 changes: 1 addition & 1 deletion skills/no-comments/references/comment-sicko.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ That list is my only leash. When I am not sure a keep clause applies, the commen

`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.

`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I trace the named symbol or call, run the **why** skill on it, or both. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.

A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.

Expand Down
1 change: 0 additions & 1 deletion skills/poteto-mode/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ These triggers fire before you write anything. No exceptions.
| Trigger | Action |
|---------|--------|
| Your first message on a task | Tell the user, in your own words, their goal, the problem they are solving, and, if the task ships a change, the smallest change you expect to meet it. Don't wait for confirmation. If the evidence rules out the change they asked for, show it and stop. Restate the goal in each subagent brief, in each PR's `## Why`, and at the top of each final report, except after a fully specified one-line edit. |
| Nontrivial change (new feature, refactor, multi-file edit) | `skill_view(name='pstack:how')` first. Plan before code. |
| Any code produced | Name the data shape before writing logic. Types first, functions second. |
| Code crossing a function/module boundary | `skill_view(name='pstack:architect')`. Design the seam. |
| Parallel fan-out (3+ independent slices) | `skill_view(name='pstack:swarm')`. Coordinate subagents. |
Expand Down
2 changes: 1 addition & 1 deletion skills/poteto-mode/playbooks/bug-fix.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

1. **Reproduce it yourself.** Don't ask the user for more info yet - try to hit the bug with `terminal`, tests, or manual verification. If you can't reproduce, *then* ask. A bug you can't trigger is a bug you can't verify you fixed.

2. **Binary-search the cause.** Seed understanding with `pstack:how` over the affected subsystem. Then:
2. **Binary-search the cause.** Seed understanding by tracing the affected subsystem yourself (`search_files`, `read_file`). Then:
- Form 2-3 hypotheses for root cause.
- For each: find runtime evidence that confirms or eliminates it (`terminal` for logs/debugger, `search_files` for call sites, `read_file` to trace flow).
- Eliminate until one survives. If none survive, your model is wrong - re-read.
Expand Down
2 changes: 1 addition & 1 deletion skills/poteto-mode/playbooks/feature.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## Steps

1. **Understand the subsystem.** Run `pstack:how` over every module the feature touches. Don't design until you know what's already there.
1. **Understand the subsystem.** Trace every module the feature touches. Don't design until you know what's already there.

2. **Design exploration.** Run `pstack:architect` - explore approaches, pick one, document why. Output: a short design doc with the chosen approach and its trade-offs.

Expand Down
Loading
Loading