clarify

What this skill does

# Clarify Skill

Resolve ambiguities by updating documents directly with tracked changes. Context-aware: adapts to scopes, code reviews, or standalone use.

---

## When to Use

**Use for:**
- Resolving markers before implementation (especially for Initiatives)
- Clarifying ambiguous requirements discovered post-validation
- Addressing gaps identified in ambiguity_scan
- Resolving questions from code review findings
- Any interactive clarification with audit trail

**Don't use for:**
- Initial validation (handled during `/scope` creation)
- Changing fundamental scope (re-run `/scope`)

---

## Context Detection

The skill auto-detects context based on what's available:

| Context | Detection | Source |
|---------|-----------|--------|
| **Scope** | `./scopes/*/*/validation.yaml` exists | ambiguity_scan + markers |
| **Code Review** | Recent `~/.claude/reviews/*.md` | Review issues/questions |
| **Standalone** | Neither above | User-provided questions |

---

## Workflow

### Step 1: Load and Scan

**Scope context:**
1. Find scope in `./scopes/*/*/` (lifecycle dirs: `draft`, `active`, `done`)
2. Read `validation.yaml` from scope directory
3. Run ambiguity scan:
   - Check `ambiguity_scan` section for areas with `status: partial` or `status: missing`
   - These become clarification candidates alongside open markers
4. Collect open markers where `status: open`
5. Merge candidates: ambiguity gaps + open markers (deduplicate by area)
6. If no candidates: report "No unresolved items" and exit

**Code review context:**
1. Find most recent review in `~/.claude/reviews/`
2. Extract issues marked as needing clarification
3. Present as candidates

**Standalone:**
1. Ask user what needs clarification
2. Proceed with interactive Q&A

### Step 2: Present Candidates

For each candidate (prioritized by impact), use AskUserQuestion:

```
Header: ${AREA}
Question: ${DESCRIPTION}
multiSelect: false
Options:
- [Generated options based on context]
- Defer: Skip for now
```

**Prioritization:** Scope > Behavior > Data Model > Constraints > Edge Cases > Integration > Terminology

### Step 3: Update Documents Directly

When a clarification is resolved, update the relevant section in the source document:

| Clarification Area | Target Document | Target Section |
|--------------------|-----------------|----------------|
| Scope | scope.md | Requirements, Scope |
| Behavior | scope.md | Requirements, Behavior |
| Data Model | scope.md | Data Model |
| Constraints | scope.md | Constraints |
| Edge Cases | scope.md | Edge Cases |
| Integration | scope.md | Integration Points |
| Terminology | scope.md | Terminology |

**Update approach:**
1. Read the target section
2. Integrate the clarification naturally into existing content
3. Do NOT create a separate "## Clarifications" section

### Step 4: Record Clarification Session

Create a new session entry in `clarification_sessions`:

```yaml
clarification_sessions:
  - id: S00${N}
    timestamp: ${ISO_TIMESTAMP}
    source: clarify  # or scope-review, code review if invoked from there
    questions:
      - id: Q001
        question: "${QUESTION}"
        answer: "${ANSWER}"
        area: ${TAXONOMY_AREA}
        doc_updates:
          - file: scope.md
            section: Requirements
            action: modified
```

**doc_updates** tracks exactly which files/sections changed for audit trail.

### Step 5: Update Ambiguity Scan Status

For each resolved clarification from ambiguity gaps:

1. Update `ambiguity_scan.${area}.status` to `clear`
2. Remove the resolved gap from `ambiguity_scan.${area}.gaps`

### Step 6: Update Markers

For each resolved marker:

1. Change `status: open` to `status: resolved`
2. Add `resolution: "${USER_ANSWER}"`

### Step 7: Re-check Gates (Initiatives Only)

For Initiative scopes:

1. Re-evaluate gates in validation.yaml
2. Update gate status if resolution changes assessment
3. Report gate status

---

## Doc Update Mapping

| Source | Target File | Target Section |
|--------|-------------|----------------|
| Scope gap | scope.md | ## Requirements or ## Scope |
| Behavior gap | scope.md | ## Requirements / Behavior subsection |
| Data Model gap | scope.md | ## Data Model |
| Constraints gap | scope.md | ## Constraints |
| Edge Cases gap | scope.md | ## Edge Cases |
| Integration gap | scope.md | ## Integration Points |
| Terminology gap | scope.md | ## Terminology |

---

## Example Session

```
[Load validation.yaml]
[Run ambiguity scan]
- scope: partial (1 gap)
- data_model: missing (2 gaps)
[Check markers]
- M001 (Constraints): open

Candidates:
1. Scope: "User role boundaries unclear"
2. Data Model: "Schema for notifications not defined"
3. Data Model: "Retention policy not specified"
4. Constraints: "Authentication method not specified"

---
Header: Scope
Question: What user roles exist and what are their boundaries?

Options:
- Admin/User: Two-tier with admin full access
- Role-based: Granular permissions per feature
- Defer: Skip for now

User selects: Admin/User

[Update scope.md#requirements]
Added: "Two-tier role system: Admin (full access), User (standard permissions)"

[Record session]
clarification_sessions:
  - id: S001
    timestamp: 2025-01-15T10:30:00Z
    source: clarify
    questions:
      - id: Q001
        question: "What user roles exist and what are their boundaries?"
        answer: "Two-tier: Admin (full access), User (standard permissions)"
        area: scope
        doc_updates:
          - file: scope.md
            section: Requirements
            action: modified

[Update ambiguity_scan]
scope:
  status: clear
  gaps: []

---
Header: Constraints
Question: Which authentication method should be used?
...
```

---

## Integration

**Command:** `/clarify [context]`

**Invoked from:**
- `scope` - Clarify during scope creation or review
- `code review` - Clarify code review findings
- `implement` - Resolve blocking markers before execution

**Related skills:**
- `scope` - Creates scopes with ambiguity_scan and markers
- `implement` - Checks for blocking markers before execution