refactor(agent-personas): generalise discussion mode, fold review skills, drop Shape A/B jargon

[wmadden]

At a glance

Follow-up to #447. Three coordinated simplifications to the persona-library skill surface, prompted by use of the M3-landed skills and feedback from the ignite team (see the parallel ignite/#84).

A skill that wants the discussion mode now looks like this:

> discussion mode with architect and principal-engineer

— and the agent stress-tests an idea through those lenses, then offers to document the outcome as a spec, plan, ADR, or amendment. Personas are inputs to the skill, not part of its identity.

The changes

1. drive-design-discussion → drive-discussion

The discussion mechanics (one-thread-at-a-time, response shape, read-only stance, explicit exit-and-document step) are the skill; the personas are inputs. Personas can be specified by the user ("discussion mode with pm") or inferred from context and announced ("loading architect + principal-engineer based on the framing — say so if you want a different lens").

Synthesis now requires an in-depth written summary (not a one-paragraph wrap-up) that captures:

• The refined topic
• The decisions reached, with the why per decision (the reasoning is the durable value of the discussion — preserve it)
• Assumptions each decision rests on (future trigger for re-entering this skill when one falsifies)
• Alternatives considered and rejected, with the substantive rejection reason
• Open questions and accepted trade-offs
• Cross-pollinations between persona lenses

Followed by a mandatory offer to document the summary as a project spec, plan, ADR, or amendment. Discussions that produce real understanding deserve real artefacts.

Three worked examples (engineering design, product framing, mid-implementation falsified assumption) ground the configurable shape.

2. Fold the three review-* sub-skills back into drive-pr-local-review

