Skip to content
Merged
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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ One orchestrator skill (`poteto-mode`) routes tasks to playbooks. Supporting ski
| `pstack:poteto-mode` | Orchestrator and playbook routing. |
| `pstack:how` | Codebase exploration. |
| `pstack:architect` | Design types and module boundaries. |
| `pstack:interrogate` | Adversarial multi-reviewer review. |
| `pstack:interrogate` | Adversaries break a change; only run-proven findings survive. |
| `pstack:swarm` | Parallel workers and aggregation. |
| `pstack:unslop` | Clean AI writing patterns from prose. |
| `pstack:deslop` | Clean AI code slop from diffs. |
Expand Down Expand Up @@ -65,7 +65,7 @@ Then in any chat session:
| `/poteto-mode` | Load the orchestrator (task routing, principles, delegation). |
| `/how` | Codebase exploration. "How does X work?" |
| `/architect` | Design types and boundaries before building. |
| `/interrogate` | Adversarial multi-reviewer code review. |
| `/interrogate` | Adversaries break a change; only run-proven findings survive. |
| `/swarm` | Fan out parallel workers. |
| `/unslop` | Strip AI writing patterns from prose. |
| `/setup-pstack` | Pick the delegate model and reasoning budget. |
Expand Down
4 changes: 2 additions & 2 deletions docs/guide/04-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,9 @@ Reach for it when parallelism buys coverage or lets independent checks race. Com
load pstack:interrogate the whole branch, but skeptically. no nitpicks unless it's an actual bug or regression.
```

[`pstack:interrogate`](../../skills/interrogate/SKILL.md) sends the same diff, intent, and rubric to several reviewers on different model families. Model diversity is the point. Different models have different blind spots, so a finding two models raise independently is high-confidence signal. The lead sorts everything into `Act on`, `Consider`, `Noted`, and `Dismissed`, with a reason for each dismissal, and applies nothing automatically.
[`pstack:interrogate`](../../skills/interrogate/SKILL.md) gives the change and its intent to adversaries spawned with `delegate_task`, and each tries to break it with a run against the real code. Adversaries find different failures. A finding survives only when rerunning its command shows a failure that breaks the intent. The report lists every verified finding with the adversaries that found it, then what each adversary dropped and why, and applies nothing.

Read the dismissals too. The lead is a pragmatic senior engineer, not an oracle, and you can override it.
Read the Dropped list too. You can override the verdict.

## How much design work does a task deserve?

Expand Down
6 changes: 3 additions & 3 deletions docs/guide/07-overnight.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,13 +63,13 @@ The contract above drives one task to one finish condition. Some nights hold mor
load pstack:poteto-mode full autopilot on this queue. each item is independent. i want them merged by morning.
```

[Autopilot-stack](../../skills/poteto-mode/playbooks/autopilot-stack.md) runs the same owner loop but ships nothing. You wake up to one linear stack with a verifier's verdict on every link, and you review and land it yourself. Pick it over Autopilot-full when the changes are coupled, or when you want your own eyes on the work before anything merges:
[Autopilot-stack](../../skills/poteto-mode/playbooks/autopilot-stack.md) is Autopilot-full without the merge. You wake up to verified PRs, each with its verdict, and you review and land them yourself. A PR stacks only on a PR it builds on. Pick it over Autopilot-full when you want your own eyes on the work before anything merges:

```text
load pstack:poteto-mode autopilot these five changes but stack them, don't ship. i'll land the stack in the morning.
load pstack:poteto-mode autopilot these five changes, but don't merge. i'll land them in the morning.
```

[Orchestrate](../../skills/poteto-mode/playbooks/orchestrate.md) is for a program that outlives any single agent: multi-day, many stacked PRs, fleets of delegate_task subagents under one standing coordinator chat. The coordinator authors briefs, collects what its subagents finish, keeps the lowest unmerged PR green, and never writes code itself. It's deliberately heavy machinery. If one agent could finish the work in a session, the playbook itself routes you back to the overnight contract above:
[Orchestrate](../../skills/poteto-mode/playbooks/orchestrate.md) is for a program that outlives any single agent: multi-day, many stacked PRs, fleets of delegate_task subagents under one standing coordinator chat. The coordinator decides which agent does each piece of work, checks what each one produces, and never writes code itself. If one agent could finish the work in a session, the playbook itself routes you back to the overnight contract above:

