| name | clarity-council |
| description | Facilitates structured single-persona or multi-persona consultation for strategy, product, engineering, operations, and risk decisions. Use when the user requests a council, multiple perspectives, persona advice, tradeoff analysis, or iterative clarification and debate. |
| codex-short-description | Facilitates structured single-persona or multi-persona consultation for strategy… |
| related-skills | ["grill-me","idea-generate"] |
| loop-eligible | false |
| recurrence-hint | on-demand |
| compatibility | claude-code codex opencode |
Clarity Council
Structured persona-based consultation for decisions that benefit from expert perspectives. The
council runs entirely inline in one of three modes — nothing depends on a separate subagent, so
it behaves identically on every host.
Persona contracts live in the shared skills/persona/ category — the index is
skills/persona/PERSONAS.md and pre-made panels are in
skills/persona/GROUPS.md. Links below are relative to this skill's
folder.
When to use
Use this skill when you need any of:
- Quick expert opinion from one persona
- Multiple expert viewpoints with synthesis
- Iterative decision-making with clarifications
- Structured tradeoff analysis
Do not use for pure factual lookup with no decision component.
Which mode?
| Mode | When | Feel |
|---|
| single | Focused advice from one expert | Quick (10–15 min) |
| multi | A decision needs several viewpoints synthesized | Standard (20–30 min) |
| iterative | Multi-turn refinement as constraints emerge | Deep (30–60 min, 3–5 turns) |
Callers select a mode explicitly. A skill invoking the council via Skill names the mode
(e.g. "invoke clarity-council in multi mode with personas [psychologist, personal-assistant]").
Users can say "as a senior-architect…" (single), "convene a council on…" (multi), or "run a council,
I'll iterate" (iterative).
Common inputs
- Decision/problem — required.
- Personas — optional; which experts to consult (defaults apply per mode).
- Persona groups — optional; pre-made panels from
skills/persona/GROUPS.md.
- Depth — optional:
brief / standard / deep.
- Context / constraints / desired outcome — optional but strongly recommended.
- Iterative state — for multi-turn sessions (sessionId, turn, history).
Resolving a persona name (two steps, see skills/persona/PERSONAS.md):
first look for skills/persona/<name>.md and use its Decision Lens, Preferred Frameworks,
and Blind Spots (most personas live here). If there's no such file, the name is a hands-on
specialist skill that doubles as a voice (data-engineer, devops-engineer, technical-writer) —
read its ## Council Persona Lens section, which is the persona contract (the rest of that skill is
implementation guidance). Keep terminology consistent with the names in
skills/persona/PERSONAS.md.
Mode: single
Deliver focused expert perspective from one persona. If no persona is named, ask which
perspective would help most.
Workflow
- Confirm the persona. Resolve its lens per the two-step rule above (local file, else the
top-level specialist skill of that name).
- Understand the problem. Ask a clarifying question only if a hard constraint (state, decision,
budget/timeline/compliance, definition of success) is ambiguous.
- Apply the lens. Frame the analysis through the persona's Decision Lens and Preferred
Frameworks (e.g. senior-architect → structural/scalability impact; security-expert → attack
surface/compliance; devils-advocate → challenge the obvious).
- Produce structured advice (template below).
- Quality checks: advice tied to the persona's focus (not generic); assumptions separated from
facts; at least one concrete next step; confidence justified; blind spots flagged where they matter.
If the user then wants multiple perspectives → switch to multi; back-and-forth refinement →
iterative.
Single-persona output
summary: <short answer>
advice:
- <point>
assumptions:
- <assumption>
questions:
- <question>
next_steps:
- <action>
confidence: <low|medium|high>
Mode: multi
Convene several personas, collect each perspective, then synthesize. Synthesis is mandatory —
do not just list opinions.
Default panels (if no personas named; ask if the panel doesn't fit):
- Architecture — senior-architect, senior-developer, qa-engineer, tech-lead, devops-engineer, devils-advocate
- Feature/product — product-owner, senior-developer, ux-designer, customer-advocate, tech-lead, devils-advocate
- Hiring/people — culture-lead, product-owner, senior-architect, devils-advocate
- Risk/security — security-expert, compliance-officer, senior-architect, devops-engineer, devils-advocate
- Financial/business — financial-officer, product-owner, business-owner, devops-engineer, devils-advocate
- Estimation — scrum-master, tech-lead, senior-developer, qa-engineer
Pre-made groups also live in skills/persona/GROUPS.md — domain panels
(product-delivery-core, platform-and-reliability, investigation-and-diagnosis,
stakeholder-reporting, …) plus convenience archetypes (technical-focus, stakeholder-focus,
full-council, quick-pulse, estimation). Reference a group by its slug; expand it into its listed
personas before consulting.
Workflow
- Classify & prepare. Confirm the problem; load/expand personas; dedupe, preserve requested order.
- Consult each persona using the single-mode method. Collect all responses before
synthesizing — do not synthesize as you go.
- Synthesize across five dimensions: Cost vs Speed · Risk vs Reversibility · Short-term vs
Long-term · Confidence (evidence vs assumption) · People Impact.
- Agreements — where two or more personas converge (strong evidence).
- Conflicts — name the dimension ("they disagree on reversibility", not "they disagree") and
give each a decision table.
- Risks & tradeoffs — what could go wrong; what the user is choosing between; underweighted
blind spots.
- Next steps — 2–4 concrete actions that reduce ambiguity or resolve conflicts.
- Quality checks: agreements separated from conflicts; every conflict has a dimension + table;
next steps concrete; blind spots acknowledged.
If the user needs iterative back-and-forth → switch to iterative; a single perspective needs a
deeper dive → single.
Multi-persona output
responses:
- persona: <name>
summary: <short answer>
advice:
- <point>
assumptions:
- <assumption>
questions:
- <question>
next_steps:
- <action>
confidence: <low|medium|high>
synthesis:
agreements:
- <point>
conflicts:
- dimension: <Speed|Reversibility|Risk|People|Confidence>
table: |
| Option | Benefit | Risk | Who Favors |
| --- | --- | --- | --- |
| A | ... | ... | ... |
| B | ... | ... | ... |
decision_point: <one-line question that resolves this conflict>
risks_tradeoffs:
- <point>
next_steps:
- <action>
Mode: iterative
Run a multi-turn session: ask targeted clarifications, re-consult the council (multi-mode) with
updated constraints, resolve conflicts, and refine toward a decision. Slower, but catches edge cases
and hidden assumptions.
Session state carried each turn: sessionId, turn, history (compact per-turn summaries),
personas_active, conflicts_open.
Workflow
- Turn 1 — initialize: load personas (or ask which panel); classify the problem; ask one
clarifying question if ambiguity is high; return
needs_clarification or in_progress.
- Turn 2+ — iterate: read the user's answer; update
history; re-consult the council (multi mode)
with new constraints; check conflicts; return needs_clarification, in_progress, or completed.
- Conflict Protocol (mandatory when personas clash): name the dimension → present a 2–3 option
decision table → ask one targeted question → record the decision in
history → continue with
that constraint locked in.
- Turn limit: 5–7. Beyond that, suggest narrowing the decision, external stakeholder input, or a
prototype/experiment.
Notes: one question per turn; state carries forward (never make the user repeat constraints);
this surfaces options and tradeoffs — the user decides.
Iterative output
status: <needs_clarification|in_progress|completed>
message: <short user-facing response>
nextAction: <what is needed next>
output:
<single- or multi-persona structure for this turn>
state:
sessionId: <id>
turn: <number>
decisions_made:
- <decision>: <rationale>
conflicts_open:
- <unresolved conflict>
history:
- <compact turn summary>
Quality checks (all modes)
Before finalizing:
- recommendations tie to stated constraints
- assumptions separated from facts
- at least one concrete next step
- at least one explicit risk or tradeoff for non-trivial decisions
- terminology consistent with the persona names in
skills/persona/PERSONAS.md
Reference files
Host portability: tool names in this skill follow Claude Code conventions; on other hosts
(Codex, opencode) map them by intent — see PORTABILITY.md.
Self-Evolve Loop
This skill learns across invocations — the full contract is
SELF-EVOLVE.md. Start: read the learnings
journal — ~/.ink-and-agency/learnings/clarity-council.md and/or the workspace-local
.ink-and-agency/learnings/clarity-council.md — if present, and apply its guidance.
End: self-evaluate the results; optionally ask the user for feedback (never
block on it); append signal-bearing learnings to the journal (user-global when
the sandbox allows writing there, workspace-local otherwise); route
skill-improvement ideas per the contract's tiers — edit the canonical source
when one is present, never the plugin cache.