review-system-design, review-implementation, and review-walkthrough (which #447 introduced as atomic single-persona sub-skills) are inlined as numbered passes in drive-pr-local-review:

• § 3 — architect pass → system-design-review.md
• § 4 — principal-engineer pass → code-review.md
• § 5 — tech-lead pass → walkthrough.md

Each transition is an explicit persona-load instruction. The skill still owns scope + expectations (§§ 1–2) and synthesis (§ 6).

One place to find the review content trumps the decomposition; in practice the three passes are always run together for a meaningful PR review, and the decomposition added file-jumping friction without producing reusable surfaces.

3. Drop the Shape A / Shape B terminology

The labels were jargon that did not help readers and produced a false dichotomy. drive-agent-personas now describes a single multi-persona pattern:

• Orchestrator persona named at top
• Persona transitions named at workflow boundaries within the skill body
• Each transition is its own explicit load instruction (persona is not propagated)
• Orchestrator reloaded at synthesis points

drive-discussion no longer announces its "shape"; the skill body is the contract.

4. Delete drive-product-discussion

drive-discussion invoked with the pm persona produces exactly what drive-product-discussion produced — same operating rules, same response shape, same exit-and-document protocol; only the lens differs. Worked example B in drive-discussion covers the product-framing case explicitly, and drive-discussion's description names "product mode" / "pm mode" as triggers so users routing to product framing still land in the right place.

Removing the preset keeps the surface honest: one mode skill, lens chosen at invocation time. Shipping per-persona presets would balloon the surface for no behavioural gain.

What this PR contains

.agents/skills/
  drive-agent-personas/SKILL.md       (M) — simplified Composite-skills section, no Shape A/B
  drive-create-spec/SKILL.md          (M) — cross-ref updates
  drive-design-discussion/SKILL.md    (D)
  drive-discussion/SKILL.md           (A) — generalised discussion mode
  drive-pr-local-review/SKILL.md      (M) — three review-* sub-skills inlined as numbered passes
  drive-product-discussion/SKILL.md   (D) — subsumed by drive-discussion + pm
  review-implementation/SKILL.md      (D) — inlined into drive-pr-local-review § 4
  review-system-design/SKILL.md       (D) — inlined into drive-pr-local-review § 3
  review-walkthrough/SKILL.md         (D) — inlined into drive-pr-local-review § 5

Test plan

• drive-discussion enters cleanly on each documented trigger phrase (discussion mode, tech design mode, product mode, pm mode, challenge my idea, pressure-test this).
• drive-discussion with user-specified personas honours the named set exactly; with no personas named, infers and announces.
• drive-discussion synthesis produces the in-depth summary (with reasoning, assumptions, rejected alternatives) and offers to document.
• drive-pr-local-review produces all three artefacts side-by-side on a real PR, with explicit persona transitions visible in the workflow.
• No remaining references to Shape A / Shape B, drive-design-discussion, drive-product-discussion, review-system-design, review-implementation, or review-walkthrough in .agents/skills/.

Alternatives considered

• Keep drive-design-discussion and drive-product-discussion as separate skills, each with their personas baked in. Tempting because it avoids touching the existing skills, but produces N skills competing for the same invocation surface ("discuss this" / "pressure-test this") with subtly different framings. Configurable personas-at-invocation is the load-bearing simplification — one skill, lens chosen at invocation time.
• Keep the three review- sub-skills decomposed* (as feat(agent-personas): persona library + skill-persona binding convention #447 landed them). They were never invoked independently in practice; the decomposition added file-jumping friction; cross-pass synthesis is easier to keep coherent when the passes share a skill body. Reverting the decomposition is a net simplification.
• Keep the Shape A / Shape B vocabulary as architecture documentation. The labels were jargon that produced a false dichotomy (some skills don't fit cleanly into either bucket). The single multi-persona pattern (orchestrator at top, transitions at boundaries) covers every multi-lens case we have without forcing a taxonomy choice on skill authors.
• Per-persona preset skills (drive-product-discussion, drive-architect-discussion, …) as thin wrappers. Removed drive-product-discussion precisely because this approach scales badly — every new persona would want a preset, and the configurable-lens shape already covers the use case.

Summary by CodeRabbit

• Documentation
  • Reworked multi-persona guidance and clarified orchestration, load/display rules, sequencing, and transition mechanics
  • Added a structured, read-only "drive-discussion" mode for guided Q&A with explicit entry/synthesis/exit steps
  • Swapped fallback guidance to use the new discussion flow for unsettled designs
  • Expanded and tightened the PR-local-review workflow with persona-driven passes and stricter acceptance checks
  • Removed several legacy review/product skill specs to consolidate workflows

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: fbfd5c3a-093d-4102-8223-484ab15f76dd

📥 Commits

Reviewing files that changed from the base of the PR and between 15315ae and 5623b72.

📒 Files selected for processing (9)

• .agents/skills/drive-agent-personas/SKILL.md
• .agents/skills/drive-create-spec/SKILL.md
• .agents/skills/drive-design-discussion/SKILL.md
• .agents/skills/drive-discussion/SKILL.md
• .agents/skills/drive-pr-local-review/SKILL.md
• .agents/skills/drive-product-discussion/SKILL.md
• .agents/skills/review-implementation/SKILL.md
• .agents/skills/review-system-design/SKILL.md
• .agents/skills/review-walkthrough/SKILL.md

---

📝 Walkthrough

Walkthrough

This PR refactors the agent skill architecture from atomic, implicit multi-persona coordination to an explicit orchestrator pattern. It consolidates five specialized review skills into a unified drive-discussion skill and reorients drive-pr-local-review to use formal persona-scoped passes with visible load instructions.

Changes

Agent Skill Architecture Refactoring

Layer / File(s)	Summary
Multi-persona skill mechanics .agents/skills/drive-agent-personas/SKILL.md	Replaces "Composite skills" guidance with "Multi-persona skills" section defining an explicit orchestrator persona, visible persona-load instructions at boundaries, a standardized transition mechanic, and an example plus extensibility note.
Unified discussion-mode skill .agents/skills/drive-discussion/SKILL.md	New skill defining read-only Q&A with persona-lensed questioning, selection/sequencing/cross-pollination rules, required response shape (assessment, why it matters, optional direction, next question), reloads tech-lead for synthesis, includes worked examples and an artefact-offer flow.
PR review orchestrator with persona passes .agents/skills/drive-pr-local-review/SKILL.md	Refactors from composite delegation to explicit orchestrator with persona-scoped passes: architect for system-design (typology/naming probes, coverage, quality bar), principal-engineer for code-review (structured findings, PASS/FAIL/NOT VERIFIED/WEAK verdicts, verification traps), tech-lead for walkthrough (audience/altitude, conflict surfacing, delegation mechanics), and synthesis checks for side-by-side artifacts. Metadata version bumped to 2026.5.11.
Skill name references .agents/skills/drive-create-spec/SKILL.md	Updates fallback skill reference from design-discussion to drive-discussion in two locations (entry-point guidance and guidelines when design is unsettled).
Removed legacy skills .agents/skills/drive-{design-discussion,product-discussion}/SKILL.md, .agents/skills/review-{implementation,system-design,walkthrough}/SKILL.md	Deletes five atomic review/product-discussion skills whose Q&A workflows, persona rules, verdict logic, and walkthrough mechanics are consolidated into drive-discussion and expanded into drive-pr-local-review persona passes.

🎯 3 (Moderate) | ⏱️ ~25 minutes

• prisma/prisma-next#479: Same documentation-level refactor of multi-persona skill conventions and consolidation/renaming of drive discussion/review skills.

"🐰
I hopped through docs anew,
Five prompts became one view,
Personas take the lead,
Orchestrator seeds,
Synthesis warms the review."

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the three main refactoring changes: generalizing discussion mode, folding review skills, and removing outdated Shape terminology.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent-personas-discussion-followup

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-runtime@479

@prisma-next/family-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/family-mongo@479

@prisma-next/sql-runtime

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-runtime@479

@prisma-next/family-sql

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/family-sql@479

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-arktype-json@479

@prisma-next/extension-cipherstash

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-cipherstash@479

@prisma-next/middleware-telemetry

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/middleware-telemetry@479

@prisma-next/mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo@479

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-paradedb@479

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-pgvector@479

@prisma-next/postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/postgres@479

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-orm-client@479

@prisma-next/sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sqlite@479

@prisma-next/target-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-mongo@479

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-mongo@479

@prisma-next/driver-mongo

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-mongo@479

@prisma-next/contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract@479

@prisma-next/utils

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/utils@479

@prisma-next/config

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/config@479

@prisma-next/errors

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/errors@479

@prisma-next/framework-components

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/framework-components@479

@prisma-next/operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/operations@479

@prisma-next/ts-render

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/ts-render@479

@prisma-next/contract-authoring

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract-authoring@479

@prisma-next/ids

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/ids@479

@prisma-next/psl-parser

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/psl-parser@479

@prisma-next/psl-printer

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/psl-printer@479

@prisma-next/cli

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/cli@479

@prisma-next/emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/emitter@479

@prisma-next/migration-tools

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/migration-tools@479

prisma-next

npm i https://pkg.pr.new/prisma/prisma-next@479

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/vite-plugin-contract-emit@479

@prisma-next/mongo-codec

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-codec@479

@prisma-next/mongo-contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract@479

@prisma-next/mongo-value

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-value@479

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract-psl@479

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-contract-ts@479

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-emitter@479

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-schema-ir@479

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-query-ast@479

@prisma-next/mongo-orm

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-orm@479

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-query-builder@479

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-lowering@479

@prisma-next/mongo-wire

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-wire@479

@prisma-next/sql-contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract@479

@prisma-next/sql-errors

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-errors@479

@prisma-next/sql-operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-operations@479

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-schema-ir@479

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-psl@479

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-ts@479

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-emitter@479

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-lane-query-builder@479

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-relational-core@479

@prisma-next/sql-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-builder@479

@prisma-next/target-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-postgres@479

@prisma-next/target-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-sqlite@479

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-postgres@479

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-sqlite@479

@prisma-next/driver-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-postgres@479

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-sqlite@479

commit: 15315ae

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/drive-discussion/SKILL.md:
- Around line 85-92: The three example blockquotes under "Example openings" (the
lines starting with "> In discussion mode with architect +
principal-engineer...", "> In discussion mode with pm...", and "> An assumption
seems to have been falsified mid-implementation...") have blank lines between
quoted lines which triggers MD028; remove the intervening blank lines so each
multi-line example is a single continuous blockquote (i.e., consecutive lines
each beginning with ">") and ensure there are no empty lines separating the ">"
lines to satisfy markdownlint.
- Around line 41-44: The SKILL.md currently contradicts itself by allowing
“silent” mid-thread persona switches in the “Cross-pollination is expected”
paragraph while also insisting persona loads be visible at every boundary (the
“Persona is the lens, not a phase…” / agent-personas library statement) — pick
one behavior and make the doc consistent: either remove or constrain the
“silent” switch language (the sentence starting with “Switch silently for the
subthread”) and replace it with an explicit visible-reload rule, or instead
update the visibility rule to allow short-lived, explicitly scoped persona
overrides (e.g., “persona overrides may be used for subthreads but must be
declared in the workflow body”) so both paragraphs align; ensure you reference
the same symbol names (`tech-lead`, “Cross-pollination is expected”, and
agent-personas) when editing so the intent is unambiguous.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 1d59f7b4-f3a6-4d74-bc1d-4f1c80e2e475

📥 Commits

Reviewing files that changed from the base of the PR and between bc5aece and 583d077.

📒 Files selected for processing (9)

• .agents/skills/drive-agent-personas/SKILL.md
• .agents/skills/drive-create-spec/SKILL.md
• .agents/skills/drive-design-discussion/SKILL.md
• .agents/skills/drive-discussion/SKILL.md
• .agents/skills/drive-pr-local-review/SKILL.md
• .agents/skills/drive-product-discussion/SKILL.md
• .agents/skills/review-implementation/SKILL.md
• .agents/skills/review-system-design/SKILL.md
• .agents/skills/review-walkthrough/SKILL.md

💤 Files with no reviewable changes (5)

• .agents/skills/review-system-design/SKILL.md
• .agents/skills/drive-product-discussion/SKILL.md
• .agents/skills/drive-design-discussion/SKILL.md
• .agents/skills/review-implementation/SKILL.md
• .agents/skills/review-walkthrough/SKILL.md