diff --git a/.devin-plugin/plugin.json b/.devin-plugin/plugin.json index 6a12ffa..fff2fd8 100644 --- a/.devin-plugin/plugin.json +++ b/.devin-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "pstack", - "version": "0.9.2", + "version": "0.10.0", "platforms": ["local"], "description": "Rigorous agent workflows for Devin CLI. Write less, higher quality code.", "homepage": "https://github.com/athul-ramesh/ptstack-devin", diff --git a/README.md b/README.md index e345eeb..d2af582 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,12 @@ The 0.2.0 release was verified against Devin CLI 3000.11.3 (9c803229faa4), local Avoid installing two copies with the same plugin name. Devin may source-qualify inventory names while loading skills from an older copy; verify the path returned by the skill tool. +## Using 0.10.0 + +`/pstack:why` is a short cited read of commits and PR discussion. `/pstack:how` is one read-only `subagent_explore` pass. Poteto-mode traces the code itself. Teach and poteto-help still offer both skills. Recall starts one investigator per git or `gh` source. + +`/pstack:setup-pstack` writes `# defaults: 2`. An older sheet drops the retired how and why roles. A `bug-fix` or `hillclimb` row that is still the old `pstack:poteto-agent-sonnet` default moves to `pstack:poteto-agent-opus` when `opus` is available. Any other choice stays. Profile `model:` pins are unchanged. Devin's docs do not publish the Cursor slugs `claude-fable-5-2-*`, `claude-opus-5-5-*`, or `gemini-4-carbon-*`, so those pins were not added. See the [0.15.42 port audit](docs/pstack-0.15.42-port-audit.md). + ## Using 0.9.2 Ask `/pstack:poteto-help` with a setup or workflow question. This explicit-user skill answers with one suggested prompt and a source link. It does not start a task for a help question. A request to do work follows poteto-mode instead. @@ -30,7 +36,7 @@ Invoke [`/pstack:ketchup`](skills/ketchup/SKILL.md) to catch up on this chat sin The [usage guide](docs/usage-guide.md) covers prompting, investigation, prototypes before plans, real behavior verification, benchmark evidence, repeated-mistake enforcement, and bounded in-session delivery. The help skill includes [prompting guidance](skills/poteto-help/references/prompting.md) and [copyable recipes](skills/poteto-help/references/recipes.md). -Invoke [`/pstack:sharpen`](skills/sharpen/SKILL.md) on a prompt before you send it. The agent says what a top professional would add, the raw material and methods they would use, and an outside check, then hands back the rewritten prompt with your choices left open. It does not do the task. It runs only when requested. +Invoke [`/pstack:sharpen`](skills/sharpen/SKILL.md) on a prompt before you send it. The agent says what a top professional would add, the raw material and methods they would use, and an outside check, then hands back the rewritten prompt. The rewrite asks the agent to prototype a choice an experiment can settle and recommend from what it observed. Product and preference choices stay with you. It does not do the task. It runs only when requested. Invoke [`/pstack:create-formal-verification-skill`](skills/create-formal-verification-skill/SKILL.md) when tests cannot reach the case that breaks a race, retry, state machine, parser, or unsafe code. It verifies one property with a tool that fits and runs on your machine, shows the check failing on a broken variant, and writes a project skill under `.devin/skills/` to recheck it. [`/pstack:maintain-formal-verification-skill`](skills/maintain-formal-verification-skill/SKILL.md) brings that verification back in line after the covered code changes. This plugin bundles no verifier; the agent asks before installing one. diff --git a/agents/comment-sicko/AGENT.md b/agents/comment-sicko/AGENT.md index 84508de..83f81db 100644 --- a/agents/comment-sicko/AGENT.md +++ b/agents/comment-sicko/AGENT.md @@ -27,7 +27,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. Read the surrounding code. If the rule 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. 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 the claim is not obvious there, I trace the named symbol with `read` and `grep`. I have no `exec`, so I do not claim to have read the PR. 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. diff --git a/docs/pstack-0.15.42-port-audit.md b/docs/pstack-0.15.42-port-audit.md new file mode 100644 index 0000000..a355123 --- /dev/null +++ b/docs/pstack-0.15.42-port-audit.md @@ -0,0 +1,48 @@ +# Port pstack 0.15.42 to Devin + +Audited on 2026-11-15 on top of `main` at `6e060b5`. PRs #11 (`ab1f702`, 0.8.0) and #13 (`c742dd6`, 0.9.1) are merged. Plugin version is 0.10.0. + +## Source and coverage + +Upstream range: [`c742dd6...bf0c7cd`](https://github.com/cursor/plugins/compare/c742dd61706fbacc1b95f1a20b7b988cf096ce6c...bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7) (`pstack/`, 0.15.36 to 0.15.42). The squash is [bf0c7cd](https://github.com/cursor/plugins/commit/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7) (PR #1236). `harness/pstack/claude-code` is the Claude Code mirror and was not ported. + +| Upstream change | Devin disposition | +| --- | --- | +| Sharpen's last line asks the agent to prototype a choice an experiment can settle and recommend from what it observed. Product and preference choices stay with the user. | Already present in 0.9.2. README and the usage guide now describe that line. | +| Reflect synthesizer drift example is a function rename. | Adapted. The example is `readConfig` to `loadSettings` in `config.ts`. | +| Why is one short file. Investigators, synthesizer, model routing, output format, and `references/` are deleted. | Adapted. The body is one paragraph plus a Devin line to use `exec` for git and `gh`. It names no source catalog. The reference files are deleted. | +| Recall starts its own investigator per source. | Adapted. One `pstack:panel-opus` investigator each for git history and, when `gh` is authenticated, pull requests and issues. `subagent_explore` is not used, because that profile cannot run `gh`. `run_subagent` has no readonly flag, so the brief forbids writes. | +| Blast radius and teach stop pointing at removed why parts. | Adapted. Blast radius pulls the PR with git and `gh` and cites `file:line` itself. Teach still runs how and why, and no longer asks to narrow a sweep why no longer has. | +| How is one file that starts one read-only subagent. | Adapted. The profile is the documented built-in `subagent_explore`. Explorer, explainer, and critic prompts are deleted. | +| Poteto-mode no longer routes to how. Investigation, Feature, Bug fix, Hillclimb, Perf issue, Refactoring, architect, no-comments, and comment-sicko trace the code. | Adapted in those files. Comment-sicko traces with `read` and `grep` only. Its `allowed-tools` list has no `exec`, so it does not claim to have read the PR. | +| Teach and poteto-help keep how. | Kept. Help, prompting, and the usage guide describe the shorter skills. | +| Setup drops the two why roles and the two how roles. | Adapted. `how explorer`, `how explainer`, `why investigators`, and `why synthesizer` are dropped. `how critics` is dropped with them because the one-file how has no critic panel. | +| New default models, Fable as its own family and the same vendor as Claude, Grok 4.7 no longer a default, and a `# defaults: 2` marker that migrates old defaults. | Partial. See Models below. The marker is written. An unmarked sheet migrates `bug-fix` and `hillclimb` only when the row is still exactly `pstack:poteto-agent-sonnet` and `opus` is available. Other values stay. | +| Statechart SANY error text and parent-border Mermaid arrows. | Ported onto the checker this repo already ships. The drawing and the 40-line SANY section follow the upstream tests. | +| Benny automation tweaks. | Skipped. Benny is not part of this port. | + +## Models + +Checked [Devin CLI models](https://docs.devin.ai/cli/models), [Desktop models](https://docs.devin.ai/desktop/models) (pricing text dated 2026-11-09), and [Subagents](https://docs.devin.ai/cli/subagents) on 2026-11-15. + +The CLI documents short aliases `opus`, `sonnet`, `swe`, `codex`, and `gemini`. A profile `model:` field takes an alias or an id the account allows. Desktop pricing names Claude Fable 5.2 with Low, Medium, High, XHigh, Max, and Fast Mode, and it names Gemini 4 Argon. It does not publish `claude-fable-5-2-max`, `claude-opus-5-5-xhigh`, `claude-opus-5-5-high-fast`, or `gemini-4-carbon-high`. The CLI page does not list `fable` as a short alias. Opus 5.5 is not named. + +Shipped pins stay `gpt-6-1-sol-medium` (`opus` and `codex`), `glm-5-3-flash-high` (`sonnet`), and `swe`. No new profile was added. + +Role routing that maps onto those pins: + +- Feature, refactoring, bug-fix, perf-issue, and hillclimb use `pstack:poteto-agent-opus`. Bug-fix and hillclimb used to default to `sonnet`. +- Strongest judgment stays `pstack:panel-opus`. There is no documented Fable pin to put above it. +- Swarm workers and reflect tooling stay `pstack:panel-sonnet`. Upstream moved them to `claude-opus-5-5-high-fast`. This port has no second opus pin for that speed. +- Arena runners, architect runners, and interrogate reviewers stay `opus`, `swe`, and `sonnet`. The cross-judge pool stays `opus` and `swe`, compared by `model:` pin. Upstream's vendor rule (Fable and other Claude models are one vendor) is not applied, because no shipped pin is a documented Fable id or a Claude Opus 5.5 id. +- The setup budget ladder, `inherit-parent`, and `auto` stay out. `run_subagent` takes a profile, not an effort or a speed. + +Grok 4.7 was never a default in this repo. The migration recognizes the old Devin profile rows, not a `grok-*` slug. + +## Checks + +- `node --test tests/*.test.mjs`: 56 passed. +- `git diff --check`: passes. +- `npm test --prefix skills/statechart/scripts` with TLC 1.7.4 on `TLA2TOOLS`: 373 passed, none skipped. That run includes the SANY line-and-column cases and the parent-border chart tests. + +Native Devin activation of 0.10.0 is untested. `subagent_explore` as the how profile is taken from the subagents page and has not been run in this session. diff --git a/docs/release-notes.md b/docs/release-notes.md index a68bb32..2924db1 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,5 +1,11 @@ # Release notes +## 0.10.0 + +- Port upstream 0.15.37 through 0.15.42 (`bf0c7cd`). `/pstack:why` is one short file. `/pstack:how` is one read-only `subagent_explore` pass. Poteto-mode, the code playbooks, architect, no-comments, and comment-sicko trace the code. Teach and poteto-help still offer how. Recall starts its own investigator per git or `gh` source. Reflect's drift example is a function rename. Sharpen's prototype line was already on main in 0.9.2. The docs now say so. +- Setup writes `# defaults: 2`. An older sheet drops the retired how and why roles. Old default `bug-fix` and `hillclimb` rows move from `pstack:poteto-agent-sonnet` to `pstack:poteto-agent-opus` when `opus` is available. Other choices stay. Profile pins stay `gpt-6-1-sol-medium`, `glm-5-3-flash-high`, and `swe`. Cursor slugs for Fable 5.2, Opus 5.5, and Gemini 4 Carbon are not written. Swarm workers and reflect tooling stay on `sonnet`. +- Statechart reports SANY's own error section, capped at 40 lines, and draws an outside arrow to a parent state's border. Benny is not shipped. Native activation remains untested. See the [port audit](pstack-0.15.42-port-audit.md). + ## 0.9.2 - Local drift fixes: declare `platforms: ["local"]` in `.devin-plugin/plugin.json` so the plugin loads only in Devin CLI and Devin Desktop. README and AGENTS.md say so explicitly. Restore sharpen prototype wording, obligatory `/pstack:unslop` and `/pstack:technical-writing` routing in poteto-mode, and ketchup `permissions.deny: [edit]`. Native activation remains untested. diff --git a/docs/usage-guide.md b/docs/usage-guide.md index 955c543..a6246b2 100644 --- a/docs/usage-guide.md +++ b/docs/usage-guide.md @@ -22,7 +22,7 @@ Workers and review panels spend extra tokens. Choose suitable registered profile For a noisy report, ask the agent to restate the underlying issue before sharing your theory of the cause. For an unclear cause, request evidence and hypotheses without code changes. -[`/pstack:how`](../skills/how/SKILL.md) traces mechanics. [`/pstack:why`](../skills/why/SKILL.md) finds reasons and history. [`/pstack:teach`](../skills/teach/SKILL.md) explains choices and tradeoffs in plain language. [`/pstack:recall`](../skills/recall/SKILL.md) uses this conversation, named Devin exports, and the shared record. Unavailable history stays an evidence gap. +[`/pstack:how`](../skills/how/SKILL.md) is one read-only explanation of how code works. During a change, poteto-mode traces the code itself. [`/pstack:why`](../skills/why/SKILL.md) cites the commits and PR discussion. [`/pstack:teach`](../skills/teach/SKILL.md) explains choices and tradeoffs in plain language. [`/pstack:recall`](../skills/recall/SKILL.md) uses this conversation, named Devin exports, and one investigator per git or `gh` source. Unavailable history stays an evidence gap. For a captured profile, use [Trace forensics](../skills/poteto-mode/playbooks/trace-forensics.md). For a live leak, CPU spin, or glitch, use [Runtime forensics](../skills/poteto-mode/playbooks/runtime-forensics.md). Both produce diagnosis before a fix. @@ -72,7 +72,7 @@ The help skill's [prompting reference](../skills/poteto-help/references/promptin Use `/pstack:in-your-own-words` to hear the goals and problem the agent understood. This explicit-user skill restates them without starting a workflow or adding a confirmation gate. -Use `/pstack:sharpen ` when you are unsure a prompt is aimed right. It hands back the prompt rewritten deeper, not bigger, with an outside check and your choices left open. It does not do the task. Send the rewrite yourself. +Use `/pstack:sharpen ` when you are unsure a prompt is aimed right. It hands back the prompt rewritten deeper, not bigger, with an outside check. The rewrite asks the agent to prototype a choice an experiment can settle and recommend from what it observed. Product and preference choices stay with you. It does not do the task. Send the rewrite yourself. Use `/pstack:ketchup` to catch up since your previous message. The story stays under 100 words. Every call waiting on you gets its own bullet with its link, what it changes, the evidence, the risk, and a pick, including older unresolved decisions, so a large batch makes a long reply instead of a cut list. Existing captures and available diagrams show status and before/after options. When the Devin host cannot render them, compact text includes the same facts and unknowns. The skill does not start an app, install a renderer, or post anything to produce a visual. diff --git a/skills/architect/SKILL.md b/skills/architect/SKILL.md index 4e4d9b7..402ad6f 100644 --- a/skills/architect/SKILL.md +++ b/skills/architect/SKILL.md @@ -21,7 +21,7 @@ Open a todolist with one entry per phase. ## Phase A: Ground -Build a real model of every system the new code touches. Invoke `/pstack:how` over those subsystems. Critique mode when existing structure is the constraint. Naming a file is not grounding. Produce the architectural explanation how prescribes. If the design redefines ownership or layering, also invoke `/pstack:why` so the rationale is a constraint. +Build a real model of every system the new code touches. Trace those subsystems with `read`, `grep`, and `glob`. Naming a file is not grounding. Write what the system is, how the pieces move, where they live, and the traps. If the design redefines ownership or layering, also invoke `/pstack:why` so the rationale is a constraint. Skip Phase A only for genuine greenfield work. @@ -70,7 +70,7 @@ A few edge cases do not condemn a design. When you scrap: -1. Invoke `/pstack:how` over what was built. +1. Trace what was built. 2. Redesign as if the new constraints were day-one assumptions. Read `skills/principle-redesign-from-first-principles/SKILL.md`. 3. Subtract first. Read `skills/principle-subtract-before-you-add/SKILL.md`. The new sketch starts smaller. 4. Return to Phase B. diff --git a/skills/blast-radius/SKILL.md b/skills/blast-radius/SKILL.md index 238285e..58e2c7e 100644 --- a/skills/blast-radius/SKILL.md +++ b/skills/blast-radius/SKILL.md @@ -31,10 +31,10 @@ Any safety fact you can't get to step 4, say so out loud. Don't write it up as s ## 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. Invoke `/pstack:why` when you need PR and commit evidence. +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 with `exec` git and `gh` when that record matters. 2. Find the one fact it's safe because of. Most changes that look scary 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 of the scary cases die 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 citation rules as `/pstack:why`. Cite a real `file:line`. A search that finds nothing is still an answer. 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. Never make up a caller or an API. 5. Prove the one fact. Write a script or test that runs the real code. `exec` it. Paste what happened. If you can't prove it cheaply, mark it unproven. Don't round up. 6. For a big or wide change, invoke `/pstack:arena`. Ask several profiles the same question and merge the answers. Sequential when distinct profiles are fewer than needed. Say so. diff --git a/skills/how/SKILL.md b/skills/how/SKILL.md index 5d7d5f3..96038d9 100644 --- a/skills/how/SKILL.md +++ b/skills/how/SKILL.md @@ -1,58 +1,20 @@ --- name: how -description: "Use for \"how does X work\", code walkthroughs before changing something, and placement / ownership / layering questions (\"where should this live\", \"which package owns this\", \"is this the right layer\"). Explains subsystem architecture, runtime flow, onboarding mental models. Can critique architecture. Use why for motivation." +description: "Use for how code works, a walkthrough before a change, and where a piece of code should live. One read-only explanation of the subsystem. Use why for the reasons." --- # How -Answer "how does X work?" Produce a senior onboarding explanation. A working mental model, not annotated source. +Answer "how does X work?" Hand back a mental model a senior engineer can use, not a tour of every line. -Two modes: +If the scope is ambiguous, state your interpretation and explore. The user can redirect. -1. **Explain** (default). Explore and explain. -2. **Critique.** Explain first, then independent architectural critics. +## Explain -Resolve profiles from [`../poteto-mode/references/panel-run.md`](../poteto-mode/references/panel-run.md). Record a `PanelRun` before the first `run_subagent` call. +Start one read-only `run_subagent`. Devin's `run_subagent` has no readonly flag. Use the built-in profile `subagent_explore`, which the CLI documents as read-only codebase exploration. Pass the user's question and this brief: -## Explain mode +> Explain this area to a senior engineer who has not worked in it. Read the code and describe the architecture they need before they change it. Stay read-only. Name the main flow, where the pieces live, and the traps. -### Step 1. Question and complexity +## Present -If the scope is ambiguous, state your interpretation and explore. When in doubt, lean simple. - -- **Simple.** One module, utility, or narrow question. One read-only `run_subagent` on the how-explainer profile explores and explains with [`references/explainer-prompt.md`](references/explainer-prompt.md) and no explorer findings. Then Step 4. -- **Complex.** Multiple files or services, a cross-cutting feature, or a full overview. Continue with Step 2. - -### Step 2. Explore (complex only) - -Split the question into 2-4 disjoint angles. Spawn one read-only explorer per angle on the how-explorer profile, using [`references/explorer-prompt.md`](references/explorer-prompt.md). Each returns components, flow, files read, boundaries, non-obvious facts, and open questions. - -### Step 3. Synthesize (complex only) - -After every explorer returns, give one read-only how-explainer all reports and [`references/explainer-prompt.md`](references/explainer-prompt.md). It reconciles overlap and contradictions by reading the code. - -### Step 4. Present - -Show the explainer output. Light edits for conversation context are fine. Do not rewrite it. - -### Output format - -Use the sections in [`references/explainer-prompt.md`](references/explainer-prompt.md): Overview, Key Concepts, How It Works, Where Things Live, Gotchas. Drop empty sections. - -## Critique mode - -User asked for architectural issues, problems, or improvements. - -1. Run Explain first. -2. Spawn one critic per how-critics profile. Same filled [`references/critic-prompt.md`](references/critic-prompt.md) plus [`references/critique-rubric.md`](references/critique-rubric.md), the explanation, and file paths. Sequential when `executionMode` is sequential. Say so. -3. Lead judgment. Put each finding in one bucket with its critic profile and a one-line rationale: Act on (would block a real change), Consider (real, cost unclear), Noted (valid, not actionable now), Dismissed (wrong, a nit, or missing context, with the reason). Parent owns the verdict. - -Present the explanation, then the critique. The explanation stands alone. - -## Models - -`$HOME/.config/devin/pstack-models.md` overrides these defaults. Values are profiles. - -- how explorer: `pstack:panel-sonnet` -- how explainer: `pstack:panel-opus` -- how critics: `pstack:panel-opus`, `pstack:panel-swe`, `pstack:panel-sonnet` +Present the subagent's output. Light edits for conversation context are fine. Do not rewrite it. diff --git a/skills/how/references/critic-prompt.md b/skills/how/references/critic-prompt.md deleted file mode 100644 index e17298e..0000000 --- a/skills/how/references/critic-prompt.md +++ /dev/null @@ -1,59 +0,0 @@ -# Critic Prompt Template - -Build each critic subagent's prompt from this template. Fill in the placeholders. - ---- - -You are reviewing the architecture of a codebase subsystem. An explanation of how it works has already been written. Read it to orient yourself, then read the actual code to form your own judgment. - -## Architectural Explanation - -{EXPLANATION} - -## Relevant Files - -{FILE_PATHS} - -## Critique Rubric - -{CRITIQUE_RUBRIC_CONTENTS} - -## Instructions - -Read the files listed above. Use the explanation as a map, but form your own opinions from the code itself. The explanation might miss things or frame them charitably. - -Find architectural problems, not line-level bugs or style issues. Ask whether this subsystem is built well for what it needs to do and how it will need to evolve. - -For each finding: - -1. **Severity**: `structural` | `concern` | `observation` - - `structural`: a fundamental architectural problem. Wrong abstraction boundary, broken data model, coupling that will block future work - - `concern`: a real issue that makes the system harder to work with or reason about, but not fundamentally broken - - `observation`: worth noting. A tradeoff that might not age well, a pattern inconsistent with the rest of the codebase, technical debt -2. **Finding**: the architectural issue. Be specific. Name the components, the boundary, the coupling. -3. **Evidence**: concrete code that demonstrates the problem. Don't just assert that "this is too coupled". Show the dependency chain. -4. **Impact**: what the issue costs. Harder to test? Harder to change? Performance cliff at scale? Be concrete about the consequence. - -## What to Avoid - -- Line-level code review (not your job here) -- Suggesting rewrites without demonstrating a problem with the current approach -- "This could use more abstraction" without showing what the abstraction would actually solve -- Flagging intentional tradeoffs with clear benefits as issues - -If the architecture is sound, say so. An empty critique is a valid outcome. - -## Output - -``` -## Findings - -### 1. [Severity] Short title -**Components**: Which parts of the system are involved -**Finding**: What's wrong architecturally -**Evidence**: Concrete code references -**Impact**: What this costs in practice - -### 2. [Severity] Short title -... -``` diff --git a/skills/how/references/critique-rubric.md b/skills/how/references/critique-rubric.md deleted file mode 100644 index b4d452f..0000000 --- a/skills/how/references/critique-rubric.md +++ /dev/null @@ -1,58 +0,0 @@ -# Architectural Critique Rubric - -Review through whichever of these lenses are relevant. Not every lens applies to every subsystem. - -## Abstraction Fit - -Are the abstractions pulling their weight? - -- Does each abstraction represent a real concept, or is it an indirection layer "in case we need it"? -- Are the boundaries in the right place? Do they separate things that change independently? -- Is there accidental coupling where components share implementation details they shouldn't need to know about? -- Is business logic entangled with framework wiring, or cleanly separated? - -Over-abstraction is as much a problem as under-abstraction. A flat, simple design is fine when the domain is simple. - -## Data Model - -Do the data structures fit the actual usage patterns? - -- Are the data models designed for how data is actually accessed, or for how it was conceptually modeled? -- Are there impedance mismatches, places where code constantly reshapes data because the model doesn't match the access pattern? -- Are types honest? Do they represent what data actually looks like at runtime, or claim more structure than exists? - -## Boundary Discipline - -Are system boundaries clean and well-placed? - -- Is validation concentrated at entry points, or scattered through internal code? -- Are errors handled at boundaries and propagated cleanly, or caught and re-thrown at every layer? -- Does data cross boundaries in well-typed shapes, or as bags of optional fields? -- Could this subsystem be tested in isolation, or does it require the entire system to be running? - -## Evolution Readiness - -How well will this architecture handle likely changes? - -- If the most probable next requirement landed tomorrow, how much would change? "One file" or "everything"? -- Are there hardcoded assumptions that would need to be relaxed? -- Is the design bolted-on (integrated as an afterthought) or integrated (looks like it was always part of the plan)? -- Are legacy paths preserved for compatibility that no one depends on? - -Don't penalize for not handling hypothetical changes. Focus on changes plausible given the codebase's trajectory. - -## Complexity vs. Value - -Is the complexity budget spent wisely? - -- Is complexity concentrated in the parts that need it (core logic, tricky invariants) or in accidental places (boilerplate, unnecessary indirection, configuration)? -- Are there simpler ways to achieve the same behavior? -- Does every component earn its existence, or are there vestigial pieces from an earlier design? - -## Consistency - -Does this subsystem follow the patterns established elsewhere in the codebase? - -- Are similar problems solved the same way here as elsewhere, or does this area invent its own patterns? -- If the patterns differ, is there a good reason, or did it just evolve independently? -- Inconsistency isn't automatically bad. But unexplained inconsistency is a maintenance burden. diff --git a/skills/how/references/explainer-prompt.md b/skills/how/references/explainer-prompt.md deleted file mode 100644 index dc2df79..0000000 --- a/skills/how/references/explainer-prompt.md +++ /dev/null @@ -1,55 +0,0 @@ -# Explainer Prompt Template - -Build the explainer subagent's prompt from this template. Fill in the placeholders. - ---- - -You are writing an architectural explanation for a senior engineer. Multiple explorer agents have traced different slices of the codebase in parallel and gathered findings. Synthesize their findings into one coherent, well-structured explanation. - -## Original Question - -> {QUESTION} - -## Explorer Findings - -{EXPLORER_FINDINGS_ALL} - -## Instructions - -The explorers each investigated a different angle of the same subsystem. Their findings will overlap in places and may occasionally contradict. Reconcile them. Merge overlapping descriptions, resolve contradictions by checking the code yourself, and weave the separate slices into a unified picture. - -Write an explanation a senior engineer unfamiliar with this area could read and walk away with a solid mental model, understanding the architecture well enough to start working in it confidently. - -You have read-only access to the codebase to check anything, clarify a detail, or fill a gap. Use `read`, `grep`, and `glob` as needed. The explorers did the heavy lifting, so you shouldn't need to re-explore from scratch. - -## Output Format - -Use this structure, adapted to what makes sense for the question. Not every section is needed for every question. - -### Overview -1-2 paragraphs. What is this thing, what does it do, why does it exist. Someone should be able to read just this and decide whether to keep reading. - -### Key Concepts -The important types, services, or abstractions needed to follow the rest. Brief definitions, not exhaustive. - -### How It Works -The core of the explanation, and the longest section. Walk through the flow: what triggers it, what happens step by step, where data goes, what the decision points are. - -Use prose, not pseudocode. Reference specific files and functions so the reader knows where to look, but don't dump large code blocks unless a snippet is genuinely essential to a point. - -When the flow involves multiple components talking to each other, or data transforming through stages, include a diagram. Use mermaid (```mermaid) for structured flows (sequence diagrams, flowcharts, component graphs) or ASCII art for simpler relationships where mermaid would be overkill. Use your judgment. A diagram should clarify, not decorate. If prose covers the flow, skip the diagram. - -### Where Things Live -A brief file/directory map. Just the ones someone would need to start working here. - -### Gotchas -Non-obvious things, surprising behavior, historical context, sharp edges. Skip this section if there's nothing worth calling out. - -## Communication Style - -- Use concrete language, not abstractions-about-abstractions -- Say "the `UserService` calls `AuthClient.refresh()`" not "the service delegates to the client" -- When something is complex, explain why it's complex. Don't just describe the complexity -- When something is simple, don't pad it out -- If there's a helpful analogy, use it; if there isn't, don't force one -- If the explorers flagged open questions or gaps, acknowledge them honestly rather than papering over them diff --git a/skills/how/references/explorer-prompt.md b/skills/how/references/explorer-prompt.md deleted file mode 100644 index 64cc1c4..0000000 --- a/skills/how/references/explorer-prompt.md +++ /dev/null @@ -1,52 +0,0 @@ -# Explorer Prompt Template - -Build each explorer subagent's prompt from this template. Fill in the placeholders. - ---- - -You are exploring a codebase to understand how something works. Gather facts: trace code paths, read implementations, map components. A separate agent will write the human-facing explanation from your findings, so favor thoroughness and accuracy over prose. - -Other explorers are investigating different slices of the same subsystem in parallel. Don't try to cover everything. Focus on your assigned angle and go deep. - -## Question - -> {QUESTION} - -## Your Exploration Angle - -{EXPLORATION_ANGLE} - -## Exploration Instructions - -Start by finding the relevant code. Use `glob` to find directories and files, `grep` to find key symbols, `read` to understand the actual implementation. Don't guess from names. Read the code. - -Follow this pattern: -1. **Find the entry point.** What triggers this behavior? A user action, an API call, a scheduled job? Find where it starts. -2. **Trace the flow.** Follow the call chain from the entry point. Read each function. Understand what data flows through and how it transforms. -3. **Map the key abstractions.** What types, interfaces, services, or classes are central? Read their definitions. Understand what they represent and why they exist. -4. **Find the boundaries.** Where does this subsystem interface with others? What goes in, what comes out? -5. **Look for the non-obvious.** Anything surprising? Anything that looks like a historical artifact? Anything a newcomer would misunderstand? - -Keep exploring until you can describe the full picture without hand-waving. If you hit a part you can't trace, say so explicitly. "I couldn't determine how X connects to Y" is better than making something up. - -## Output - -Return your findings in this structure. Be factual and specific. Reference exact file paths, function names, type names, and line numbers where relevant. - -### Components Found -The key types, services, classes, and abstractions. For each: name, file path, and a one-sentence description of what it does. - -### Flow -The execution flow step by step. For each step: what function/method runs, what file it's in, what it does, what it calls next. Include the data that flows between steps. - -### Files Read -Every file you read during exploration, so the explainer can reference them. - -### Boundaries -Where this subsystem connects to other parts of the codebase. The inputs and outputs. - -### Non-Obvious Things -Anything surprising, historically motivated, or easy to get wrong. Things that look like they should work one way but actually work another. - -### Open Questions -Anything you couldn't fully trace or understand. Be honest about gaps. diff --git a/skills/no-comments/SKILL.md b/skills/no-comments/SKILL.md index 5d4f2eb..42504a4 100644 --- a/skills/no-comments/SKILL.md +++ b/skills/no-comments/SKILL.md @@ -16,7 +16,7 @@ Use the caller's files or diff. Otherwise use the current diff against the base ## Steps 1. Call `run_subagent` with profile `pstack:comment-sicko`. Pass the scope. Do not restate its rules. -2. Inspect its report. 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, read the named symbol with `read` and `grep`. Do not invoke `/pstack:how` or `/pstack:why`. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report. +2. Inspect its report. 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 the named symbol with `read` and `grep`, and invoke `/pstack:why` when the history is the question. Do not invoke `/pstack:how`. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report. 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, sketch types in this session and stop at the sketch. Do not invoke `/pstack:architect`. 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. Read `skills/principle-fix-root-causes/SKILL.md` and `skills/principle-redesign-from-first-principles/SKILL.md` for intent only. Neither authorizes widening the fence nor fixing instances outside it. 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. diff --git a/skills/poteto-help/SKILL.md b/skills/poteto-help/SKILL.md index 634883f..070ed4d 100644 --- a/skills/poteto-help/SKILL.md +++ b/skills/poteto-help/SKILL.md @@ -96,7 +96,7 @@ If a skill directory next to this one is missing from the table, read its frontm Close calls: -- `/pstack:how` explains what the code does. `/pstack:why` explains the reasons. `/pstack:teach` runs one or both and explains the result plainly. +- `/pstack:how` explains what the code does, in one read-only pass. `/pstack:why` cites the commits and the PR discussion. `/pstack:teach` runs one or both and explains the result plainly. - `/pstack:arena` gives every worker the same brief and merges the best parts. `/pstack:swarm` splits work into slices or a race and returns one report. - `/pstack:architect` implements right after it settles the design. Add "with checkpoint" to review the design before it writes code. - `/pstack:interrogate` reviews the diff. `/pstack:blast-radius` looks for breakage outside the diff and proves the one fact that makes the change safe. diff --git a/skills/poteto-help/references/prompting.md b/skills/poteto-help/references/prompting.md index 05ceed0..e8edc42 100644 --- a/skills/poteto-help/references/prompting.md +++ b/skills/poteto-help/references/prompting.md @@ -20,7 +20,7 @@ A prompt states the intent and the check for done. The playbook supplies the ste - For a noisy report, ask the agent to restate the underlying issue in its own words and in plain English before it does anything else. A misreading shows up before any code exists. - In a fresh chat, `/pstack:recall` earlier work on the topic. Use this conversation, user-named Devin exports, and live git or gh state. Unavailable history stays an evidence gap. -- Before a change to unfamiliar code, ask `/pstack:how` for the mechanics and `/pstack:why` for the reasons. An agent with no traced model fixes the symptom at the first plausible spot. +- Before a change to unfamiliar code, ask the agent to trace the code. Ask `/pstack:how` when you want that trace as its own explanation, and `/pstack:why` for the reasons in the commits and PRs. An agent with no traced model fixes the symptom at the first plausible spot. - Ask `/pstack:teach` to make the case for a choice, as in "convince me it fixes the cause and not the symptom". A case is easier to check than a summary. ## Design before the plan diff --git a/skills/poteto-mode/SKILL.md b/skills/poteto-mode/SKILL.md index 4177a43..2475f64 100644 --- a/skills/poteto-mode/SKILL.md +++ b/skills/poteto-mode/SKILL.md @@ -23,9 +23,9 @@ In your first message on a task, tell the user in your own words their goal, the ## Routing gates -Invoke the named companion skill before the work proceeds. Scale `how` to the question. A narrow module or function uses one readonly explainer. A subsystem spanning files or services uses two to four explorers followed by synthesis. Do not force fan-out on trivial work. +Invoke the named companion skill before the work proceeds. Do not force fan-out on trivial work. -- Nontrivial change, architecture decision, or a request that challenges confidence: invoke `/pstack:how` over the affected subsystem. +- Mechanics of code you have not traced: trace it with `read`, `grep`, and `glob`. Do not route that trace through `/pstack:how`. - A change crossing a function boundary, including within one module: invoke `/pstack:architect` before code. It grounds the design and compares at least two structurally distinct candidates before synthesis. - Motivation, rationale, tradeoffs, regressions, postmortems, data-backed thresholds, or a change that redefines ownership or layering: invoke `/pstack:why`. Do not require it for every task. - Parallel fan-out over independent partitions: `/pstack:swarm`. Competing design or code attempts: `/pstack:arena`. A contested design before shipping: `/pstack:interrogate`. @@ -131,12 +131,14 @@ Read `$HOME/.config/devin/pstack-models.md` when it exists. Its exact role row o Implementation uses dedicated profiles. Resolve legacy `pstack:panel-` rows to `pstack:poteto-agent-` only after verifying registration and equal `model:` frontmatter pins, as specified in Root-owned delegation. This mapping is not a failure fallback. Preserve explicit implementation-profile rows. - feature, refactoring: `pstack:poteto-agent-opus` -- bug-fix: `pstack:poteto-agent-sonnet` +- bug-fix: `pstack:poteto-agent-opus` - perf-issue: `pstack:poteto-agent-opus` -- hillclimb: `pstack:poteto-agent-sonnet` +- hillclimb: `pstack:poteto-agent-opus` - judgment and prose: `pstack:panel-opus` - strongest judgment: `pstack:panel-opus` +A sheet without a `# defaults: 2` line is an older setup. Honor its lines for this session and tell the user once to rerun `/pstack:setup-pstack`. Do not remap a profile at dispatch time. + Devin dispatch has no per-call reasoning-level or speed parameter, because `run_subagent` takes a profile, not a model. Upstream pstack's per-spawn effort and fast-mode tuning therefore does not apply. Match the model to the job only by choosing among the configured role rows above, never by inventing a profile, editing a pin, or remapping a role at dispatch time. When an active panel skill requires N perspectives but fewer distinct profiles are available, use N sequential fresh-context `run_subagent` calls on the available registered profiles. One pass is not a panel. Do not claim a model ran without dispatch evidence. diff --git a/skills/poteto-mode/playbooks/bug-fix.md b/skills/poteto-mode/playbooks/bug-fix.md index fd159f6..bccdec3 100644 --- a/skills/poteto-mode/playbooks/bug-fix.md +++ b/skills/poteto-mode/playbooks/bug-fix.md @@ -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. Drive CLIs and TUIs with `exec`. Drive a web UI only with the browser mechanism Devin actually exposes. Do not hand the repro to the user. 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. A bug you cannot reproduce, you cannot prove fixed. -2. Binary-search the cause. Form candidate hypotheses, then rule them out until one survives. Seed them by invoking `/pstack:how` over the affected subsystem and `/pstack:why` for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Confirm the surviving mechanism with runtime evidence before planning the fix. +2. Binary-search the cause. Form candidate hypotheses, then rule them out until one survives. Seed them by tracing the affected subsystem and invoking `/pstack:why` for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Confirm the surviving mechanism with runtime evidence before planning the fix. 3. Plan the fix. If it crosses a function boundary, invoke `/pstack:architect` for parallel design exploration first, and record `architect skipped: ` when the change is local. Delegate implementation through [`../references/delegation.md`](../references/delegation.md) with the exact role key `bug-fix`. Review the diff. 4. Verify on the same surface. Detect the control tool that surface needs before claiming evidence; a missing tool is a precise limitation, not a pass. 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. The diff tells the story. Write a failing local test first when the bug has a cheap local test path. Skip that cadence when the test would be expensive, integration-heavy, or unclear. diff --git a/skills/poteto-mode/playbooks/feature.md b/skills/poteto-mode/playbooks/feature.md index 9a3b3c7..30e56ae 100644 --- a/skills/poteto-mode/playbooks/feature.md +++ b/skills/poteto-mode/playbooks/feature.md @@ -2,7 +2,7 @@ **You own the design. Plan, review, verify.** Delegate implementation. Stay in the lead. -1. Invoke `/pstack:how` over the affected subsystem before changing it. Scale it as the how skill prescribes: one readonly explainer for a narrow module or function, explorers plus synthesis when the subsystem spans files or services. Inspect with `read`, `grep`, and `glob` as needed. +1. Trace the affected subsystem with `read`, `grep`, and `glob` before changing it. 2. Invoke `/pstack:architect` before code that crosses a function boundary, including within one module. It grounds the design and compares at least two structurally distinct candidates before synthesis. Skipping stays as `architect skipped: `. Do not fold the design decision silently into implementation. 3. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: ` rather than being dropped: - **Blocking first steps.** Gates run before fan-out. diff --git a/skills/poteto-mode/playbooks/hillclimb.md b/skills/poteto-mode/playbooks/hillclimb.md index b4cd385..70f1e03 100644 --- a/skills/poteto-mode/playbooks/hillclimb.md +++ b/skills/poteto-mode/playbooks/hillclimb.md @@ -4,7 +4,7 @@ Core discipline: one change, one measurement, keep or revert. Never stack untested changes, and never claim a win from code inspection. The data decides (`skills/principle-prove-it-works/SKILL.md`). -1. Ground the workload and architecture before choosing the ruler. Run `/pstack:how` over the target, name the realistic workload dimensions that can move the result (data size, history, state, concurrency), and select a case that reproduces the user's complaint. If no case reproduces it, fix the repro instead of hillclimbing. Then fix one metric, the direction that counts as better, and a checkable stop predicate that pairs a target with a floor on attempts so a lucky early win can't end the run (the example "at least 50% better than baseline and at least 10 iterations" is this shape). Use the user's numbers when given, otherwise agree them. +1. Ground the workload and architecture before choosing the ruler. Trace the target, name the realistic workload dimensions that can move the result (data size, history, state, concurrency), and select a case that reproduces the user's complaint. If no case reproduces it, fix the repro instead of hillclimbing. Then fix one metric, the direction that counts as better, and a checkable stop predicate that pairs a target with a floor on attempts so a lucky early win can't end the run (the example "at least 50% better than baseline and at least 10 iterations" is this shape). Use the user's numbers when given, otherwise agree them. 2. Build the measurement harness, prove its sensitivity, read `skills/benchmark-checklist/SKILL.md` from the installed plugin root and apply its procedure, then freeze it (`skills/principle-build-the-lever/SKILL.md`). Run contrasting realistic workloads and confirm the target case reproduces the symptom while easier cases separate as expected. If the ruler cannot distinguish them, revise the workload or metric. The frozen harness reports error and completed-work counts. A missing or invalid count prevents a claimed win. Once frozen, one repeatable command emits the metric, sampled enough to clear the noise (median of N, not a single run). Changing it invalidates every earlier number. Record the baseline metric and a green run of the regression gate (the tests that must keep passing) before any change. 3. Open the decision log via `/pstack:show-me-your-work`. Also keep a `decision.tsv` for this run, one row per attempt. Columns are id, hypothesis, change, before, after, delta, tests, verdict (kept or reverted), note. This is the run's memory. Read it before each attempt so the search accumulates instead of circling. Keep it out of the tree so it survives reverts. 4. Borrow the strategy order from [Perf issue](perf-issue.md): avoid work, avoid repeating it, do less, defer it, move it off the interactive path, run concurrently, then make it cheaper. Preserve this hillclimb's target, attempt floor, regression gates, and session bounds. Ground each hypothesis in the architecture model from step 1, so it names a specific mechanism ("defer X off the boot path because it blocks first paint"), not "try memoizing something". diff --git a/skills/poteto-mode/playbooks/investigation.md b/skills/poteto-mode/playbooks/investigation.md index f20d28b..1fb7cef 100644 --- a/skills/poteto-mode/playbooks/investigation.md +++ b/skills/poteto-mode/playbooks/investigation.md @@ -4,7 +4,7 @@ Read-only requests. "How does X work?", "why was Y built this way?", "are we sure about Z?", "should we do X or Y?". They produce a cited explanation or a recommendation, not a code change. -1. Inspect the affected files with `read`, `grep`, and `glob`. For "how does X work?" invoke `/pstack:how`. For motivation, rationale, regressions, postmortems, or data-backed thresholds invoke `/pstack:why`. For "are we sure?", critique. For a narrow question with no sibling skill, explain here. Cite history you can actually read. +1. Trace the code the question is about with `read`, `grep`, and `glob`. For motivation, rationale, regressions, postmortems, or data-backed thresholds invoke `/pstack:why`. For a challenge to the current structure, say what is wrong and why. For a narrow question, explain it here. Cite history you can actually read. 2. Throughput checkpoint stays one line. `throughput checkpoint: n/a, read-only investigation`. The four-item version is for code-shaped work. 3. Produce an Overview, Key Concepts, How It Works, Where Things Live, and Gotchas answer, or a recommendation with a tradeoffs table if the request is a decision between alternatives. 4. Write the reply per poteto-mode Writing the reply. diff --git a/skills/poteto-mode/playbooks/perf-issue.md b/skills/poteto-mode/playbooks/perf-issue.md index 383a4b3..d331ce8 100644 --- a/skills/poteto-mode/playbooks/perf-issue.md +++ b/skills/poteto-mode/playbooks/perf-issue.md @@ -3,7 +3,7 @@ **You own the measurement story. Plan, review, verify the numbers.** Tie every fix to a measurement. Do not read source instead of measuring. 1. Capture a baseline on the matching surface. Drive CLIs and TUIs with `exec`. Drive a web UI only with the browser mechanism Devin actually exposes. -2. Ground hypotheses by reading the hot path. Do not claim a perf ceiling without running it first. +2. Trace the hot path to ground hypotheses. Do not claim a perf ceiling without running it first. Read `skills/benchmark-checklist/SKILL.md` from the installed plugin root and apply it to the baseline and every subsequent performance claim. Its user-only trigger means the model skill tool cannot invoke it; workflow-directed reading supplies the procedure. Consider strategies in this order, grounded in the measured limiter. Stop when an earlier strategy meets the target. 1. Avoid work. Delete unnecessary computation. 2. Avoid repeating it. Reuse results with explicit invalidation. diff --git a/skills/poteto-mode/playbooks/refactoring.md b/skills/poteto-mode/playbooks/refactoring.md index 7ad4fee..289b9f5 100644 --- a/skills/poteto-mode/playbooks/refactoring.md +++ b/skills/poteto-mode/playbooks/refactoring.md @@ -4,7 +4,7 @@ A refactor that smuggles in a behavior change loses its safety net. If the cleanup reveals a missing feature or a real bug, split it out and ship the structural change first against the pinned contract. A redesign is allowed, but name it and route to Feature. -1. Pin the behavior contract first. Invoke `/pstack:how` over the affected subsystem to learn the contract, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. The harness makes "refactor" a checkable claim (`skills/principle-prove-it-works/SKILL.md`). If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin. +1. Pin the behavior contract first. Trace the affected subsystem to learn the contract, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. The harness makes "refactor" a checkable claim (`skills/principle-prove-it-works/SKILL.md`). If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin. 2. Name the structure the code is missing per `skills/principle-model-the-domain/SKILL.md`. Boring code stays when the shape is already clear and local. The reshape must delete branches or invalid states, not add indirection. 3. Name the target shape. State what the module layout, types, and call graph should be if built today. If the target crosses a function boundary, invoke `/pstack:architect` for parallel design exploration of the shape before the move. 4. Subtract before you add. Delete dead weight, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape. The smallest change that reaches the target shape ships. A speculative cleanup that "might help" gets reverted. diff --git a/skills/poteto-mode/references/evidence-source.md b/skills/poteto-mode/references/evidence-source.md index 64c4472..3982d73 100644 --- a/skills/poteto-mode/references/evidence-source.md +++ b/skills/poteto-mode/references/evidence-source.md @@ -34,7 +34,7 @@ A `ProgramState` store is a first-class resume source. Read `/.pstack/` has 175 tokens at limit 80" - "Bugbot flagged regex backtracking on May 2" -- "we renamed the encoder helper in `encodingForModel`" +- "we renamed `readConfig` to `loadSettings` in `config.ts`" Keep (durable patterns): - "closed regex enums for trigger detection are brittle; prefer schema-validated structures" diff --git a/skills/setup-pstack/SKILL.md b/skills/setup-pstack/SKILL.md index 9216f27..816a727 100644 --- a/skills/setup-pstack/SKILL.md +++ b/skills/setup-pstack/SKILL.md @@ -11,17 +11,21 @@ Do not write `~/.claude/` or any host path this plugin does not own. ## Default routing policy -`opus` is the strongest configured model, `sonnet` is the medium-capability model for bounded work, and `swe` supplies an alternate model perspective. These labels do not select model families or reasoning levels; configure profile pins separately. +`opus` is the strongest configured pin. Feature, refactoring, bug-fix, perf-issue, and hillclimb all use it. Judgment, prose, and strongest judgment use the `opus` review profile. `sonnet` stays the faster pin for swarm workers and reflect tooling. `swe` supplies an alternate perspective. These labels do not select a Cursor slug or a reasoning level. -Keep broad features/refactoring, performance diagnosis, synthesis, prose, and final judgment on `opus`. Use `sonnet` for scoped bug fixes, measurable hillclimbing, exploration, evidence gathering, tooling review, and swarm slices. Scope those briefs tightly; select `opus` explicitly when the work requires broad design or difficult diagnosis. Panels retain all three perspectives; the arena cross-judge pool uses `opus` and `swe`. Arena runs one judge and tries only pool entries whose pin differs from the parent's model, in list order, so order the pool by preference. +Devin documents the family aliases `opus`, `sonnet`, `swe`, `codex`, and `gemini` ([Models](https://docs.devin.ai/cli/models)). A custom profile's `model:` field takes an alias or a model id the account allows ([Subagents](https://docs.devin.ai/cli/subagents)). Desktop pricing names Claude Fable 5.2, with Low through Max and Fast Mode, and Gemini 4 Argon. It does not publish `claude-fable-5-2-max`, `claude-opus-5-5-xhigh`, `claude-opus-5-5-high-fast`, or `gemini-4-carbon-high`, and the CLI page does not list `fable` as a short alias. This setup does not write those slugs. Shipped pins stay `gpt-6-1-sol-medium`, `glm-5-3-flash-high`, and `swe`. -Keep paired `panel-*` and `poteto-agent-*` model pins equal. Setup writes role routing only; it does not change those pins or the main session model. +Panels keep three profiles. The arena cross-judge pool stays `opus` and `swe`. Arena runs one judge and tries only pool entries whose pin differs from the parent's model, in list order, so order the pool by preference. Fable and other Claude models are one vendor in upstream arena. No shipped pin is a documented Fable id or a Claude Opus 5.5 id, so this port still compares pins. + +Keep paired `panel-*` and `poteto-agent-*` model pins equal. Setup writes role routing only. It does not change those pins, the main session model, or a reasoning budget. + +A sheet without the line `# defaults: 2` is from an older setup. The writer drops retired roles (`how explorer`, `how explainer`, `how critics`, `why investigators`, `why synthesizer`). Where `bug-fix` or `hillclimb` is still exactly `pstack:poteto-agent-sonnet` and `opus` is in `devin models list`, that row becomes `pstack:poteto-agent-opus`. Every other value stays, including a `sonnet` row the user chose on any other role. The script prints each replacement and each dropped role on stderr. A sheet that already has the marker is left alone. Tell the user which rows moved. ## Steps 1. Run `devin models list` with `exec`. Keep every alias from lines that start with `aliases:`. Never write a family slug or an identifier that command did not print. 2. Resolve PluginRoot from the Source line of `devin plugins info pstack`. -3. Pipe that models list into `node "$PluginRoot/skills/setup-pstack/write-models.mjs" --home "$HOME"`. Do not export a different `HOME` for that command. Auth stays in the process environment. `--home` is only the output root. The script maps implementation roles to registered `poteto-agent` profiles and review roles to registered panel profiles, reads an existing sheet first, preserves valid role lists and their order plus operator notes, fills missing roles from current defaults, keeps panel list length, and replaces the file atomically. Default rows use the first available core alias when their preferred alias is absent; existing configured rows are never silently substituted. -4. Apply only explicitly requested changes with repeatable `--role "=[,...]"` arguments, for example `--role "how critics=pstack:panel-codex,pstack:panel-codex"`. Validate requested aliases against step 1. The script validates known roles, registered profiles, review/implementation compatibility, and same-pin implementation counterparts for legacy panel entries in implementation roles. Duplicate or invalid role rows and unknown profile-shaped role rows are errors: leave the sheet unchanged and report the exact correction needed. Preserve unknown prose and notes; never discard an unknown role row automatically. Use Markdown headings or ordinary prose for notes, outside role configuration rows. +3. Pipe that models list into `node "$PluginRoot/skills/setup-pstack/write-models.mjs" --home "$HOME"`. Do not export a different `HOME` for that command. Auth stays in the process environment. `--home` is only the output root. The script maps implementation roles to registered `poteto-agent` profiles and review roles to registered panel profiles, reads an existing sheet first, preserves valid role lists and their order plus operator notes, fills missing roles from current defaults, keeps panel list length, writes `# defaults: 2`, applies the migration in Default routing policy, and replaces the file atomically. Default rows use the first available core alias when their preferred alias is absent. A configured row changes only under that migration, or under an explicit `--role` override. +4. Apply only explicitly requested changes with repeatable `--role "=[,...]"` arguments, for example `--role "arena runners=pstack:panel-codex,pstack:panel-codex"`. Validate requested aliases against step 1. The script validates known roles, registered profiles, review/implementation compatibility, and same-pin implementation counterparts for legacy panel entries in implementation roles. Duplicate or invalid role rows and unknown profile-shaped role rows are errors: leave the sheet unchanged and report the exact correction needed. Preserve unknown prose and notes. Drop only the retired roles named above. Use Markdown headings or ordinary prose for notes, outside role configuration rows. 5. Read the written file. Confirm every profile suffix is an alias from step 1 and every configured choice and note survived. Repeated profiles remain separate fresh-context perspectives, in their configured order. Confirm the single-model fallback paragraph is present. 6. Tell the user the path and to start a new session so profile registration and the sheet both load. Re-running this skill must produce an identical file when inputs and explicit overrides have not changed. Keep the existing registered profile pins; do not add `auto`, `inherit-parent`, reasoning-budget rewriting, or automatic model substitution. diff --git a/skills/setup-pstack/write-models.mjs b/skills/setup-pstack/write-models.mjs index 0d74edf..1622972 100755 --- a/skills/setup-pstack/write-models.mjs +++ b/skills/setup-pstack/write-models.mjs @@ -9,28 +9,45 @@ export const CORE_ALIASES = Object.freeze(["opus", "swe", "sonnet", "codex"]); export const SINGLE_ROLES = Object.freeze([ ["feature, refactoring", "opus"], - ["bug-fix", "sonnet"], + ["bug-fix", "opus"], ["perf-issue", "opus"], - ["hillclimb", "sonnet"], + ["hillclimb", "opus"], ["judgment and prose", "opus"], ["strongest judgment", "opus"], - ["how explorer", "sonnet"], - ["how explainer", "opus"], - ["why investigators", "sonnet"], - ["why synthesizer", "opus"], ["reflect tooling", "sonnet"], ["reflect judgment, divergent, synthesizer", "opus"], ["swarm workers", "sonnet"], ]); export const PANEL_ROLES = Object.freeze([ - ["how critics", ["opus", "swe", "sonnet"]], ["arena runners", ["opus", "swe", "sonnet"]], ["arena cross-judge pool", ["opus", "swe"]], ["architect runners", ["opus", "swe", "sonnet"]], ["interrogate reviewers", ["opus", "swe", "sonnet"]], ]); +export const DEFAULTS_MARKER = "# defaults: 2"; + +export const RETIRED_ROLES = Object.freeze([ + "how explorer", + "how explainer", + "how critics", + "why investigators", + "why synthesizer", +]); + +const RETIRED = new Set(RETIRED_ROLES); + +const PREVIOUS_DEFAULTS = new Map([ + ["bug-fix", ["pstack:poteto-agent-sonnet"]], + ["hillclimb", ["pstack:poteto-agent-sonnet"]], +]); + +const MIGRATION_ALIAS = new Map([ + ["bug-fix", "opus"], + ["hillclimb", "opus"], +]); + const IMPLEMENTATION_ROLES = new Set([ "feature, refactoring", "bug-fix", @@ -110,6 +127,8 @@ export function renderSheet(roles) { "When a role needs more perspectives than distinct profiles, run that many sequential fresh-context", "`run_subagent` calls on the available profile. Do not label one pass as a panel.", "", + DEFAULTS_MARKER, + "", ]; for (const row of roles) { lines.push(`${row.role}: ${row.profiles.join(", ")}`); @@ -154,6 +173,7 @@ export function parseExistingSheet(content, available) { const match = lines[index].match(/^([^#`]+?):\s*(.*)$/); if (!match) continue; const role = match[1].trim(); + if (RETIRED.has(role)) continue; if (!KNOWN_ROLES.has(role) && !match[2].includes("pstack:")) continue; if (rows.has(role)) throw new Error(`line ${index + 1}: duplicate role ${role}`); const profiles = match[2].split(",").map((profile) => profile.trim()); @@ -161,7 +181,30 @@ export function parseExistingSheet(content, available) { catch (error) { throw new Error(`line ${index + 1}: ${error.message}`); } rows.set(role, { role, profiles, requiredPerspectives: profiles.length, line: index }); } - return { rows, lines }; + const hasMarker = lines.some((line) => line.trim() === DEFAULTS_MARKER); + return { rows, lines, hasMarker }; +} + +function sameProfiles(left, right) { + return left.length === right.length && left.every((profile, index) => profile === right[index]); +} + +function dropRetired(lines) { + return lines.filter((line) => { + const match = line.match(/^([^#`][^:]*):/); + return !(match && RETIRED.has(match[1].trim())); + }); +} + +function ensureMarker(lines) { + if (lines.some((line) => line.trim() === DEFAULTS_MARKER)) return lines; + const at = lines.findIndex((line) => { + const match = line.match(/^([^#`][^:]*):/); + return Boolean(match && KNOWN_ROLES.has(match[1].trim())); + }); + const next = lines.slice(); + next.splice(at === -1 ? next.length : at, 0, DEFAULTS_MARKER); + return next; } export function defaultOutPath(home = process.env.HOME) { @@ -219,6 +262,26 @@ export function writeFromModelsList(text, options = {}) { const path = options.out ?? defaultOutPath(options.home); const existing = existsSync(path) ? readFileSync(path, "utf8") : undefined; const parsed = parseExistingSheet(existing ?? renderSheet(defaults), available); + const migrations = []; + const dropped = []; + if (existing) { + for (const line of existing.split("\n")) { + const match = line.match(/^([^#`][^:]*):\s*/); + if (match && RETIRED.has(match[1].trim())) dropped.push(match[1].trim()); + } + } + if (!parsed.hasMarker) { + for (const [role, previous] of PREVIOUS_DEFAULTS) { + const row = parsed.rows.get(role); + const alias = MIGRATION_ALIAS.get(role); + if (!row || !alias || !available.has(alias) || !sameProfiles(row.profiles, previous)) continue; + const next = defaults.find((item) => item.role === role); + row.profiles = next.profiles.slice(); + row.requiredPerspectives = next.profiles.length; + parsed.lines[row.line] = `${role}: ${next.profiles.join(", ")}`; + migrations.push(`${role}: ${previous.join(", ")} -> ${next.profiles.join(", ")}`); + } + } const overrides = new Map(); for (const override of options.roles ?? []) { const equals = override.indexOf("="); @@ -244,8 +307,12 @@ export function writeFromModelsList(text, options = {}) { } let content = parsed.lines.join("\n"); if (additions.length) content = `${content}${content.endsWith("\n") ? "" : "\n"}${additions.join("\n")}\n`; + content = `${ensureMarker(dropRetired(content.split("\n"))).join("\n")}`; + if (!content.endsWith("\n")) content = `${content}\n`; + for (const line of migrations) console.error(`migrated ${line}`); + for (const role of dropped) console.error(`dropped ${role}`); writeAtomic(path, content); - return { path, content, roles, available: [...available].sort() }; + return { path, content, roles, available: [...available].sort(), migrations, dropped }; } if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { diff --git a/skills/statechart/scripts/backends/mermaid.ts b/skills/statechart/scripts/backends/mermaid.ts index 327220c..d792305 100644 --- a/skills/statechart/scripts/backends/mermaid.ts +++ b/skills/statechart/scripts/backends/mermaid.ts @@ -93,6 +93,52 @@ const esc = (s: string, quoted = false) => { const or = (names: Iterable) => [...names].sort(byText).join(" or "); +type Edge = { from: string[]; start: boolean; to: string[]; label: string | undefined }; + +const within = (parent: string[], path: string[]) => + path.length >= parent.length && parent.every((part, index) => path[index] === part); +const wayIn = (edge: Edge) => tupleKey([edge.start, edge.from]); + +export function drawnEdges(region: Region): Edge[] { + let out: Edge[] = []; + for (const state of region.states) + if (state.start) out.push({ from: [], start: true, to: state.path, label: undefined }); + for (const step of region.steps) + out.push({ + from: step.from, + start: false, + to: step.to, + label: step.label + (step.when ? ` [${step.when}]` : ""), + }); + const parents = new Map(); + for (const state of region.states) + for (let index = 1; index < state.path.length; index++) { + const prefix = state.path.slice(0, index); + parents.set(tupleKey(prefix), prefix); + } + for (const parent of [...parents.values()].sort((left, right) => left.length - right.length)) { + const into = out.filter( + (edge) => edge.to.length > parent.length && within(parent, edge.to) && !within(parent, edge.from), + ); + if (!into.length || into.some((edge) => wayIn(edge) !== wayIn(into[0]))) continue; + const one = into.length === 1; + const at = out.indexOf(into[0]); + out = out.filter((edge) => !into.includes(edge)); + out.splice( + at, + 0, + { ...into[0], to: parent, label: one ? into[0].label : undefined }, + ...into.map((edge) => ({ + from: parent, + start: true, + to: edge.to, + label: one ? undefined : edge.label, + })), + ); + } + return out; +} + const MARK_STYLES = { breaks: "fill:#ffecee,stroke:#e72e3b,stroke-width:2.5px,color:#cd2834", mayBreak: "fill:#fff3e6,stroke:#e8730c,stroke-width:2.5px,color:#b85a06", @@ -121,6 +167,9 @@ export function mermaidLines(chart: Chart) { if (s === undefined) known.set(path, (s = id(path))); return s; }; + const drawn = drawnEdges(r); + const line = (edge: Edge, indent: string) => + `${indent}${edge.start ? "[*]" : idOf(edge.from)} --> ${idOf(edge.to)}${edge.label === undefined ? "" : `: ${esc(edge.label)}`}`; const tree = (prefix: string[], indent: string, below: ChartState[]) => { const heads = new Map(); for (const s of below) append(heads, s.path[prefix.length], s); @@ -134,6 +183,9 @@ export function mermaidLines(chart: Chart) { if (inner.length) { out.push(`${indent}state "${esc(head, true)}" as ${id(path)} {`); tree(path, indent + " ", inner); + const key = tupleKey(path); + for (const edge of drawn) + if (edge.start && tupleKey(edge.from) === key) out.push(line(edge, `${indent} `)); out.push(`${indent}}`); } else if (leaf) { const sid = idOf(leaf.path); @@ -153,11 +205,7 @@ export function mermaidLines(chart: Chart) { } }; tree([], " ", r.states); - for (const s of r.states) if (s.start) out.push(` [*] --> ${idOf(s.path)}`); - for (const s of r.steps) - out.push( - ` ${idOf(s.from)} --> ${idOf(s.to)}: ${esc(s.label + (s.when ? ` [${s.when}]` : ""))}`, - ); + for (const edge of drawn) if (!edge.start || !edge.from.length) out.push(line(edge, " ")); return out; }; let body: string[]; diff --git a/skills/statechart/scripts/run.ts b/skills/statechart/scripts/run.ts index 4efd368..017684f 100644 --- a/skills/statechart/scripts/run.ts +++ b/skills/statechart/scripts/run.ts @@ -68,6 +68,7 @@ const TLC_TOOL = "http:tla2tools[url=https://github.com/tlaplus/tlaplus/releases/download/v1.7.4/tla2tools.jar,checksum=sha256:936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88]@1.7.4"; const JAVA_TOOL = "java@temurin-25"; export const PINNED_FLAGS = ["-workers", "1", "-fp", "0", "-lncheck", "final"]; +const SANY_ERRORS = /^\*\*\* ?(?:Errors|Abort messages|Parse Error)/m; type ChildResult = { status: number | null; @@ -227,6 +228,12 @@ const tail = (r: FileResult) => { return kept.join("").trim().split("\n").slice(-30).join("\n"); }; +const firstLines = (text: string) => { + const lines = text.trim().split("\n"); + if (lines.length > 40) lines.splice(40, Infinity, `... ${lines.length - 40} more lines`); + return lines.join("\n"); +}; + const stopOf = (r: FileResult): Stop => { const errors: Part[] = []; for (const m of r.error ? [] : messagesOf(r.output)) @@ -238,9 +245,14 @@ const stopOf = (r: FileResult): Stop => { ) errors.push(m); if (!errors.length) return { status: r.status, message: tail(r) }; - const lines = [...plainText(errors)].join("").trim().split("\n"); - if (lines.length > 40) lines.splice(40, Infinity, `... ${lines.length - 40} more lines`); - return { status: r.status, message: lines.join("\n") }; + return { status: r.status, message: firstLines([...plainText(errors)].join("")) }; +}; + +const sanyErrors = (r: FileResult) => { + if (r.error) return undefined; + const text = [...plainText(messagesOf(r.output))].join(""); + const at = text.search(SANY_ERRORS); + return at === -1 ? undefined : firstLines(text.slice(at)); }; const names = (rules: Rule[], kind: Rule["kind"]) => { @@ -305,8 +317,21 @@ export async function check(specFile: string, configFile: string): Promise path.join(here, "corpus", name, file); @@ -693,6 +694,48 @@ test("a step that leaves every child of a parent the same way is one arrow from assert.deepEqual(quits, [[open, closed]]); }); +test("a parent's only way in ends at the parent, and its start marker goes on to each state with that step's label", () => { + const graph = graphOf( + [ + ["ask", { at: "Asking" }, true], + ["flat", { at: "Layout.Flat" }], + ["parents", { at: "Layout.Parents" }], + ["drawn", { at: "Done.Drawn" }], + ], + [ + ["ask", "flat", "String"], + ["ask", "parents", "Array"], + ["flat", "drawn", "Draw"], + ], + ); + const { chart } = draw(graph, { state: (v) => String(v.at).split(".") }); + assert.deepEqual(drawn(chart).arrows.sort(), [ + "Asking --> Layout", + "Done start --> Drawn", + "Flat --> Done: Draw", + "Layout start --> Flat: String", + "Layout start --> Parents: Array", + ]); +}); + +test("a parent that two states lead into keeps an arrow from each, since one start marker cannot say where each came from", () => { + const graph = graphOf( + [ + ["a", { at: "A" }, true], + ["b", { at: "B" }], + ["p", { at: "P.p" }], + ["q", { at: "P.q" }], + ], + [ + ["a", "b", "Go"], + ["a", "p", "Left"], + ["b", "q", "Right"], + ], + ); + const { chart } = draw(graph, { state: (v) => String(v.at).split(".") }); + assert.deepEqual(drawn(chart).arrows.sort(), ["A --> B: Go", "A --> p: Left", "B --> q: Right"]); +}); + test("a label codes only the characters that Mermaid reads as syntax, so TLA+ values stay as TLC prints them", () => { const graph = graphOf( [ diff --git a/skills/statechart/scripts/test/cli.test.ts b/skills/statechart/scripts/test/cli.test.ts index 97b71c3..11f06a6 100644 --- a/skills/statechart/scripts/test/cli.test.ts +++ b/skills/statechart/scripts/test/cli.test.ts @@ -9,6 +9,7 @@ import { setTimeout as sleep } from "node:timers/promises"; import { fileURLToPath, pathToFileURL } from "node:url"; import { plainText } from "../backends/plain-text.ts"; import { readMessages } from "../frontends/messages.ts"; +import { drawn } from "./drawn.ts"; const here = path.dirname(fileURLToPath(import.meta.url)); const corpus = path.join(here, "corpus"); @@ -881,18 +882,6 @@ test("a view with a group in a theme color draws that color and names the group assert.match(chart, new RegExp(`^ {2}class ${legend} teal$`, "m")); }); -const shown = (text: string) => text.replace(/#(\d+);/g, (_, n) => String.fromCodePoint(Number(n))); - -const drawn = (chart: string) => { - const names = new Map(); - for (const m of chart.matchAll(/^ *(?:state "(.*)" as (s\d+) \{|(s\d+): (.*))$/gm)) - names.set(m[2] ?? m[3], shown(m[1] ?? m[4])); - const arrows: string[] = []; - for (const [, from, to, text] of chart.matchAll(/^ *(s\d+) --> (s\d+): (.*)$/gm)) - arrows.push(`${names.get(from)} --> ${names.get(to)}: ${shown(text)}`); - return { states: [...names.values()], arrows }; -}; - const byX = (labels: unknown[]) => `export const state = (v) => ${JSON.stringify(labels)}[v.x];\n`; const fanOut = (n: number) => { @@ -926,7 +915,7 @@ for (const [what, c] of [ view: byX([["a\0b"], ["a", "b"], ["c"], ["d"]]), status: 0, states: ["ab", "a", "b", "c", "d"], - arrows: ["ab --> b: Inc", "b --> c: Inc", "c --> d: Inc"], + arrows: ["a start --> b", "ab --> a: Inc", "b --> c: Inc", "c --> d: Inc"], says: /^TLC reached 4 states and 3 steps\. The chart draws 4 states and 3 arrows\.$/m, }, ], @@ -942,7 +931,14 @@ for (const [what, c] of [ ]), status: 0, states: ["R f", "S p", "R ab", "S q", "R a", "R b", "S r"], - arrows: ["S p --> S q: Inc", "S p --> S r: Inc"], + arrows: [ + "R f start --> S p", + "R ab start --> S q", + "R b start --> S r", + "R a start --> R b", + "S p --> R ab: Inc", + "S p --> R a: Inc", + ], says: /^The regions chart lets R f, S p go to R a\0b, S r by Inc, which the model never does\. So the chart draws parent states in place of regions\.$/m, }, ], @@ -964,7 +960,7 @@ for (const [what, c] of [ view: byX([["a\u0001b"], ["a", "b"], ["c"], ["d"]]), status: 0, states: ["a\u0001b", "a", "b", "c", "d"], - arrows: ["a\u0001b --> b: Inc", "b --> c: Inc", "c --> d: Inc"], + arrows: ["a start --> b", "a\u0001b --> a: Inc", "b --> c: Inc", "c --> d: Inc"], says: /^TLC reached 4 states and 3 steps\. The chart draws 4 states and 3 arrows\.$/m, }, ], @@ -1002,7 +998,7 @@ for (const [what, c] of [ view: byX([["a"], ["P", "b\u0002c"], ["d"], ["e"]]), status: 1, states: ["a", "P", "b\u0002c", "d", "e"], - arrows: ["a --> b\u0002c: Next", "b\u0002c --> d: Next", "d --> e: Next"], + arrows: ["P start --> b\u0002c", "a --> P: Next", "b\u0002c --> d: Next", "d --> e: Next"], says: /^## NotOne breaks\nThe shortest path has 1 step:\n0\. a\n1\. Next: P \/ b\cBc$/m, }, ], @@ -1039,10 +1035,15 @@ for (const [what, c] of [ status: 0, states: ["R f", "S p", "R a", "S r", "R b", "S q", "R X\u0003a", "S q", "R X\u0003b", "S r"], arrows: [ - "S p --> S r: Go\u0003X", - "S p --> S q: Go\u0003X", - "S p --> S q: Go", - "S p --> S r: Go", + "R f start --> S p", + "R a start --> S r", + "R b start --> S q", + "R X\u0003a start --> S q", + "R X\u0003b start --> S r", + "S p --> R a: Go\u0003X", + "S p --> R b: Go\u0003X", + "S p --> R X\u0003a: Go", + "S p --> R X\u0003b: Go", ], says: /^The regions chart lets R f, S p go to R a, S q by Go\cCX, which the model never does\. So the chart draws parent states in place of regions\.$/m, }, diff --git a/skills/statechart/scripts/test/corpus.test.ts b/skills/statechart/scripts/test/corpus.test.ts index 8934373..90a4104 100644 --- a/skills/statechart/scripts/test/corpus.test.ts +++ b/skills/statechart/scripts/test/corpus.test.ts @@ -383,6 +383,44 @@ for (const [width, height, config, status, drawn, chart, header] of [ }, ); +for (const [what, tla, where] of [ + [ + "an unknown name", + ["---- MODULE Broken ----", "VARIABLE x", "Init == x = 0", "Next == x' = y", "===="], + /^line 4, col 14 to line 4, col 14 of module Broken\n+Unknown operator: `y'\.$/m, + ], + [ + "a parse error", + ["---- MODULE Broken ----", "VARIABLE x", "Init == x = = 0", "Next == x' = x", "===="], + /^Encountered "0" at line 3, column 15/m, + ], + [ + "twelve unknown names", + [ + "---- MODULE Broken ----", + "VARIABLE x", + "Init == x = 0", + ...Array.from({ length: 12 }, (_, i) => `D${i} == u${i}`), + "Next == x' = x", + "====", + ], + /^\*\*\* Errors: 12\n+line 4, col 7 to line 4, col 8 of module Broken\n+Unknown operator: `u0'\.$/m, + ], +] as const) + test( + `a spec with ${what} gets SANY's line and column, not a Java stack trace`, + { skip }, + async () => { + const base = writeSpec("Broken", [...tla], "INIT Init\nNEXT Next\n"); + await assert.rejects(check(`${base}.tla`, `${base}.cfg`), (error: Error) => { + assert.match(error.message, /^SANY could not read .*Broken\.tla \(exit 1\):\n/); + assert.match(error.message, where); + assert.doesNotMatch(error.message, /^\s+at tla2sany\./m); + return true; + }); + }, + ); + test( "check() leaves no statechart- folder in the temp dir when it returns and when it throws", { skip }, diff --git a/skills/statechart/scripts/test/corpus/Login/chart.mmd b/skills/statechart/scripts/test/corpus/Login/chart.mmd index 9733b21..547bd3e 100644 --- a/skills/statechart/scripts/test/corpus/Login/chart.mmd +++ b/skills/statechart/scripts/test/corpus/Login/chart.mmd @@ -6,12 +6,13 @@ stateDiagram-v2 s4: Checking second try s5: Wrong password, 1 try left s6: Checking last try + [*] --> s2 } s7: Reset email sent s8: Signed in s9: Locked out [*] --> s0 - s0 --> s2: YouSubmitAPassword + s0 --> s1: YouSubmitAPassword s2 --> s8: ThePasswordIsRight s2 --> s3: ThePasswordIsWrong s7 --> s0: YouSetANewPassword diff --git a/skills/statechart/scripts/test/drawn.ts b/skills/statechart/scripts/test/drawn.ts new file mode 100644 index 0000000..1290403 --- /dev/null +++ b/skills/statechart/scripts/test/drawn.ts @@ -0,0 +1,20 @@ +const shown = (text: string) => text.replace(/#(\d+);/g, (_, n) => String.fromCodePoint(Number(n))); + +export const drawn = (chart: string) => { + const names = new Map(); + for (const m of chart.matchAll(/^ *(?:state "(.*)" as (s\d+) \{|(s\d+): (.*))$/gm)) + names.set(m[2] ?? m[3], shown(m[1] ?? m[4])); + const arrows: string[] = []; + const blocks: string[] = []; + for (const line of chart.split("\n")) { + const block = line.match(/^ *state ".*" as (\w+) \{$/); + if (block) blocks.push(block[1]); + if (/^ *\}$/.test(line)) blocks.pop(); + const m = line.match(/^ *(s\d+|\[\*\]) --> (s\d+)(?:: (.*))?$/); + const parent = names.get(blocks.at(-1) ?? ""); + if (!m || (m[1] === "[*]" && parent === undefined)) continue; + const from = m[1] === "[*]" ? `${parent} start` : names.get(m[1]); + arrows.push(`${from} --> ${names.get(m[2])}${m[3] === undefined ? "" : `: ${shown(m[3])}`}`); + } + return { states: [...names.values()], arrows }; +}; diff --git a/skills/statechart/scripts/test/labels.ts b/skills/statechart/scripts/test/labels.ts index a3d1499..6b5165b 100644 --- a/skills/statechart/scripts/test/labels.ts +++ b/skills/statechart/scripts/test/labels.ts @@ -1,5 +1,5 @@ import { inspect } from "node:util"; -import { mermaid as chartText } from "../backends/mermaid.ts"; +import { drawnEdges, mermaid as chartText } from "../backends/mermaid.ts"; import { checkView } from "../frontends/view.ts"; import type { Chart, ChartState, State, Step, View } from "../ir.ts"; import { walk } from "../passes/reach.ts"; @@ -398,6 +398,7 @@ function expected(chart: Chart): Want { const region = chart.regions[i]; const wrap = multi ? `r${i}` : null; if (wrap) nodes.set(wrap, { text: region.name, parent: "all", group: true }); + const drawn = drawnEdges(region); const tree = (prefix: string[], parent: string | null, below: ChartState[]) => { const heads = new Map(); for (const s of below) { @@ -413,19 +414,23 @@ function expected(chart: Chart): Want { else leaf = s; const node = id(region.name, path); nodes.set(node, { text: head, parent, group: inner.length > 0 }); - if (inner.length) tree(path, node, inner); - else if (leaf?.group !== undefined) used.add(chart.colors[String(leaf.group)]); + if (inner.length) { + tree(path, node, inner); + const key = JSON.stringify(path); + for (const edge of drawn) + if (edge.start && JSON.stringify(edge.from) === key) + edges.push([`${node}_start`, id(region.name, edge.to), edge.label ?? ""]); + } else if (leaf?.group !== undefined) used.add(chart.colors[String(leaf.group)]); } }; tree([], wrap, region.states); - for (const s of region.states) - if (s.start) edges.push([`${wrap ?? "root"}_start`, id(region.name, s.path), ""]); - for (const s of region.steps) - edges.push([ - id(region.name, s.from), - id(region.name, s.to), - s.label + (s.when ? ` [${s.when}]` : ""), - ]); + for (const edge of drawn) + if (!edge.start || !edge.from.length) + edges.push([ + edge.start ? `${wrap ?? "root"}_start` : id(region.name, edge.from), + id(region.name, edge.to), + edge.label ?? "", + ]); } let legend = 0; for (const [text, cls] of Object.entries(chart.colors)) diff --git a/skills/statechart/scripts/test/render.test.ts b/skills/statechart/scripts/test/render.test.ts index 5309a92..a7b53e9 100644 --- a/skills/statechart/scripts/test/render.test.ts +++ b/skills/statechart/scripts/test/render.test.ts @@ -6,6 +6,10 @@ import os from "node:os"; import path from "node:path"; import { before, test } from "node:test"; import { fileURLToPath, pathToFileURL } from "node:url"; +import { mermaid as chartText } from "../backends/mermaid.ts"; +import type { Graph } from "../ir.ts"; +import { walk } from "../passes/reach.ts"; +import { project } from "../pipeline.ts"; import { fuzz, type Html, type Mermaid, type Render } from "./labels.ts"; const here = path.dirname(fileURLToPath(import.meta.url)); @@ -75,6 +79,66 @@ test("random labels and colors keep their text and the chart's shape in Mermaid assert.ok(drawn > 400 && refused > 20, `${drawn} charts drawn, ${refused} refused`); }); +const pathPoints = (d: string) => { + const points: number[][] = []; + let [ax, ay] = [0, 0]; + for (const [, cmd, args] of d.matchAll(/([MLC])([^MLC]*)/g)) { + const n = args.split(/[ ,]/).filter(Boolean).map(Number); + const [x, y] = n.slice(-2); + if (cmd !== "M") + for (let t = 0; t <= 1; t += 1 / 64) { + const u = 1 - t; + points.push( + cmd === "L" + ? [ax + (x - ax) * t, ay + (y - ay) * t] + : [ + u ** 3 * ax + 3 * u * u * t * n[0] + 3 * u * t * t * n[2] + t ** 3 * x, + u ** 3 * ay + 3 * u * u * t * n[1] + 3 * u * t * t * n[3] + t ** 3 * y, + ], + ); + } + [ax, ay] = [x, y]; + } + return points; +}; + +test("an arrow into a parent from its only way in stays out of the parent's title bar in Pele 1.9.0", () => { + const graph: Graph = { states: new Map(), steps: [] }; + for (const [id, at] of [ + ["ask", "Asking your view for labels"], + ["flat", "Laying out the chart/Flat"], + ["parents", "Laying out the chart/Parent states"], + ["regions", "Laying out the chart/Regions"], + ] as const) + graph.states.set(id, { vars: { at }, start: id === "ask", breaks: [] }); + for (const [to, action] of [ + ["flat", "String"], + ["parents", "Array"], + ["regions", "Object"], + ] as const) + graph.steps.push({ from: "ask", to, action }); + const { chart } = project(graph, walk(graph), { state: (v) => String(v.at).split("/") }, []); + const { svg } = render(chartText(chart)); + const bars = [ + ...svg.matchAll( + /]*\/> x > bar.left && x < bar.right && y > bar.top && y < bar.bottom, + ) + ) + crossings.push(`${id} crosses the title bar of ${bar.id}`); + assert.deepEqual(crossings, []); +}); + test("the theme in references/render.md colors each class that the charts use", () => { assert.ok(classes.size > 0); for (const name of classes) assert.match(theme, new RegExp(`\\.pele \\.${name} rect \\{`), name); diff --git a/skills/teach/SKILL.md b/skills/teach/SKILL.md index 6b63e62..d703120 100644 --- a/skills/teach/SKILL.md +++ b/skills/teach/SKILL.md @@ -7,11 +7,11 @@ description: "Explain a body of work plainly so a person actually understands it Explain what a thing is, how it works, and why it is built that way, at the person's pace. They should understand it. Do not change the code. -Teach sits on `/pstack:how` and `/pstack:why`. Orient yourself with `read`, then invoke those skills. Do not redo their investigation by hand. Blend the results into one plain account. Keep why's hedges. Those hedges are findings. +Teach sits on `/pstack:how` and `/pstack:why`. Orient yourself with `read`, then invoke those skills. Do not redo their investigation by hand. Blend the results into one plain account. 1. Decide the few things they should walk away knowing. Read that from why they asked and what they already know in this conversation. Do not quiz them. Skip what they already know. -2. Invoke `/pstack:how` for mechanics and `/pstack:why` for motivation. Issue both before waiting when the host runs them together. Sequential is fine. Say so. Match size to the question. Both for a subsystem. One may be enough for a small change. Keep why narrow by default. Put the narrowing in the ask. Widen only when the reasons are the point. +2. Invoke `/pstack:how` for mechanics and `/pstack:why` for motivation. Issue both before waiting when the host runs them together. Sequential is fine. Say so. Match size to the question. Both for a subsystem. One may be enough for a small change. 3. Start with a plain definition. Name the thing. Say what it is. Then tie it to this repo. Then how it works, then why, then edges. Explain the mechanism. Do not list functions like a changelog. Do not print framing labels such as "the key insight", "at its core", or "TL;DR". diff --git a/skills/why/SKILL.md b/skills/why/SKILL.md index 4592e6f..242bd26 100644 --- a/skills/why/SKILL.md +++ b/skills/why/SKILL.md @@ -1,64 +1,10 @@ --- name: why -description: "Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, or postmortems. Searches source control history (git log and blame, PRs and linked issues via `gh`, code comments, in-repo docs) and returns a cited, confidence-weighted read on decisions and tradeoffs. Use how for runtime behavior." +description: "Use for why a design exists, why it was picked, a regression, or a postmortem. Returns a cited read of the decisions and tradeoffs. Trace the code, or use how, for how it runs." --- # Why -Investigate motivation, constraints, and rejected alternatives. Use `/pstack:how` for mechanics. +Answer from the history, not from how the code reads. Read the commits and the PR discussion that added the target and each later change. Look further when that trail is thin. Quote what the authors wrote, mark inferences as inferences, and name what the record leaves open. -The source registry currently covers source control: commits, PRs, linked issues, review threads, code comments, and in-repo docs. Name gaps in coverage when they matter. Query thoroughly, then synthesize with explicit confidence. Null results are evidence. Coverage is the default. - -Resolve profiles from [`../poteto-mode/references/panel-run.md`](../poteto-mode/references/panel-run.md). Record a `PanelRun` before the first `run_subagent` call. - -Read [`references/epistemics.md`](references/epistemics.md). Investigators gather evidence; the synthesizer follows its confidence tiers. - -## Step 1. Target and question - -Name the code, pattern, feature, or decision. Restate the question. If the target is vague, guess from this conversation, state it, continue. - -## Step 2. Code anchor - -Inline, cheap: - -- File paths and line ranges -- Key symbols -- Recent commits on the target (`exec` git blame, git log --follow, git log --oneline) -- PR numbers from merge subjects, then `gh pr view` when `gh` works - -Pass this seed to each investigator. - -## Step 3. Investigators - -Default is the full sweep of source control history. - -Read the registry in [`references/source-playbook.md`](references/source-playbook.md). Search each registered category whose tools are available. Source control is the sole registered category today. Check git access and `gh` availability/authentication separately; search local history even if PR access fails and record the partial coverage and reason. - -For each available category, resolve the exact `why investigators` role through the panel contract and dispatch its configured perspectives. With the default profile list and registry, this is one worker. Follow `executionMode` for independent workers. Workers must not write files, commit, or change external state. - -Each investigator gets [`references/investigator-prompt.md`](references/investigator-prompt.md) with its source name and registered playbook filled in, the code anchor, and the question. Append [`references/sources/incident-postmortem.md`](references/sources/incident-postmortem.md) for defensive code investigated through source control. - -Collect findings, empty searches, availability failures, and additional leads. Route a cross-source lead to the worker for its registered, available category; record unchased leads with the reason (unregistered, unavailable, or outside the requested scope). - -## Step 4. Synthesize - -Resolve the `why synthesizer` role through the panel contract. Same no-write rule. Give it the available read tools for the registered sources to spot-check citations. - -Give it all investigator findings, source availability and reasons, and unchased leads, the code anchor, the question, [`references/epistemics.md`](references/epistemics.md), and [`references/synthesizer-prompt.md`](references/synthesizer-prompt.md). - -## Step 5. Present - -Light edits only. Do not rewrite confidence language. - -## Output format - -Use [`references/synthesizer-prompt.md`](references/synthesizer-prompt.md): The Question, The Code in Question, What We Found, What We Can Reasonably Infer, Competing Hypotheses, What We Don't Know, Sources Consulted, Confidence Summary. Keep the confidence split. Sources Consulted names each registered category, searches, unavailable portions and reasons, and unchased leads. - -If this `why` precedes a change, add Preserve / Change / Avoid / Risk from the lineage. - -## Models - -`$HOME/.config/devin/pstack-models.md` overrides these defaults. - -- why investigators: `pstack:panel-sonnet` -- why synthesizer: `pstack:panel-opus` +Use `exec` for `git` and `gh`. Do not invent a source catalog. diff --git a/skills/why/references/epistemics.md b/skills/why/references/epistemics.md deleted file mode 100644 index b713cba..0000000 --- a/skills/why/references/epistemics.md +++ /dev/null @@ -1,71 +0,0 @@ -# Epistemics - -How to reason about confidence when evidence is historical, fragmentary, and sometimes contradictory, and how to tell the user without flattening it into false certainty. Code shows what it does, not *why it exists*. This port searches commits, PRs, linked issues, review threads, code comments, and in-repo docs. Other evidence may be unavailable. The record is incomplete, biased, and sometimes missing. Pretending otherwise produces confident-sounding guesses that mislead the user. - -## Confidence Tiers - -Every claim in the output must sit in one tier. The tier sets its section and its phrasing. - -### 1. Direct - -An explicit, textual citation answers the question: something an author actually *wrote* that says why, not "the code does X so the author must have wanted X." For example, a PR description "this fixes the bug where users with >1000 items couldn't paginate", a linked issue "we're adding this because customer Acme requested it in their security review", a code comment "// clamp to 100 because the upstream API rejects larger values", a design doc "we chose option A over option B because we need persistence across restarts", or a PR review comment from the author "switching to this approach since the old one was flaky in tests". - -Phrasing: confident, present tense, cited. "This exists because X." - -### 2. Supported - -Multiple pieces of indirect evidence converge on one conclusion. No single source states it explicitly, but the pattern across sources makes it likely. For example, the PR title says "improve performance", the issue is labeled "perf", and the surrounding commits all touch the same hot path. Or several tests added with the change all exercise very large inputs. Or the author's other PRs from the same week all name the same incident. - -Phrasing: confident but clearly derived, citing each item. "The evidence points strongly to X: [the specific pieces]." - -### 3. Inferred - -A reasonable reading of the context that nothing explicitly supports. It is *your interpretation*, not a fact from the record. For example, the PR doesn't say why, but the error was happening in production (per a "fix for incident" commit the same week) and the fix was rushed (merged the same day), so it was likely a hotfix. Or the function name suggests retry logic, and its retry count of 3 matches the team's 3-retry convention elsewhere in the codebase. - -Phrasing: hedged, with the chain explicit. "Given A and B, C seems likely because D." - -### 4. Speculative - -A plausible hypothesis on thin evidence, where other explanations fit equally well. Worth presenting, since the user may know which is right, but mark it as a guess. For example, "This might be a workaround for a browser bug that's since been fixed, but we found no contemporary evidence of that", or "It's possible this threshold was chosen to match an SLA commitment, but no SLA doc references it." - -Phrasing: "One possibility is X, but we have no direct evidence." Usually lives in Competing Hypotheses, alongside other possibilities. - -### 5. Unknown - -You looked and couldn't find out. A valid, important outcome. Document it. - -Phrasing: "We searched X, Y, and Z and found no evidence of why." Be specific about *what* you searched. "We couldn't find out" is less useful than "We ran `git log -S` for the threshold literal, scanned the 6 PRs that touched this file since 2023, and grep'd the repo for string literals matching the threshold. None surfaced a rationale." - -## Phrasing Guide - -**Confidence words** imply Direct or Supported evidence and need a citation immediately adjacent. Never use them for inferences: "because", "the reason is", "was designed to" (claims author intent), "fixes" / "addresses" / "solves" (claims the change achieved its goal), "the team decided" (claims a group decision happened). - -**Hedges** signal interpretation, not report. Use them liberally in What We Can Reasonably Infer: "appears to", "seems to", "likely", "suggests", "is consistent with", "one reading is", "plausibly", "may have been", "the evidence points toward". - -**Words to avoid:** - -- "obviously". If it were obvious, the user wouldn't be asking -- "clearly". Almost always precedes a claim that isn't clear -- "of course". Same -- "just" (as in "it's just X for performance"). Dismissive and usually hides uncertainty -- "I think" / "I believe". You're synthesizing evidence, not giving a personal opinion. Use "the evidence suggests" instead. - -## Avoid Rationalization - -Code that "makes sense" today may have been written for reasons that no longer apply, or that were wrong at the time. Don't retrofit a clean rationale onto messy history. Don't assume the author did the "right" thing and work backward to justify it. Don't assume a consistent pattern was intentional when it might be copy-paste. Don't turn an absence of evidence into evidence of absence ("no one mentioned security concerns, so it must not have been a concern"). - -## The Sycophancy Trap - -Users often embed a hypothesis: "Why do we do it this way, I assume it's for performance?" Don't simply confirm it. The guess is a prompt for investigation, not a conclusion to validate. Treat it as one candidate among others and check the evidence independently. If the evidence supports it, say so with citations. If not, say so, and present what the evidence *does* support. - -## When Evidence Contradicts - -Surface both sources in the output, with citations. Don't pick the one that fits a tidier narrative. For example, the ticket says "we need this for customer X's compliance requirement" and the PR says "cleaning up tech debt in this area". Both may be true (the ticket motivated the work, the PR gave the author's framing), or one may be wrong. Let the user make the call. - -## When Evidence Is Missing - -An honest "we don't know" is one of the most valuable outputs. The user learns the answer isn't in the obvious places, that they'll need to ask a human (the original author, the product owner, the team lead), or that they can decide the question isn't worth pursuing further. Failing to mark a gap, and instead filling it with a confident guess, actively harms the user, because they'll act on the guess. Name each gap concretely: the question, the sources searched, what you searched for in each, and what you found (nothing, or only tangential material). - -## Before Finalizing - -Before the synthesizer delivers the output, it checks every claim in "What We Found" and "What We Can Reasonably Infer". Each claim has a citation or moves to Inferred or Hypotheses. Its phrasing matches its tier. It doesn't treat code as evidence for its own intent (if it does, remove or reclassify it). The output has a "What We Don't Know" section. If no gaps are mentioned, that's suspicious. Either the evidence was unusually complete or something is being swept under the rug. diff --git a/skills/why/references/investigator-prompt.md b/skills/why/references/investigator-prompt.md deleted file mode 100644 index d7eca3f..0000000 --- a/skills/why/references/investigator-prompt.md +++ /dev/null @@ -1,87 +0,0 @@ -# Investigator Prompt Template - -Build each investigator's prompt from this template. Fill in the placeholders, including the assigned source name and its playbook from `source-playbook.md`. For defensive code, append `sources/incident-postmortem.md` to the source-control investigator. - ---- - -You are investigating the historical context and motivation behind a piece of code. A separate synthesizer combines investigator findings into the final answer, so gather evidence accurately rather than writing prose. - -Cover your assigned source thoroughly. Other workers may cover other registered sources; stay within your assignment. - -Work like a careful, cautious, precise investigator. Surface evidence accurately, including contradictions. One verbatim quote with a precise citation beats a paragraph of plausible summary. - -## The Question - -> {QUESTION} - -## The Code Anchor - -**Target files:** {FILES_WITH_LINE_RANGES} - -**Key symbols:** {SYMBOLS} - -**Initial commits touching this code (most recent first):** -{COMMIT_LIST} - -**PR numbers extracted from commit messages:** {PR_NUMBERS} - -**Ticket IDs mentioned in commits or PR bodies (if any):** {TICKET_IDS} - -## Your Source - -{SOURCE_NAME} - -{SOURCE_PLAYBOOK} - -## Investigation Loop - -1. **Cast a wide net first**, then narrow in on specific items. -2. **Read the whole thing.** Read each PR, issue, doc, or thread fully, including comments and follow-ups. -3. **Follow links within your assigned source.** For source control, this includes linked PRs, commits, and GitHub issues. Record cross-source references under Additional Leads for the parent to route; do not chase them yourself. -4. **Quote verbatim** with the exact PR number, issue number, URL, commit hash, or file:line. -5. **Record queries verbatim**, including searches that returned nothing. -6. **Surface contradictions** with both citations. Do not suppress inconvenient evidence. - -Before calling a finding strong, ask whether you would expect it if your reading were wrong. Never invent or round a partial finding up to certainty. - -## Epistemic Discipline - -- **Mechanics are not motivation.** A commit changing `limit = 50` to `limit = 100` shows the change, not necessarily why. Look for the reason in the commit message, PR description, linked ticket, or review comments. -- **No intent from code behavior or style.** You may read code to learn what the target *is*. "The author chose a functional approach" is an observation about code, not evidence of intent. Claim intent only where the author stated it. -- **Preserve uncertainty.** Say when evidence is ambiguous, or when one reading is more plausible but not certain. Don't collapse ambiguity to look decisive. -- **No silent substitutions.** If the question is about feature X and you only find evidence about feature Y, don't present Y's evidence as if it answers X. - -## Output Format - -Return your findings in this structure. The synthesizer reads it directly. - -### Source -The assigned source name. - -### What I Searched -The queries you ran, items you opened, and places you looked. Be specific. This shows how thorough the search was and what is still unsearched. - -### Direct Evidence Found -For each item that explicitly addresses the question: -- **What it says**: verbatim quote or accurate paraphrase -- **Where it's from**: PR #123, issue number, commit hash, file:line, or URL -- **Author and date** (if available) -- **Relevance**: one sentence on how it bears on the question - -### Indirect / Circumstantial Evidence -For each item that bears on the question without answering it: -- **What it is**: brief description -- **Where it's from**: location -- **What it suggests**: what a careful reader might infer, and the inference chain -- **Alternative readings**: if the same evidence could support a different interpretation, note it - -### Contradictions -Items that disagree with each other, with both citations. - -### Gaps -Report unavailable tools or inaccessible items separately from completed searches with no results, with the reason for each. For empty searches, be specific: "Ran `git log -S ''` across the full history. No matching commits." These absences are valuable data. - -### Additional Leads -Cross-source references, with their locator, target category, and relevance, for the parent to route or report as unchased. - -Gather evidence, not a final answer. Do not pick sides in contradictions or speculate beyond the record. The synthesizer does the reasoning. diff --git a/skills/why/references/source-playbook.md b/skills/why/references/source-playbook.md deleted file mode 100644 index e82e0df..0000000 --- a/skills/why/references/source-playbook.md +++ /dev/null @@ -1,13 +0,0 @@ -# Source registry - -Only categories registered below are searched. An installed connector alone does not expand the sweep. Each investigator reads its assigned category's playbook. - -| Category | Playbook | Tools it documents | -|---|---|---| -| Source control history | [`code-archaeology.md`](./sources/code-archaeology.md) | git, `gh` | - -To add a connector, add a category row and a playbook describing its required read tools, availability/authentication check, search scope, citation locators, and source-specific pitfalls. Reuse an existing category for another provider of the same evidence. Use the shared investigator output contract; keep source-specific instructions in the playbook. Record unavailable tools as coverage gaps, not empty search results. - -Cross-cutting: - -- [`incident-postmortem.md`](./sources/incident-postmortem.md). Add this to the source-control investigator if the target code looks defensive (null checks, retry, timeout, rate limit, feature flag, egress guard, OOM handler). diff --git a/skills/why/references/sources/code-archaeology.md b/skills/why/references/sources/code-archaeology.md deleted file mode 100644 index 4fbe3c4..0000000 --- a/skills/why/references/sources/code-archaeology.md +++ /dev/null @@ -1,86 +0,0 @@ -# Code Archaeology (git + in-repo) - -## What this source contains - -- Commit history (messages, dates, authors, diffs) -- PR descriptions, review comments, and discussion threads (via `gh`) -- Inline code comments, TODOs, FIXMEs, deprecation notes -- ADRs (architectural decision records) if the repo keeps them -- Tests, whose names and assertions often encode the edge cases that motivated a change -- Related files modified in the same commits (co-change signal) -- CHANGELOG entries and release notes in the repo -- Issue/ticket IDs in commit messages and PR bodies - -The most trustworthy source, tied directly to the code, and the most complete. Everything that went through the repo should be here. - -## How to search it - -Expand the seed commit list: - -```bash -# History through renames -git log --follow --oneline -- - -# Pickaxe: commits that added or removed this exact text -git log -S '' -- - -# Or for patterns: -git log -G '' -- - -# Who wrote each line and when -git blame -L , - -# One commit's full diff -git show - -# Commits between two points affecting this file -git log .. -p -- -``` - -For each substantive commit, pull the PR context: - -```bash -# PR number from the merge commit or branch -git log -1 --format=%B - -# Body, review comments, linked issues. In a PR with discussion, reviews and comments hold the real signal -gh pr view --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews,files -``` - -Look for out-of-band docs: - -```bash -# ADRs often live in docs/adr/ or similar -rg -l -i 'architecture.decision' --glob '*.md' - -# TODOs and FIXMEs near the target -rg -n -C2 '(TODO|FIXME|HACK|XXX|NOTE)' - -# Related tests -rg -l '' --glob '*test*' -``` - -## What good evidence looks like here - -- A PR description that explains the problem, not just the change ("This fixes the pagination bug that caused X") -- A long review thread where alternatives were debated -- An inline comment near the target line that explains a non-obvious constraint -- A test named `test_handles_edge_case_when_X` that reveals a motivating edge case -- A commit message that references a ticket or incident ID -- A CHANGELOG entry that summarizes the user-visible rationale - -## Common pitfalls - -- **Squash-merge flatlands.** Squashed PRs lose their branch commits. Fall back to the PR body and comments. -- **Misleading commit messages.** "Small refactor" sometimes hides an intentional behavior change. Look at the diff, not the message. -- **Cargo-culted patterns.** The author may have copied a pattern without understanding why. Check whether it originated earlier in the codebase, and investigate *that* commit. -- **Bot commits and auto-merges.** Dependabot, Renovate, and automated backports usually carry no motivation. Skip them when looking for intent. -- **Treating code as evidence of intent.** The code isn't evidence for why it exists. Evidence comes from commit messages, PRs, comments, tests, and docs. Don't cite "the function is named X" as evidence of intent. - -## What to return - -Every commit/PR/comment that bears on the question, with: -- The exact text (quoted) -- The hash / PR number / file:line -- Author and date -- Whether it's direct (explicitly addresses the question) or circumstantial diff --git a/skills/why/references/sources/incident-postmortem.md b/skills/why/references/sources/incident-postmortem.md deleted file mode 100644 index 652a435..0000000 --- a/skills/why/references/sources/incident-postmortem.md +++ /dev/null @@ -1,11 +0,0 @@ -# Incident & Postmortem Context - -Not a separate source, a **cross-cutting angle**. Incidents often motivate defensive code ("we added this check after the X outage"), so if the target looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags), hunt for incident history inside source control: - -- **Commits**: messages like "fix for incident", "add defensive check", "hotfix", and "revert" followed by "re-apply with..." are strong signals. Try `git log -i -E --grep='incident|hotfix|outage|sev|postmortem' -- ` on the target file and around the dates it was added. -- **PRs**: search merged PRs for incident language (`gh search prs 'incident' --merged --repo `, `gh pr list --state merged --search 'sev OR postmortem OR outage' --repo `). Review comments often mention "this broke in prod" or name the incident. -- **External links in PR bodies**: postmortem docs, incident tickets, and status-page links pasted into PRs or comments. Record them as cross-source leads for the parent to route or report as unchased. - -If you find an incident reference, fetch the full PR thread. Postmortem action items often tie directly to the defensive code. - -Worth spending time on when the code's defensive character makes an incident-driven origin plausible. Skip it for code that doesn't look defensive. diff --git a/skills/why/references/synthesizer-prompt.md b/skills/why/references/synthesizer-prompt.md deleted file mode 100644 index 7ec6f2e..0000000 --- a/skills/why/references/synthesizer-prompt.md +++ /dev/null @@ -1,130 +0,0 @@ -# Synthesizer Prompt Template - -Build the synthesizer's prompt from this template; fill in the placeholders. - ---- - -You are answering a "why" question about a piece of code by synthesizing findings from investigators assigned to registered evidence sources. Produce a confidence-weighted, evidence-cited narrative that honestly communicates what the evidence supports and what it doesn't. - -## The Question - -> {QUESTION} - -## The Code Anchor - -**Target files:** {FILES_WITH_LINE_RANGES} - -**Key symbols:** {SYMBOLS} - -## Investigator Findings - -{ALL_INVESTIGATOR_FINDINGS} - -## Source Coverage - -{SOURCE_COVERAGE_WITH_REASONS} - -## Unchased Leads - -{UNCHASED_LEADS_WITH_REASONS} - -## Epistemics Framework - -You MUST follow `references/epistemics.md`. Read it in full before writing. The key rules: - -1. Every claim must sit in one tier: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. The tier sets its section and its phrasing. -2. Every Direct/Supported claim must have a citation (PR #, issue number, commit hash, file:line, or URL). -3. Inferred and Speculative claims must use hedged language ("appears to", "likely", "suggests", "one possibility is"). -4. Never cite code as evidence for its own intent. -5. Document gaps. Don't fill them with plausible-sounding guesses. -6. Treat a hypothesis embedded in the user's question as a candidate, not a conclusion. Check it independently. - -## Instructions - -1. Read all findings and weigh the evidence yourself. Investigators gathered evidence, not conclusions. -2. Merge overlaps into one authoritative reference. -3. Surface contradictions with both citations. Do not pick one. -4. Calibrate each claim. Direct claims need citations; inferences need hedges and the reasoning chain; speculation needs a label. Claims without evidence belong in gaps. -5. Spot-check uncertain citations with available read tools for registered sources. Do not write files, commit, or modify external state. -6. Leave unanswered questions open rather than fill them with confident guesses. - -## Output Format - -Write for the user, in this exact structure: - ---- - -### The Question - -Restate the user's question in one or two sentences. - -### The Code in Question - -File paths, line ranges, key symbols. Two or three lines to orient a cold reader. - -### What We Found - -Claims with textual evidence, each quoted or paraphrased and cited precisely: - -- **[Direct]** {Claim}. Source: [PR #123](https://example.com/pr/123) / ticket ID / file:line. {Brief quote or paraphrase.} -- **[Supported]** {Claim}. Evidence: {list of items and what each contributes}. - -`[Direct]` is single-source, explicit evidence. `[Supported]` is multiple indirect items converging on a conclusion. - -### What We Can Reasonably Infer - -Claims stated nowhere but well-supported by indirect evidence. Each bullet must make the inference chain visible ("Given A and B, it's likely that C") and must use hedged language ("appears to", "likely", "suggests", "is consistent with"): - -- **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}. - -Skip this section if there's nothing to infer. - -### Competing Hypotheses - -If the evidence fits multiple stories, present each. Don't force a winner the record doesn't support. For each hypothesis: - -- **Hypothesis:** {one-sentence statement} -- **Evidence for:** {specific items} -- **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist} - -Skip this section if there's a single clear answer. - -### What We Don't Know - -**Explicit gaps.** Things the user asked that the evidence didn't answer. Searches that came up empty. Sources or items that could not be searched, with the reasons. - -Be specific. "We ran `git log -S` and read the 6 PRs touching this file looking for the rate-limit threshold rationale and found nothing" is useful. "We don't know why" is not. Include: - -- Specific questions that went unanswered -- Searches that returned nothing -- External leads that could not be chased (tracker tickets, docs, chat threads the record references) -- People who would likely know but who you can't ask - -### Sources Consulted - -What was actually searched, so the user can judge coverage and redirect: - -- **{Registered category}**: queries and items actually searched, including empty results. State any unavailable portions and reasons separately. For source control, include files, commits, PRs, issues, and comments reviewed. -- **Unchased leads**: referenced items and why they were not followed (unregistered source, unavailable tools, or scope). Or "None surfaced." - -### Confidence Summary - -One or two sentences on overall confidence, e.g.: - -> "The core rationale (A) is well-supported by direct PR evidence. The specific threshold value (100) is inferred from the surrounding context but not explicitly documented. Whether it was driven by a customer request could not be answered; the searched records do not establish it." - ---- - -## Quality Check Before Returning - -Revise if any item fails: - -1. Does every claim in "What We Found" have a citation? If not, add one or move it to "Inferred" or "Hypotheses." -2. Is the phrasing tier-appropriate? (Direct claims can use "because"; Inferred claims cannot.) -3. Did you surface every contradiction you noticed, or quietly pick one? -4. Does "What We Don't Know" name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps. -5. Did you check any hypothesis embedded in the question against the evidence rather than rubber-stamp it? -6. Did you cite code as evidence for its own intent? Remove it. Code is mechanics, not motivation. -7. Is the tone calibrated? A confident-sounding answer on weak evidence is the exact failure this skill exists to prevent. - -The value of this output is its honesty, not its authority. A reader who takes it to the original author, an engineering lead, or a product manager should know what's known, what's inferred, and what's missing, so they can ask the right follow-up questions. Optimize for being useful, not for looking decisive. diff --git a/tests/port-contracts.test.mjs b/tests/port-contracts.test.mjs index de53668..ad57e06 100644 --- a/tests/port-contracts.test.mjs +++ b/tests/port-contracts.test.mjs @@ -137,10 +137,26 @@ test('every skill is named after its folder', () => { } }); +test('0.15.42 port keeps a short why, one how pass, and traced playbooks', () => { + const why = read('skills/why/SKILL.md'); + const how = read('skills/how/SKILL.md'); + assert.match(why, /Quote what the authors wrote/); + assert.match(why, /exec` for `git` and `gh`/); + assert.doesNotMatch(why, /references\/|Datadog|Linear|synthesizer/); + assert.match(how, /subagent_explore/); + assert.doesNotMatch(how, /how explorer|how explainer|references\//); + assert.match(read('skills/poteto-mode/SKILL.md'), /Do not route that trace through `\/pstack:how`/); + assert.match(read('skills/poteto-mode/playbooks/feature.md'), /Trace the affected subsystem/); + assert.match(read('skills/recall/SKILL.md'), /one investigator `run_subagent` per source/); + assert.match(read('skills/reflect/references/synthesizer.md'), /readConfig` to `loadSettings/); + assert.throws(() => read('skills/why/references/epistemics.md')); + assert.throws(() => read('skills/how/references/explainer-prompt.md')); +}); + test('plugin manifest is local-only and current release', () => { const manifest = JSON.parse(read('.devin-plugin/plugin.json')); assert.deepEqual(manifest.platforms, ['local']); - assert.equal(manifest.version, '0.9.2'); + assert.equal(manifest.version, '0.10.0'); }); test('e73df47 port keeps Devin paths, honest tool limits, and local-only reflect edits', () => { diff --git a/tests/poteto-delegation.test.mjs b/tests/poteto-delegation.test.mjs index 8b75c24..9e2b75a 100644 --- a/tests/poteto-delegation.test.mjs +++ b/tests/poteto-delegation.test.mjs @@ -74,9 +74,9 @@ describe("poteto delegation contract", () => { ); const expected = new Map([ ["feature, refactoring", "pstack:poteto-agent-opus"], - ["bug-fix", "pstack:poteto-agent-sonnet"], + ["bug-fix", "pstack:poteto-agent-opus"], ["perf-issue", "pstack:poteto-agent-opus"], - ["hillclimb", "pstack:poteto-agent-sonnet"], + ["hillclimb", "pstack:poteto-agent-opus"], ["judgment and prose", "pstack:panel-opus"], ["strongest judgment", "pstack:panel-opus"], ]); @@ -149,7 +149,7 @@ describe("poteto delegation contract", () => { it("keeps implementation defaults on legacy-equivalent model pins", () => { const roles = new Map(buildRoleConfigs(new Set(["opus", "swe", "sonnet"])).map((row) => [row.role, row])); - for (const [role, alias] of [["feature, refactoring", "opus"], ["bug-fix", "sonnet"], ["perf-issue", "opus"], ["hillclimb", "sonnet"]]) { + for (const [role, alias] of [["feature, refactoring", "opus"], ["bug-fix", "opus"], ["perf-issue", "opus"], ["hillclimb", "opus"]]) { const implementationPath = join(repoRoot, "agents", `poteto-agent-${alias}`, "AGENT.md"); const panelPath = join(repoRoot, "agents", `panel-${alias}`, "AGENT.md"); assert.deepEqual(roles.get(role).profiles, [`pstack:poteto-agent-${alias}`]); diff --git a/tests/pstack-models.test.mjs b/tests/pstack-models.test.mjs index 42f39a1..20b9741 100644 --- a/tests/pstack-models.test.mjs +++ b/tests/pstack-models.test.mjs @@ -47,29 +47,31 @@ describe("pstack models sheet", () => { it("maps panel roles to registered profiles and keeps list length", () => { const roles = buildRoleConfigs(parseDevinModelsList(LIST_FOUR)); - const critics = roles.find((row) => row.role === "how critics"); - assert.deepEqual(critics.profiles, [ + const runners = roles.find((row) => row.role === "arena runners"); + assert.deepEqual(runners.profiles, [ "pstack:panel-opus", "pstack:panel-swe", "pstack:panel-sonnet", ]); - assert.equal(critics.requiredPerspectives, 3); + assert.equal(runners.requiredPerspectives, 3); }); it("routes implementation roles to dedicated workers and keeps panels for review roles", () => { const roles = new Map(buildRoleConfigs(parseDevinModelsList(LIST_FOUR)).map((row) => [row.role, row])); assert.deepEqual(roles.get("feature, refactoring").profiles, [implementationProfile("opus")]); - assert.deepEqual(roles.get("bug-fix").profiles, [implementationProfile("sonnet")]); + assert.deepEqual(roles.get("bug-fix").profiles, [implementationProfile("opus")]); assert.deepEqual(roles.get("perf-issue").profiles, [implementationProfile("opus")]); - assert.deepEqual(roles.get("hillclimb").profiles, [implementationProfile("sonnet")]); + assert.deepEqual(roles.get("hillclimb").profiles, [implementationProfile("opus")]); assert.deepEqual(roles.get("judgment and prose").profiles, ["pstack:panel-opus"]); - assert.deepEqual(roles.get("how critics").profiles, ["pstack:panel-opus", "pstack:panel-swe", "pstack:panel-sonnet"]); + assert.deepEqual(roles.get("arena runners").profiles, ["pstack:panel-opus", "pstack:panel-swe", "pstack:panel-sonnet"]); + assert.equal(roles.has("how explorer"), false); + assert.equal(roles.has("why investigators"), false); }); it("repeats one profile for three critic perspectives when only swe exists", () => { const roles = buildRoleConfigs(parseDevinModelsList(LIST_SWE)); - const critics = roles.find((row) => row.role === "how critics"); - assert.deepEqual(critics.profiles, [ + const runners = roles.find((row) => row.role === "arena runners"); + assert.deepEqual(runners.profiles, [ "pstack:panel-swe", "pstack:panel-swe", "pstack:panel-swe", @@ -89,14 +91,16 @@ describe("pstack models sheet", () => { assert.match(first.content, /Do not label one pass as a panel/); assert.match(first.content, /Implementation roles use `pstack:poteto-agent-`; review roles use `pstack:panel-`/); assert.match(first.content, /frontmatter `model:` pin is authoritative/); - assert.doesNotMatch(first.content, /claude-/); + assert.match(first.content, /^# defaults: 2$/m); + assert.doesNotMatch(first.content, /claude-|grok-|gemini-4-carbon|claude-fable/); }); it("preserves role order, notes, repeated perspectives and explicit overrides on rerun", () => { const out = join(mkdtempSync(join(tmpdir(), "pstack-models-")), "sheet.md"); - writeFileSync(out, "# My models\n\nNotes: Keep my preferred review order.\nhow critics: pstack:panel-codex, pstack:panel-codex\nbug-fix: pstack:panel-opus\n"); + writeFileSync(out, "# My models\n\nNotes: Keep my preferred review order.\narena runners: pstack:panel-codex, pstack:panel-codex\nbug-fix: pstack:panel-opus\n"); const first = writeFromModelsList(LIST_FOUR, { out, roles: ["swarm workers=pstack:panel-sonnet", "feature, refactoring=pstack:poteto-agent-codex"] }); assert.match(first.content, /Notes: Keep my preferred review order/); - assert.equal(first.roles[0].role, "how critics"); + assert.match(first.content, /^# defaults: 2$/m); + assert.equal(first.roles[0].role, "arena runners"); assert.equal(first.roles[0].requiredPerspectives, 2); assert.deepEqual(first.roles[1].profiles, ["pstack:panel-opus"]); assert.match(first.content, /swarm workers: pstack:panel-sonnet/); @@ -109,7 +113,7 @@ describe("pstack models sheet", () => { "bug-fix: pstack:poteto-agent-swe\nbug-fix: pstack:poteto-agent-opus\n", "unknown role: pstack:panel-opus\n", "bug-fix: pstack:panel-missing\n", - "how critics: pstack:poteto-agent-opus\n", + "arena runners: pstack:poteto-agent-opus\n", "bug-fix: \n", ]) { writeFileSync(out, content); @@ -123,7 +127,7 @@ describe("pstack models sheet", () => { const content = writeFromModelsList(LIST_FOUR, { out }).content; for (const roles of [ ["no such role=pstack:panel-opus"], - ["how critics=pstack:poteto-agent-opus"], + ["arena runners=pstack:poteto-agent-opus"], ["bug-fix=pstack:poteto-agent-claude"], ["bug-fix=pstack:poteto-agent-opus", "bug-fix=pstack:poteto-agent-swe"], ]) { @@ -139,11 +143,40 @@ describe("pstack models sheet", () => { const script = join(dirname(fileURLToPath(import.meta.url)), "../skills/setup-pstack/write-models.mjs"); const result = spawnSync(process.execPath, [script, "--out", out, "--role", "bug-fix=pstack:poteto-agent-codex", - "--role", "how critics=pstack:panel-swe,pstack:panel-swe"], { input: LIST_FOUR, encoding: "utf8" }); + "--role", "arena runners=pstack:panel-swe,pstack:panel-swe"], { input: LIST_FOUR, encoding: "utf8" }); assert.equal(result.status, 0, result.stderr); const sheet = readFileSync(out, "utf8"); assert.match(sheet, /bug-fix: pstack:poteto-agent-codex/); - assert.match(sheet, /how critics: pstack:panel-swe, pstack:panel-swe/); + assert.match(sheet, /arena runners: pstack:panel-swe, pstack:panel-swe/); + }); + + it("migrates old bug-fix and hillclimb defaults once, and drops retired roles", () => { + const out = join(mkdtempSync(join(tmpdir(), "pstack-models-")), "sheet.md"); + writeFileSync(out, [ + "# old", + "bug-fix: pstack:poteto-agent-sonnet", + "hillclimb: pstack:poteto-agent-sonnet", + "swarm workers: pstack:panel-codex", + "how explorer: pstack:panel-sonnet", + "why investigators: pstack:panel-opus", + "", + ].join("\n")); + const first = writeFromModelsList(LIST_FOUR, { out }); + assert.match(first.content, /^# defaults: 2$/m); + assert.match(first.content, /bug-fix: pstack:poteto-agent-opus/); + assert.match(first.content, /hillclimb: pstack:poteto-agent-opus/); + assert.match(first.content, /swarm workers: pstack:panel-codex/); + assert.doesNotMatch(first.content, /how explorer|why investigators|how critics/); + assert.deepEqual(first.migrations, [ + "bug-fix: pstack:poteto-agent-sonnet -> pstack:poteto-agent-opus", + "hillclimb: pstack:poteto-agent-sonnet -> pstack:poteto-agent-opus", + ]); + assert.deepEqual(first.dropped, ["how explorer", "why investigators"]); + writeFileSync(out, first.content.replace("bug-fix: pstack:poteto-agent-opus", "bug-fix: pstack:poteto-agent-codex")); + const kept = writeFromModelsList(LIST_FOUR, { out }); + assert.match(kept.content, /bug-fix: pstack:poteto-agent-codex/); + assert.deepEqual(kept.migrations, []); + assert.equal(writeFromModelsList(LIST_FOUR, { out }).content, kept.content); }); });