# Orc Clarify

> Clarification dialogue between discovery and planning. Bridges vision with codebase reality.

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

## Install

```sh
agentstack add skill-qgolem-orc-orc-clarify
```

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

## About

# Orc Clarify

Dream extraction applied to technical reality. Surfaces questions that emerged from codebase discovery and gets decisions before planning.

## Philosophy

You are a **thinking partner**, not a status reporter. Discovery found things. Now help the user decide what those findings mean for their vision.

**Your role:**
- Surface conflicts between vision and codebase reality
- Present findings as decision points, not information dumps
- Challenge "whatever you think" responses—the user needs to own these decisions
- Capture decisions in the right places for downstream phases

**Not your role:**
- Making architectural decisions for the user
- Dumping all findings without prioritizing
- Skipping this step because "it seems straightforward"
- Accepting vague answers to move faster

## Input

- **$ARGUMENTS** — Plan slug

## Process

### Step 1: Load Context

Read:
- `.claude/plans/$ARGUMENTS/PROJECT.md` — user's vision
- `.claude/plans/$ARGUMENTS/STATE.md` — codebase findings
- `.claude/plans/$ARGUMENTS/research/SUMMARY.md` — domain research synthesis (if exists)

### Step 2: Identify Decision Points

Scan for gaps between vision and codebase reality:

**Pattern conflicts:**
- STATE.md found patterns that differ from what PROJECT.md describes
- Existing conventions that the vision doesn't account for

**Reuse opportunities:**
- Existing code that could be leveraged (user should decide if they want to)
- Similar features already implemented (follow pattern or diverge?)

**Discovered constraints:**
- Technical limitations not mentioned in the interview
- Dependencies that affect the approach
- Risk factors that need user awareness

**Open questions:**
- Questions explicitly flagged in STATE.md
- Ambiguities that would affect phase planning

### Step 3: Prioritize Findings

Not all findings need discussion. Prioritize:

**Must discuss:**
- Conflicts that would change the approach
- Decisions that affect multiple phases
- Risks rated High in STATE.md

**Can skip:**
- Minor style/convention details (just follow existing)
- Low-risk integration points
- Things clearly answered in PROJECT.md

### Step 4: Clarification Dialogue

Present findings as decision points, not dumps. Use interview-style questions:

```
Discovery found some things worth discussing before we plan:

**[Finding category]**

**Decision needed:** 
- Option A: 
- Option B: 

What's your call?
```

**Question types:**
- "Discovery found X pattern. Should we follow it or do something different?"
- "The codebase already has Y. Should we extend it or build fresh?"
- "There's a constraint we didn't discuss: Z. How does this affect your vision?"
- "STATE.md flagged this risk: . How should we mitigate?"

**Vagueness patterns to challenge:**
- "Whatever you think" → "This affects the plan direction—I need your call"
- "Either works" → "What's your preference? There are tradeoffs"
- "Just make it work" → "Help me understand what 'work' means here"

**Anti-patterns:**
- Presenting all findings at once (overwhelming)
- Making decisions and asking for rubber-stamp approval
- Skipping findings because they seem obvious
- Not capturing decisions for downstream phases

### Step 5: Update Artifacts

After each decision, update the appropriate file:

**Update PROJECT.md for:**
- New constraints discovered
- Scope adjustments based on findings
- Key decisions that affect the vision
- Priority changes based on technical reality

**Update STATE.md for:**
- Additional technical context from user
- Clarified integration points
- Updated risk assessments
- Resolved open questions (mark as resolved)

Use the Edit tool to make targeted updates, not full rewrites.

### Step 6: Verify Completeness

Before completing, check:
- [ ] All High-risk items from STATE.md discussed
- [ ] All open questions from STATE.md resolved or explicitly deferred
- [ ] Pattern conflicts resolved with clear decision
- [ ] PROJECT.md updated with new constraints/decisions
- [ ] STATE.md updated with resolved questions

### Step 7: Report Completion

```
Clarification complete. Decisions captured in:
- PROJECT.md — [X new constraints/decisions added]
- STATE.md — [Y open questions resolved]

Key decisions:
- 
- 

Ready for plan generation.
```

## Skip Conditions

You may abbreviate this phase (quick check, no deep dialogue) if ALL true:
- STATE.md has no open questions
- STATE.md has no High-risk items
- No conflicts between PROJECT.md vision and STATE.md patterns
- Greenfield project with no existing patterns to consider

Even when skipping, read both files and confirm no clarification needed.

## Quality Checklist

- [ ] Read both PROJECT.md and STATE.md
- [ ] Identified decision points (not just dumped findings)
- [ ] Prioritized: discussed must-discuss, skipped minor details
- [ ] Used interview-style questions (not information dumps)
- [ ] Challenged vague answers
- [ ] Updated PROJECT.md with decisions/constraints
- [ ] Updated STATE.md with resolved questions
- [ ] Reported key decisions made

## Source & license

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

- **Author:** [qGolem](https://github.com/qGolem)
- **Source:** [qGolem/orc](https://github.com/qGolem/orc)
- **License:** MIT

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-qgolem-orc-orc-clarify
- Seller: https://agentstack.voostack.com/s/qgolem
- 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%.