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 docs/guide/04-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,12 +120,12 @@ For a migration, state the bar in the prompt:

You might be wondering whether every change needs this. No. Most changes need none of it. A rough ladder:

- A small, finished change you're unsure about needs `/interrogate` alone.
- A small, finished change you're unsure about needs `/blast-radius`, which proves the one fact that makes it safe. Use `/interrogate` only when you want an adversarial review.
- A change that crosses function boundaries or moves ownership earns `/architect`, which brings `/arena` with it.
- A standalone decision where independent attempts would help, like naming, formats, or an algorithm, is `/arena` directly.
- A coverage matrix, set of parallel checks, or race with declared arms is `/swarm`.
- An open question you could answer by running something, like a layout, a timing, or an approach, gets a prototype, not a debate.
- A contested design that's expensive to reverse gets `/architect`, then `/interrogate` before shipping.
- A contested design that's expensive to reverse gets `/architect`, then a prototype, `/statechart`, or formal verification before shipping. Evidence settles it better than another review.
- Work that spans several PRs gets a plan, written after the design settles.

`/meta-mode` already applies this ladder. Boundary-crossing work triggers `/architect` on its own, so you reach for these directly mainly when you want more or less scrutiny than the default.
Expand Down
12 changes: 6 additions & 6 deletions profiles/skill-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
"upstream": "pstack",
"source": "skills/architect/SKILL.md",
"sourceDigest": "31f8e97a52bfa5432edd61f68ade2a8632ef0bacbc2d2a6802d7a0e6821944ac",
"targetDigest": "76c299297a79236fa519d401716a6ad1845ecc1a3f4fdff2aa052309261651aa"
"targetDigest": "8ab2154c8f977a50ed7754d77b989ea610b2ffbc379932bc55357beed0c45fe1"
},
"skills/arena/SKILL.md": {
"upstream": "pstack",
Expand Down Expand Up @@ -247,7 +247,7 @@
"upstream": "pstack",
"source": "skills/poteto-mode/playbooks/bug-fix.md",
"sourceDigest": "66e26542dad131cfd7df80ac0cdf81ed4d85e7b5e3f0eb65b933888760c4831f",
"targetDigest": "8872387c8893159c2557929af3c2b35270b245ace9aa04b76f3d8f622b526d2d"
"targetDigest": "a1349fb3715f2878178041703c99fa54810f641237c8a8dc74ac93acfe2a66d1"
},
"skills/meta-mode/playbooks/eval.md": {
"upstream": "pstack",
Expand All @@ -259,7 +259,7 @@
"upstream": "pstack",
"source": "skills/poteto-mode/playbooks/feature.md",
"sourceDigest": "af8ce700b99953741cb547e34308fde0cf6b98ce67e1652c800d0deedf53aba1",
"targetDigest": "f9ac3784c615c1e84d40ec30ede16872988dcb8364d480343e4d98b7961f06c2"
"targetDigest": "84770de9c0f52649e920865448377041ab18673f62f71e6b5c325b4e0ccb2a5c"
},
"skills/meta-mode/playbooks/hillclimb.md": {
"upstream": "pstack",
Expand All @@ -277,7 +277,7 @@
"upstream": "pstack",
"source": "skills/poteto-mode/playbooks/multi-phase-plan.md",
"sourceDigest": "2b4fbb547e5ccfe46d1279d714eb0199d28e995f06bdc4eda4afbca9221fbbe6",
"targetDigest": "ad8323944a6e16aae7cadec362bae7063141ca33dccdaff446df90d5b198711d"
"targetDigest": "f0db3db097c610ec098bc5b52632d45f2a90f5e3e78d30dfc5649b92f684aae8"
},
"skills/meta-mode/playbooks/opening-a-pr.md": {
"upstream": "pstack",
Expand Down Expand Up @@ -376,12 +376,12 @@
"upstream": "pstack",
"source": "skills/poteto-mode/SKILL.md",
"sourceDigest": "ee1848c973a112026f09ba12ea7a13c1654006e7bf170d1c34bf5d5816bc439b",
"targetDigest": "3d21e1b684a2cc0ff43f81cfc0fd9b53c703936d901a8d609f499767ab63e728"
"targetDigest": "d7ede7cea157c2d26dfc2e65b4406a98a5e60f980ca9435bd23d204a024a4a53"
},
"skills/mstack-help/SKILL.md": {
"upstream": null,
"reason": "mstack-only entry skill that routes setup and usage questions; no upstream skill covers this repository.",
"targetDigest": "425353e51cc7d98f98c855375191f2f8e6127b406ce059ef0f2fd1934ec7d5ee"
"targetDigest": "cb138f6929f09d338f61a2c1474bf77b77baf6a8bf767ee372e37484ca5079d6"
},
"skills/no-comments/SKILL.md": {
"upstream": "pstack",
Expand Down
4 changes: 2 additions & 2 deletions profiles/upstream-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"canonicalSkills": {
"architect": {
"source": "76ca68a7e061c68a9d387cb60a4c88eeca7f7aa4f472b6053e42e2ec19db6597",
"target": "76c299297a79236fa519d401716a6ad1845ecc1a3f4fdff2aa052309261651aa"
"target": "8ab2154c8f977a50ed7754d77b989ea610b2ffbc379932bc55357beed0c45fe1"
},
"arena": {
"source": "2a839e3a486228d013f5b07b65e688dfe89e4fedb2b62e291773ce89014a5185",
Expand Down Expand Up @@ -80,7 +80,7 @@
},
"meta-mode": {
"source": "02085314995c284b6da78c2ae072db36573dccdacc27de1105391856347035df",
"target": "3d21e1b684a2cc0ff43f81cfc0fd9b53c703936d901a8d609f499767ab63e728"
"target": "d7ede7cea157c2d26dfc2e65b4406a98a5e60f980ca9435bd23d204a024a4a53"
},
"principle-attack-the-premise": {
"source": "6a932884daad4aa189e9b5d1665226bbc75621d4d2a398fd4003bebd382f4599",
Expand Down
8 changes: 8 additions & 0 deletions profiles/upstreams.json
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,14 @@
{
"from": "When you're stuck, or can't tell which skill fits, type [`/poteto-help`](../../skills/poteto-help/SKILL.md) with your question:\n\n```text\n/poteto-help which skill should i use to review this branch?\n```\n\nIt answers, hands you a prompt to send, and links the skill or guide page the answer came from. It doesn't start the work, because a mstack run spends real tokens, so you send the prompt when you're ready. It runs only when you type it.\n\n",
"to": ""
},
{
"from": "- A small, finished change you're unsure about needs `/interrogate` alone.",
"to": "- A small, finished change you're unsure about needs `/blast-radius`, which proves the one fact that makes it safe. Use `/interrogate` only when you want an adversarial review."
},
{
"from": "- A contested design that's expensive to reverse gets `/architect`, then `/interrogate` before shipping.",
"to": "- A contested design that's expensive to reverse gets `/architect`, then a prototype, `/statechart`, or formal verification before shipping. Evidence settles it better than another review."
}
]
},
Expand Down
2 changes: 1 addition & 1 deletion skills/architect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Default: proceed directly to implementation with the synthesized design. No huma

Opt in to a checkpoint when the invoker explicitly asks: "/architect with checkpoint," "stop and show me before implementing," or similar. Then surface the synthesized design and pause for sign-off.

The synthesis can ship as its own commit either way, as the "scaffold first" mode of the **foundational-thinking** principle skill. Planned and scoped breakage during fill-in is fine, per the **outcome-oriented-execution** principle skill. For adversarial pressure on the design before implementing, run the **interrogate** skill on the synthesized sketch.
The synthesis can ship as its own commit either way, as the "scaffold first" mode of the **foundational-thinking** principle skill. Planned and scoped breakage during fill-in is fine, per the **outcome-oriented-execution** principle skill. To pressure-test the design before implementing, prototype the contested part or check its state invariants with the **statechart** skill. Run the **interrogate** skill on the sketch only when the invoker asks for an adversarial review.

If the human pushes back on the shape (in a checkpoint or after the fact), treat that as Phase A evidence. Re-ground and re-run Phase B before writing more code.

Expand Down
2 changes: 1 addition & 1 deletion skills/meta-mode/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Remaining triggers:
- Any code → name the data shape first, and choose its organizing structure per **principle-model-the-domain**.
- Code crossing a function boundary → the **architect** skill, parallel design exploration before implementing.
- Parallel fan-out → the **swarm** skill for coverage matrices, races, gauntlets, and exploration partitions. Use **arena** for design or code bakeoffs with base selection and grafting.
- Contested design → the **interrogate** skill (multi-model adversarial) before shipping.
- Contested design → settle it with evidence, not more review. Run the competing shapes through the Prototype playbook (`playbooks/prototype.md`), or prove the safety-critical fact with the **blast-radius** skill. For a state, protocol, or concurrency invariant, check it with the **statechart** skill or the **create-formal-verification-skill** skill. Run the **interrogate** skill only when the user asks for an adversarial review.
- Nontrivial multi-step → write the throughput checkpoint (Feature step 3).
- Any prose surface → the **unslop** skill. Your reply is a prose surface. Write it per **Writing the reply**. Agent-facing prose also follows the repository's skill-authoring guidance.
- Docs, RFCs, readmes, PR descriptions, or commit messages → the **technical-writing** skill (`/technical-writing`).
Expand Down
2 changes: 1 addition & 1 deletion skills/meta-mode/playbooks/bug-fix.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspenders that "might help" is a hypothesis, not a fix. It does not ship. When evidence refutes a hypothesis, revert what it motivated. The smallest change the evidence justifies ships, nothing more.

1. Reproduce it yourself on the matching surface via the control skill (Non-negotiables), even when a debug or instrumentation protocol says to ask the user to reproduce. Ask the user only with a stated, specific reason the control surface cannot reach the target, and only after driving it as far as it goes. If it won't reproduce directly, synthesize the trigger, tighten conditions, or instrument until it fires.
2. Binary-search the cause. Form candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. Each pass takes the split that removes the most remaining possibilities, gets runtime evidence, and eliminates one side. When program state is unclear, add instrumentation or logging and read it as the code runs. Do not guess. Drive a long or stubborn hunt with the active harness's scheduler. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect and interrogate fan-out.
2. Binary-search the cause. Form candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. Each pass takes the split that removes the most remaining possibilities, gets runtime evidence, and eliminates one side. When program state is unclear, add instrumentation or logging and read it as the code runs. Do not guess. Drive a long or stubborn hunt with the active harness's scheduler. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect fan-out.
3. Plan the fix. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using the mstack `implementer` role (default `inherit-parent`) with a specific scope.
4. Verify on the same surface. The original repro now passes. "Inconclusive" or wrong-surface is not a pass. Flag it. Unit tests show branch behavior, not bug absence.
5. Stage the commits so the failing repro lands before the fix in git history. See the **tdd** skill for the failing-test-first cadence when the bug has a cheap local test path. Skip it when the test would be expensive, integration-heavy, or unclear.
Expand Down
2 changes: 1 addition & 1 deletion skills/meta-mode/playbooks/feature.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass. Flag it.
6. Rebase into small, ordered commits. Stack follow-ups.
Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next.
7. If the design is contested, `interrogate` before shipping.
7. If the design is contested, settle it before shipping with a prototype or `blast-radius`, or with `statechart` or formal verification for a state or concurrency invariant. Use `interrogate` only when the user asks for an adversarial review.
8. Run **Opening a PR**.

Code-coupled work (one feature, one migration) goes to a single owner with the checkpoint inline. That owner fans out internally after the blocking phase. Parent-level fan-out is for slices that produce independent artifacts (audits, cross-subsystem investigations, competing experiments). Rewrite the checkpoint at phase boundaries. Spawn a fresh owner rather than chaining interrupts.
Expand Down
2 changes: 1 addition & 1 deletion skills/meta-mode/playbooks/multi-phase-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ Each live lane runs in its own configured environment at the PR head. Drive it w

## Appendix D. Links and reading list

<Docs to read before editing. Which PRs get `<mstack-skills>/how/SKILL.md` and `<mstack-skills>/interrogate/SKILL.md`. The trail per `<mstack-skills>/show-me-your-work/SKILL.md`.>
<Docs to read before editing. Which PRs get `<mstack-skills>/how/SKILL.md`, and which get a `<mstack-skills>/statechart/SKILL.md` or formal verification pass. The trail per `<mstack-skills>/show-me-your-work/SKILL.md`.>
````

**Reply:** the plan path, the PR ids with their dependencies and the review-gated set, what the prototypes proved and what stays unproven, and the check script's output.
4 changes: 2 additions & 2 deletions skills/mstack-help/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ The default answer is `meta-mode`, which runs most of the others when its steps
| Fix a bug test-first when a cheap local test exists | `tdd` |
| Get several attempts at one brief, merged into the best | `arena` |
| Fan out parallel workers for coverage, races, or exploration | `swarm` |
| Have several models review a diff and try to break it | `interrogate` |
| Have several models review a diff and try to break it, when asked for an adversarial review | `interrogate` |
| Apply strict TypeScript practices to `.ts` or `.tsx` work | `typescript-best-practices` |
| Strip comments before review | `no-comments` |
| Clean AI tells out of prose | `unslop` |
Expand All @@ -100,7 +100,7 @@ Close calls:

- `how` explains what the code does. `why` explains the reasons. `teach` runs both and explains the result plainly.
- `arena` gives every worker the same brief and merges the best parts. `swarm` splits work into slices or a race and returns one report.
- `interrogate` reviews the diff. `blast-radius` looks for breakage outside it and proves the one fact that makes the change safe.
- `interrogate` reviews the diff. `blast-radius` looks for breakage outside it and proves the one fact that makes the change safe. Prefer `blast-radius`, a prototype, or formal verification: evidence settles a contested change better than another round of review.
- `figure-it-out` designs one rigorous run. The Orchestrate playbook runs a program of many PRs. The Autonomous run playbook drives one task to a finish condition.

## Playbooks and principles
Expand Down
Loading