# Clarification Gate

> Use when a new goal, feature request, migration, or non-trivial change needs focused clarification before PRD, spec, plan, or implementation work begins.

- **Type:** Skill
- **Install:** `agentstack add skill-yipxiyi-openarc-clarification-gate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Yipxiyi](https://agentstack.voostack.com/s/yipxiyi)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Yipxiyi](https://github.com/Yipxiyi)
- **Source:** https://github.com/Yipxiyi/OpenArc/tree/main/skills/clarification-gate
- **Website:** https://github.com/Yipxiyi/OpenArc

## Install

```sh
agentstack add skill-yipxiyi-openarc-clarification-gate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Clarification Gate

Use this skill before product, spec, planning, or implementation work when the request is new, broad, ambiguous, risky, or likely to affect multiple files or governance surfaces.

## Goal

Turn an unclear request into a decision-ready handoff without creating a new documentation program.

The gate should decide:

- what the user wants
- what is out of scope
- which facts are already known from the repository
- which assumptions are risky
- which source-of-truth docs should carry the result
- whether implementation can start

## Workflow

1. Inspect existing repository evidence before asking questions:
   - README and package metadata
   - agent guide
   - `docs/PROJECT_BRIEF.md`
   - `docs/CODE_STYLE.md`
   - `docs/PRD.md`
   - `docs/SPEC.md` or latest `docs/specs/*`
   - `docs/DESIGN.md` only for UI, frontend, desktop, mobile, or component work
   - `docs/BRAND.md` only for public brand, naming, marketing, identity, or copy work
   - `docs/TASKS.md`
   - `docs/CHANGELOG_AI.md`
   - relevant source files, tests, assets, or configs
2. Separate:
   - known facts
   - unknowns
   - contradictions
   - risky assumptions
   - reusable existing systems
3. Ask only material questions that cannot be answered from repository evidence.
4. Produce a short clarification handoff.
5. Route the work to the smallest next OpenArc workflow:
   - `product-governance` when product intent or scope must be captured
   - `spec-workflow` when behavior, acceptance criteria, or compatibility must be specified
   - `planning-engine` when implementation order, validation, or migration needs structure
   - `repository-governance` or `workspace-migration` when setup or migration is the real task
   - direct implementation only when scope, constraints, and validation are already clear

## Question Budget

Default budget: ask at most 5 questions.

Allowed range: 3-7 questions when the request genuinely needs more or less.

Each question must:

- change the implementation or documentation result
- include a recommended answer
- state the trade-off behind that recommendation
- avoid asking for facts that can be discovered from the repository

If confidence is high enough to proceed, record remaining ambiguity under `Open Questions` in the target PRD, spec, or plan instead of blocking all work.

## Handoff Shape

Use this structure in the conversation, or paste it into the target PRD, spec, or plan when the repository keeps persistent docs:

```markdown
## Clarification Gate

- Goal:
- Non-goals:
- Audience / users:
- Constraints:
- Known facts:
- Unknowns:
- Risky assumptions:
- Decisions:
- Target docs:
- Implementation readiness:
```

`Implementation readiness` must be one of:

- `ready`: implementation can begin after updating the stated docs
- `needs PRD`: product intent or scope is not stable enough
- `needs spec`: behavior, acceptance criteria, or compatibility is not stable enough
- `needs plan`: implementation order, migration, rollback, or validation is not stable enough
- `blocked`: a material user or external decision is required

## Documentation Targets

Prefer existing OpenArc documents over new document families:

- Product intent, audience, goals, and non-goals -> `docs/PRD.md`
- Behavior, compatibility, acceptance criteria, and feature scope -> `docs/SPEC.md` or `docs/specs/*`
- Implementation sequence, validation, rollback, and migration -> `docs/plans/*`
- Active execution status -> `docs/TASKS.md`
- Recent AI-assisted changes and decisions -> `docs/CHANGELOG_AI.md`
- Code conventions and guardrails -> `docs/CODE_STYLE.md`
- UI implementation rules -> `docs/DESIGN.md`

Do not create `docs/intake/` or another permanent intake tree by default.

## Decision Records

Do not default to ADRs.

Prefer the existing PRD, spec, plan, task, changelog, code-style, or design document that already owns the decision.

Only suggest an ADR when all of these are true:

1. The decision is hard to reverse.
2. The choice will look surprising without context.
3. Real alternatives were considered and rejected for specific reasons.

If the repository already has an ADR convention, follow it. Otherwise, ask before creating `docs/adr/`.

## Rules

- Do not implement during the clarification gate.
- Do not create PRD, design, brand, or ADR documents just because the gate ran.
- Do not ask unlimited interview questions.
- Do not import third-party skills as core dependencies.
- Reuse existing repository vocabulary, but challenge overloaded terms when they would change the work.
- Treat script, CLI, automation, library, and docs-only repositories as non-UI unless the repository or user request shows UI, visual, or brand signals.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Yipxiyi](https://github.com/Yipxiyi)
- **Source:** [Yipxiyi/OpenArc](https://github.com/Yipxiyi/OpenArc)
- **License:** MIT
- **Homepage:** https://github.com/Yipxiyi/OpenArc

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yipxiyi-openarc-clarification-gate
- Seller: https://agentstack.voostack.com/s/yipxiyi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.