OpenParable
Skip to content
← Back to skills

Paca Clarify

Productivity
paca-clarify

Paca Clarify is an Agent Skill for productivity published in the Paca-AI/paca repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Clarify a vague or incomplete Paca task or specification by identifying ambiguities, asking targeted questions, and rewriting the description with explicit acceptance criteria. Use when a task is unclear, missing edge cases, lacks a testable done condition, or when someone asks to improve or flesh out a spec.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Paca-AI/paca/blob/HEAD/services/ai-agent/src/skills/paca-clarify/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/paca-clarify, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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 task URL → parse the task ID → get_task
    • Doc title / keyword / path → list_docs → read_doc
    • 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_docs 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.

Post these where the requester will actually see them, not just in this conversation — for a task, that's add_task_comment with an @username mention, which sends a real notification. For a document with no linked task, add_doc_comment exists but @mentions there do NOT notify anyone — the person only sees it if they reopen the doc; if the doc is linked to a task, ask there instead. Wait for the user's answers — typically a reply that mentions you back — before writing anything.

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 write_doc 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.


Tool reference

Tasks: get_task · get_task_by_number · update_task · list_tasks Comments: add_task_comment · list_task_activities · add_doc_comment · list_doc_activities Documents: read_doc · write_doc · list_docs Projects: list_projects