// Full execution protocol for MODE: CLARIFY -- structured clarification funnel with critic review before surfacing user decisions.
Guidelines for safe subprocess calls in opencode-swarm. Load before adding, modifying, or reviewing any file that calls spawn, spawnSync, bunSpawn, or child_process. Covers the six required properties, Windows portability, _internals DI seam pattern, and verification grep.
Guidelines for writing, organizing, and maintaining tests in the opencode-swarm repository. Covers framework rules (bun:test), mock isolation, CI pipeline structure, file placement, and anti-patterns that break cross-platform CI. Load this skill before writing or modifying any test file.
Apply when converting test files from mock.module('node:child_process') to _internals DI seam pattern. Guides the complete migration: adding spawnSync/_internals to source files, converting test files, adding proper beforeEach/afterEach save/restore lifecycle, mockReset() cleanup, and temp directory cleanup. Prevents mock.module leaks across Bun's shared test-runner process.
Full execution protocol for MODE: PLAN -- plan creation, external plan ingestion, QA gate persistence, task granularity, and traceability checks.
Full execution protocol for MODE: BRAINSTORM -- structured discovery dialogue, approach selection, spec drafting, QA gate selection, and transition handling.
Full execution protocol for MODE: CLARIFY-SPEC -- resolving spec clarification markers and maintaining spec/planning alignment.
| name | clarify |
| description | Full execution protocol for MODE: CLARIFY -- structured clarification funnel with critic review before surfacing user decisions. |
This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.
Ambiguous request → Run the clarification funnel Clear request → MODE: DISCOVER
Before surfacing any clarification question to the user, the architect MUST run this four-stage funnel. The goal is to limit unnecessary user interruption, not planning completeness.
Identify ALL uncertainties that could affect:
There is NO hard cap on the internal inventory. Record every material uncertainty found.
Classify each item as exactly one of:
self_resolved: answered from the user request, spec, plan, codebase reality check, .swarm/context.md, repo conventions, or an informed default. If the default is not directly supported by user request, spec, or recorded context, classify as user_decision rather than self_resolved.critic_resolved: sent to Critic Sounding Board and resolved by the critic.research_needed: needs SME/explorer/domain lookup before user escalation.user_decision: only the user can decide because it affects product scope, risk tolerance, policy, budget, UX, rollout, or destructive behavior.deferred_nonblocking: useful follow-up detail that does not block a correct initial plan and can be explicitly recorded as an assumption or follow-up.Before asking the user any clarification question, the architect MUST consult critic_sounding_board with the candidate question set and context.
For each item classified as research_needed or user_decision in Stage 2, send it to the critic. The critic responds with a verdict from SoundingBoardVerdict (see src/agents/critic.ts). The mapping between critic verdicts and funnel actions is:
| Critic Verdict (SoundingBoardVerdict) | Funnel Action | Meaning |
|---|---|---|
UNNECESSARY | DROP | Item is unnecessary or answerable from existing context |
RESOLVE | RESOLVE | Critic supplies the answer or recommended default |
REPHRASE | REPHRASE | Question is valid but should be clearer, narrower, or grouped |
APPROVED | ASK_USER | User decision is genuinely required |
Hard constraint: Items in the Always-Surface Categories list (below) MUST NOT receive UNNECESSARY/DROP from the critic — only REPHRASE or APPROVED/ASK_USER are allowed. If the critic attempts to UNNECESSARY/DROP an always-surface item, override to APPROVED/ASK_USER.
Overconfidence guard: If the critic attempts to self-resolve an item by supplying an answer (verdict RESOLVE) but the underlying default is not directly supported by user request, spec, or recorded context, the architect MUST classify the item as user_decision rather than self_resolved. Unsupported defaults must not be silently accepted.
Update classifications based on critic response:
UNNECESSARY/DROP → reclassify as self_resolved and record the reason.RESOLVE → reclassify as critic_resolved and record the answer as an assumption.REPHRASE → update the question wording and keep as candidate.APPROVED/ASK_USER → confirm as user_decision.Record all resolved items as explicit assumptions before proceeding.
If any items remain classified as user_decision after Stage 3, present them as a structured decision packet — NOT as an arbitrary subset.
The packet MUST include for each decision:
The architect MAY ask questions one at a time in interactive mode, but MUST preserve and report the full unresolved list. The architect MUST NOT drop unresolved decisions because of a session question cap.
The critic may improve wording or confirm prior context, but these categories MUST be surfaced to the user unless already explicitly answered by the user or by recorded context:
All items resolved in Stages 2-3 (self_resolved, critic_resolved, deferred_nonblocking) MUST be recorded as explicit assumptions in the spec, plan, or .swarm/context.md. Silently dropping resolved uncertainties is a protocol violation — every uncertainty that entered the funnel must have a recorded outcome.