Clarify - Systematic Uncertainty Resolution

Scan specifications for ambiguities and resolve them through structured questioning. Produces cleaner specs that feed into architecture and planning.

Triggers:

Auto-triggered by /opencode-specify when >3 [NEEDS CLARIFICATION] markers
Manual: /opencode-clarify to review current spec
Manual: /opencode-clarify path/to/spec.md for specific spec

Process

1. Load Specification

Find active spec:

# Most recent spec
ls -t .opencode/specs/*/spec.md | head -1

Or use provided path.

2. Extract Markers

grep -n "NEEDS CLARIFICATION" .opencode/specs/*/spec.md

Parse each marker:

Line number
Requirement ID (FR-xxx, SC-xxx, etc.)
Context (what section)
Question text

3. Scan for Implicit Ambiguities

Beyond explicit markers, scan for:

| Pattern | Example | Issue | |---------|---------|-------| | Vague adjectives | "fast", "reliable", "user-friendly" | Not measurable | | Undefined terms | "admin user", "valid input" | Domain-specific | | Missing edge cases | Only happy path defined | Incomplete | | Passive voice | "data is validated" | Who validates? When? | | Unbounded lists | "users can upload files" | What types? Size limits? |

Add discovered ambiguities to question queue.

4. Categorize Uncertainties

Group by taxonomy:

| Category | Examples | |----------|----------| | Functional scope | What features? What's excluded? | | Data model | What entities? Relationships? | | UX flows | User journey? Error states? | | Performance | Latency? Throughput? Scale? | | Integration | External systems? APIs? | | Edge cases | Limits? Errors? Recovery? | | Constraints | Budget? Timeline? Tech restrictions? | | Terminology | Domain-specific definitions? | | Completion | Definition of done? |

5. Prioritize Questions

Score each: Impact × Uncertainty

Impact: How much does this affect architecture, data model, task breakdown, or testing?
Uncertainty: How unclear is this currently?

Take top 5 questions maximum per clarify session.

6. Generate Questions

Format rules:

Multiple choice (2-5 options) preferred
If open-ended: constrain to ≤5 word answer
One question at a time
Include context from spec

Question template:

## Question 1 of 5

**Context:** FR-003 states "System MUST validate user input"

**Question:** What validation rules apply to email addresses?

**Options:**
A) RFC 5322 strict validation
B) Simple format check (contains @ and .)
C) Format check + DNS MX record verification
D) Custom business rules (please specify)

**Impact:** Affects error messages, test cases, and integration complexity.

7. Apply Answers Immediately

After each answer:

Update spec.md - replace marker with resolved requirement
Log to .opencode/specs/{slug}/clarifications/log.md

Before:

- FR-003: System MUST validate email [NEEDS CLARIFICATION: validation rules]

After:

- FR-003: System MUST validate email format (RFC 5322) and verify domain has MX record

Clarification log entry:

## 2025-01-29: Email Validation Rules

**Question:** What validation rules apply to email addresses?
**Answer:** RFC 5322 + MX verification (Option C)
**Updated:** FR-003
**Rationale:** Balance strictness with user experience, catch typos in domain

8. Track Coverage

After all questions answered, report coverage:

## Clarification Summary

| Category | Status |
|----------|--------|
| Functional scope | Resolved |
| Data model | Resolved |
| UX flows | Outstanding (1 marker) |
| Performance | Clear |
| Integration | Deferred |
| Edge cases | Resolved |
| Constraints | Clear |
| Terminology | Resolved |
| Completion | Clear |

**Remaining markers:** 1
**Ready for architecture:** Yes (≤3 markers)

Question Patterns

Multiple Choice (Preferred)

**Question:** How should the system handle failed payment attempts?

A) Retry automatically up to 3 times
B) Notify user immediately, no retry
C) Queue for manual review
D) Combination (specify)

Constrained Open-Ended

**Question:** Maximum file upload size? (≤5 words)

Example answers: "10MB", "50MB per file", "No limit"

Binary with Justification

**Question:** Should inactive users be auto-deleted?

A) Yes - after [specify duration]
B) No - keep indefinitely

If yes, what defines "inactive"?

Handling Technical Uncertainties

Some markers are technical (HOW, not WHAT). Don't resolve these in clarify.

Technical markers → arch-lead:

[NEEDS CLARIFICATION: which database?]
[NEEDS CLARIFICATION: sync or async processing?]
[NEEDS CLARIFICATION: API design]

Flag for arch-lead:

## Technical Uncertainties (for Architecture)

These require technical research, not stakeholder input:

1. FR-015: Processing approach (sync/async) - arch-lead to evaluate
2. NFR-003: Database selection based on scale requirements

Deferral

Some questions can't be answered yet. Mark as deferred:

- FR-020: System MUST integrate with payment provider [DEFERRED: vendor selection pending]

Deferred items:

Don't block spec completion
Must have clear unblock condition
Tracked in clarification log

Completion Criteria

Clarify session complete when:

All explicit markers addressed (resolved or deferred)
No implicit ambiguities in P1 scenarios
Coverage summary shows no Outstanding in critical categories
Remaining markers ≤ 3 (threshold for arch-lead handoff)

Output

Updates to:

.opencode/specs/{slug}/spec.md - markers replaced with answers
.opencode/specs/{slug}/clarifications/log.md - decision history

Commit changes:

git add .opencode/specs/{slug}/
git commit -m "clarify: resolve {N} uncertainties in {slug}"

Constraints

Maximum 5 questions per session (avoid fatigue)
Multiple choice whenever possible
Open-ended answers ≤5 words
Update spec immediately after each answer
Never resolve technical uncertainties (arch-lead's job)
Always log decisions with rationale