Orc Clarify

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
• Source: qGolem/orc
• License: MIT

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