paca-clarify
# paca-clarify The paca-clarify Claude Code skill refines vague or incomplete Paca task specifications by systematically identifying ambiguities, asking targeted clarifying questions, and rewriting descriptions with explicit acceptance criteria. Use it when a task lacks testable done conditions, omits edge cases, contains undefined terms, or when you need to flesh out a specification before work begins.
git clone --depth 1 https://github.com/Paca-AI/paca /tmp/paca-clarify && cp -r /tmp/paca-clarify/skills/paca-clarify ~/.claude/skills/paca-clarifySKILL.md
You are clarifying a task or specification in Paca. Use Paca MCP tools throughout — never create local files.
**If no task is specified**, call `list_tasks` and surface tasks that have no acceptance criteria or have a very short description — those are the best candidates for clarification. Present them and ask which to work on.
---
## Step 1 — Load project context
1. Resolve the target from the user's message:
- `#42` or `ABC-42` → `get_task_by_number`
- Paca URL → parse IDs → `get_task` or `get_document`
- Doc title / keyword → `list_documents` → `get_document`
- **If the task or document is not found**, tell the user clearly ("Task #99 was not found in project X") and ask them to verify the reference.
2. Call `list_documents` and read documents that provide context for this task — requirements, architecture, BDD scenarios, prior decisions. Reading broadly here means you won't ask questions the docs already answer.
3. If it's a task, call `list_task_activities` to read prior comments, decisions, and any clarifications already given.
## Step 2 — Identify ambiguities
Read the task description or document carefully and find:
- **Scope gaps** — what is in vs. out is not stated
- **Missing edge cases** — error states, empty states, permission boundaries, concurrency
- **Undefined terms** — domain words that could mean different things in this codebase
- **Unstated assumptions** — things the author assumed but did not write down
- **Acceptance criteria gaps** — no measurable, testable "done" condition
Only surface real ambiguities. Skip things that are clearly inferable from context or docs you just read.
## Step 3 — Ask clarifying questions
Present a numbered list of at most 6 questions, grouped by theme (scope / edge cases / definitions). Err on the side of fewer, better questions over many shallow ones. Wait for the user's answers before writing anything back.
**Example format:**
```
**Scope**
1. Should this cover X, or is X a separate initiative?
2. Does this apply to guest users, or only authenticated users?
**Edge cases**
3. What should happen when Y is empty?
**Acceptance criteria**
4. What does "success" look like — a UI state, an API response, something else?
```
## Step 4 — Update the spec in Paca
Once the user answers:
- **Task**: call `update_task` with an improved description including explicit acceptance criteria. Don't just append — rewrite the description so it stands alone without this conversation.
- **Document**: call `update_document` with the resolved content and any new decisions recorded as a "Decisions" section.
Do not create a new document — update the existing one.
Report back: what was clarified and the task/doc number and title that was updated.
---
## If Paca MCP is not connected
> Paca MCP tools are not available. Run `/paca-setup` to configure the connection.
---
## Tool reference
**Tasks:** `get_task` · `get_task_by_number` · `update_task` · `list_tasks`
**Comments:** `list_task_activities`
**Documents:** `get_document` · `update_document` · `list_documents`
**Projects:** `list_projects`Break a large Paca task or epic into smaller, actionable sub-tasks with dependency ordering. Use when decomposing work that is too large to estimate or execute in a single session, when creating an implementation plan, or when a task needs to be split into vertical slices before sprint planning.
Execute a Paca task end-to-end — reading context and acceptance criteria, doing the work (code, writing, research, review), updating task status, and commenting results. Use when asked to start, implement, complete, or work on a specific Paca task. Reads project docs first to understand the codebase and tech stack before acting.
Write or update documentation for a feature, task, or topic in Paca Docs. Use when asked to document a completed feature, write a guide or runbook, update existing docs, create a spec or architecture document, or produce BDD scenarios. Documentation is saved in Paca — never created as local files.
Turn a product requirement or feature description into a structured epic in Paca, with child user stories and a spec document. Use when asked to plan a new feature, break down a high-level requirement into stories, create an epic, or go from "we need X" to a fully structured backlog ready for sprint planning.
Estimate story points for Paca tasks using the Fibonacci scale, calibrated against recently completed reference tasks and project tech stack. Use when tasks are missing estimates, before sprint planning, when the team needs sizing for prioritization, or when asked to size a backlog.
Set or adjust priorities across the Paca backlog, aligned to roadmap goals and business value. Use when the backlog needs sorting, before sprint planning, when tasks need explicit Critical/High/Medium/Low priority labels, or when asked to rank work by importance or urgency.
Configure the Paca MCP server for use with Claude Code or Claude Desktop. Use when setting up Paca for the first time, adding or editing the MCP server config, troubleshooting connectivity, or installing the Paca skills globally. Walks the user through prerequisites, config file generation, verification, and optional global skill install.