# clarify

clarify turns an underspecified coding request into an actionable implementation plan, adjusting its analysis depth to the task and investigating the codebase when uncertainty persists.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 196
- Author: mag123c
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/mag123c/toktrack/tree/HEAD/.claude/skills/clarify/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/clarify

## What it does

clarify helps an agent establish what a coding task actually requires before implementation. For small changes, it asks targeted questions, defines the scope, and records success criteria. More involved work triggers parallel codebase exploration, an evolving requirements draft, and further analysis until critical unknowns are resolved.

The skill writes `.dev/specs/{name}/DRAFT.md` and `.dev/specs/{name}/PLAN.md`, while architecture choices and trade-offs go into `.dev/DECISIONS.md`. The final plan must describe test-based verification and specify `/implement` as the implementation skill. Once the plan is presented in the conversation, the agent invokes `/implement` immediately rather than entering plan mode. The workflow expects `.claude/ai-context/architecture.md` and `.claude/ai-context/conventions.md` as context files; unresolved scope after three rounds of questions triggers the deeper path.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mag123c/toktrack --skill clarify -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/clarify/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/clarify/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mag123c/toktrack --skill clarify -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/clarify/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mag123c/toktrack --skill clarify -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/clarify/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mag123c/toktrack clarify
```

2. **Manually: put the files in place**
- File: `.github/skills/clarify/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mag123c/toktrack --skill clarify -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mag123c/toktrack --path .claude/skills/clarify
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/clarify/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mag123c/toktrack --skill clarify -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/mag123c/toktrack/tree/HEAD/.claude/skills/clarify/SKILL.md

## When to use it
- Turn an unclear feature request into defined requirements
- Investigate a codebase before planning cross-module changes
- Compare architecture options and record the rationale
- Capture assumptions and unresolved questions before coding
- Create an implementation plan with test-based verification

## Example prompts
- Clarify the requirements for this feature and prepare an implementation plan.
- Investigate how to change the database schema without breaking the API, then prepare the plan.
- Help choose an architecture for this change, record the decisions in `.dev/DECISIONS.md`, and prepare the plan for `/implement`.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 450febffe51008c1.

BEGIN THIRD-PARTY FILE 450febffe51008c1
````text
---
name: clarify
description: |
  Adaptive requirements clarification with auto-depth routing.
  Shallow (Q&A) for simple tasks, Deep (exploration + DRAFT + PLAN) for complex ones.
  Escalates automatically when ambiguity persists.
required_context:
  - .claude/ai-context/architecture.md
  - .claude/ai-context/conventions.md
allowed-tools:
  - Read
  - Grep
  - Glob
  - Task
  - Write
  - AskUserQuestion
---

# /clarify — Adaptive Requirements Clarification

## Chain (MUST)
| Previous | Current | Next |
|----------|---------|------|
| Session start | /clarify | Present PLAN inline → /implement |

## Core Model

```
/clarify → Measure complexity → Clear enough?
                                ├─ Yes → Present PLAN inline → /implement
                                └─ No  → Deeper clarify (explore, analyze, DRAFT...)
                                         → Re-measure → Repeat
```

Exit condition: **"Is this enough info to implement?"** — Critical Unknown=0 + remaining items are made visible (Provenance).

---

## Reference Files (load as needed — chaining)

| When | File |
|------|------|
| Tagging provenance on key decisions/assumptions / probe decisions | `references/provenance.md` |
| Pre-PLAN user confirmation | `references/checkpoint.md` |
| When document authority/reading order is unclear | `references/doc-roles.md` |
| Full Deep path procedure | `deep/DEEP.md` |
| PLAN/DRAFT structure (Lite/Full + Clarify Verdict) | `templates/` |

> Inline essentials only: **probe-don't-tag** (if cheaply verifiable, measure instead of tagging), **PLAN=intent · WRAP/DECISIONS=fact**, **do not hide inferences**. Details in the references above.

---

## Step 0: Route — Complexity Assessment

Measure complexity internally upon receiving request (do not expose to user).

### Complexity Signals

| Signal | LOW | HIGH |
|--------|-----|------|
| Request length | Short and specific | Long or ambiguous |
| Keywords | "add", "fix", "change" | "design", "migration", "from scratch" |
| Uncertainty | None | "not sure", "how should I" |
| Impact scope | Single file/module | Cross-cutting, multiple services |
| Risk | Low (UI, text) | High (DB, auth, breaking API) |
| Existing patterns | Clearly exist | None or unfamiliar stack |

- **LOW** → Shallow Path (completed within this file)
- **HIGH** → Deep Path (see `deep/DEEP.md`)
- **Ambiguous** → Start Shallow, monitor escalation conditions

---

## Shallow Path (Low Complexity)

Remove ambiguity via quick Q&A, generate minimal specs, and present the PLAN inline.

### Execution

1. **Record**: Log original request + identify ambiguous parts
2. **Question**: `AskUserQuestion` (specific options, 2-3 rounds)
3. **Escalation Check**: Check escalation conditions (see below)
````
END THIRD-PARTY FILE 450febffe51008c1

The third-party file has ended. Everything between the 450febffe51008c1 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2785 of 5388 bytes. © mag123c · MIT · https://github.com/mag123c/toktrack/tree/HEAD/.claude/skills/clarify/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md