```text
load pstack:poteto-mode orchestrate the store migration. own it until every package is converted and merged. i'll check in twice a day.
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/10-recipes-and-pitfalls.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Each worker owns one package. The parent waits for every slice and returns one `
/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's an actual bug or regression in behavior.
```

The qualifiers do real work. "don't change anything yet" keeps it read-only, and the nitpick rule pre-filters the noise so `Act on` findings are worth your time.
The qualifiers do real work. "don't change anything yet" keeps it read-only, and the nitpick rule pre-filters the noise so the verified findings are worth your time.

## Fix a bug through a failing test

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.4"
version: "0.3.5"
description: "Poteto's engineering rigor stack. Playbooks, principles, multi-model review."
author: poteto (adapted by Madeleine)
71 changes: 18 additions & 53 deletions skills/interrogate/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,79 +1,44 @@
---
name: interrogate
description: "Use before merging for adversarial multi-model code review."
version: 0.1.0
description: "Use before merging to have adversaries break a change."
version: 0.2.0
author: poteto (Hermes adaptation)
license: MIT
platforms: [linux, macos, windows]
metadata:
hermes:
tags: [engineering, workflow]
related_skills: []
related_skills: [pstack:in-your-own-words, pstack:swarm]
---

# Interrogate

Spawn multiple `delegate_task` subagents to adversarially review code changes. Adversarial signal comes from model diversity - independent reviewers finding the same issue means high confidence.
Adversaries try to break a change or a design. A finding survives only when a run proves it. Report the findings. Do not apply fixes.

## When to Use

Before merging significant changes. When you want more than one perspective on correctness, security, or design. When the stakes of a bug are high.
Before merging significant changes, or to stress test a design you can prototype. Say "interrogate", "adversarial review", "challenge this", "stress test this code", "find blind spots", or "tear this apart".

## Procedure
## Frame

### 1. Determine Scope
The scope is what the user names. Otherwise it is the branch diff from its merge base with the base branch, through the working tree (`terminal` with `git diff $(git merge-base HEAD origin/main)`). State the intent with `pstack:in-your-own-words`, from the user's message, the commits, and the PR description. Ask the user when the intent is unclear.

Identify what to review:
- A diff (`terminal` with `git diff`)
- Specific files (`search_files`, `read_file`)
- Recent work (`git log --oneline -10`, then diff the range)
## Fan out

Collect the relevant code and context.
Spawn two or three adversaries in parallel with `delegate_task`. Give each its own scratch copy of the repo (a `git clone` or `git worktree add` under the scratch directory) with the scope's uncommitted changes applied, so repros never touch the real checkout. When the delegation config allows another model family, run adversaries on different families. Otherwise vary the angle each one attacks first. Give each adversary the scope, the intent, its copy's absolute path, and this brief:

### 2. State Intent
> Break this change. Prove each finding with a run against the real code, such as a failing test, a repro script, or command output that shows the wrong behavior. For a design or plan, run a prototype or probe the current tree. Keep repros in your own copy. Report each finding with a title, the exact command, the output it printed, and the output the intent requires. Leave out anything you did not run. That covers style, naming, structure, and risks that need a future change to matter. No findings is a valid result.

Write one sentence: what does this code change try to accomplish? This anchors every reviewer. Without it, reviewers invent their own assumptions.
If an adversary returns nothing, continue with the rest and note the dropout.

### 3. Spawn Reviewers
## Verify

Launch at least 2-3 parallel reviewers via `delegate_task`. Each gets the same prompt:
Rerun each finding's command yourself with `terminal`. Keep a finding when the output shows the failure and the failure breaks the intent. Drop the rest. Merge findings that share a root cause.

```
Review this code change.
Adversaries find different failures, so the verdict keeps every verified finding, not one adversary's list. Do not pick a winner.

Intent: [one sentence from step 2]
## Output

Code:
[the diff or file contents]

Review against this rubric:
- Correctness: does it do what intent says? Logic errors, off-by-ones, nil paths?
- Edge cases: empty inputs, concurrent access, large inputs, unicode, zero/negative values?
- Security: injection, auth bypass, secrets in code, unsafe deserialization?
- Performance: unnecessary allocations, O(n²) where O(n) works, missing indexes?
- Maintainability: unclear names, implicit coupling, missing error context?

For each finding:
- Quote the relevant code
- State the problem
- Rate severity: critical / warning / nit
- Suggest a fix (one-liner if possible)
```

### 4. Synthesize

Read all reviewer outputs. Consolidate:

- **Agreement** (2+ reviewers flagged it) → high confidence, include in verdict
- **Lone findings** → lower confidence, include as "worth reading" with the single reviewer's reasoning
- **Contradictions** → re-read the code yourself to break the tie

### Deliverable

One synthesized verdict with:
- Summary (ship / revise / block)
- High-confidence findings (with code quotes)
- Worth-reading findings
- What reviewers agreed was fine

**Do NOT auto-apply changes.** Present findings. The user decides.
- **Intent**: the restatement.
- **Findings**: for each verified finding, the command, its output, how it breaks the intent, and the adversaries that found it. Say "no verified findings" when none survive.
- **Dropped**: for each adversary, the count of dropped findings and why.
3 changes: 2 additions & 1 deletion skills/poteto-mode/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ 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. |
Expand Down Expand Up @@ -76,7 +77,7 @@ The ladder runs after you understand the problem, not instead of it. Read the ta
- **Fix Root Causes.** Reproduce first. Ask why until root cause. No nil-check guards that mask the real bug.
- **Sequence Verifiable Units.** Small units, verify each before next. Do not batch unverified work.
- **Test Behavior Not Implementation.** Call code like users do. Assert literal expected values.
- **Explain the Number.** Before you trust, report, or act on a measured number (speedup, regression, latency, eval result), name what limits it and rule out that it measured something else (errors, skipped or cached work, an untuned side, noise, a piece too small to matter). Keep run count, spread, and limiter with the number.
- **Explain the Number.** Before you measure, write the result that would change a decision and the noise floor. Before you trust, report, or act on a measured number (speedup, regression, latency, eval result), name what limits it and rule out that it measured something else (errors, skipped or cached work, an untuned side, noise, a piece too small to matter). Keep run count, spread, and limiter with the number.

### Delegation

Expand Down
2 changes: 1 addition & 1 deletion skills/poteto-mode/playbooks/autonomous-run.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
- **Commit if it advanced.** Discard and try differently if it didn't.
- Never make two unverified changes in a row.

3. **Handle side discoveries.** Broken tests, related bugs, flaky verifiers - fix them yourself as they appear. Don't log them for later; they'll block the predicate if you ignore them. Keep fixes in separate commits.
3. **Handle side discoveries that support the goal.** Broken tests, related bugs, flaky verifiers - fix them yourself as they appear. Don't log them for later; they'll block the predicate if you ignore them. Keep fixes in separate commits.

4. **Checkpoint every iteration.** After each commit, re-evaluate: how many units remain? Is the approach still converging? If you've made 3 iterations with no progress, step back and reassess the approach - don't keep grinding the same wall.

Expand Down
Loading
Loading