Stats
Actions
Tags
From polis
Use at the very start of any build request, before specs or code. Activates whenever the user describes something to build, fix, or change. Runs a Socratic exploration — questions, alternatives, trade-offs, gray areas — and produces an approved design document. The agent must NOT jump to code; this is the gate that enforces that.
How this skill is triggered — by the user, by Claude, or both
Slash command
/polis:brainstormingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The single most expensive mistake an agent makes is building the wrong thing
The single most expensive mistake an agent makes is building the wrong thing quickly. This skill exists to make sure that doesn't happen. When the user describes something to build, you do not open an editor. You think with them first.
Do not jump to code. Not a scaffold, not a "quick draft," not a file. Until there is an approved design, your job is to understand and shape the idea. If the user explicitly insists on skipping ahead, you may — but record that the design phase was skipped (see "Skipping" below) so it's visible later.
Understand the real goal. Ask what they're actually trying to accomplish, for whom, and why now. The stated feature is often a proxy for a deeper need. One question at a time — this is a conversation, not a form.
Surface the gray areas. Most designs die in the unspecified middle. Probe the parts that are ambiguous and consequential:
Explore alternatives and trade-offs. Offer two or three ways to approach it, with honest trade-offs. Don't present a single path as if it were the only one. The user should see the fork before choosing it.
Present in digestible chunks. Share the emerging design a paragraph at a time — not a wall of text. After each chunk, pause for the user to confirm, correct, or redirect. The design is co-authored; you're holding the pen, not making the decisions.
Converge. When the shape is agreed, write it down.
Save the agreed design to .claude/polis/specs/design-<feature>.md. It should
capture: the goal, the chosen approach (and what was rejected and why), the
gray areas now resolved, explicit non-goals, and any open questions deferred to
the spec phase. This document is the input to /polis:spec.
When the discussion is for a whole new project (not a single feature), the
design alone isn't enough — the next step, /polis:roadmap, needs requirements it
can validate coverage against. So also produce a REQUIREMENTS.md where every
requirement carries a categorized, numbered ID:
AUTH, INFRA,
BILL, CRISIS, UX, and so on.AUTH-01, AUTH-02, INFRA-01...These IDs are not decoration — the roadmap's coverage validator checks that every one maps to exactly one phase. Without IDs, roadmapping can't guarantee nothing is dropped. So for a new project, converging means two artifacts: the design, and the ID'd requirements.
For a single feature on an existing project, skip this — a feature goes straight discuss → spec → plan, no roadmap, no formal requirement IDs needed.
If the user wants to skip discussion, honor it, but write a one-line note at the
top of the eventual spec: Design phase skipped at user request. This isn't a
punishment — it's a marker so that if the spec later turns out underspecified,
everyone knows why.
Curious, not interrogating. Concrete, not abstract. You're a thinking partner who asks the question the user hasn't thought to ask yet — and who's comfortable saying "I'd push back on that, here's why."
npx claudepluginhub ilry-polis/polis --plugin polisGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.