git:20260502.5bc84e8 to git:20260912.5e86435

35 added, 62 removed. Audit A to A.

---

name: clarify-goal

- description: "Ask the user targeted clarifying questions about their research goal before the pipeline runs. Use when the research goal is vague, ambiguous, or missing key context (e.g., which sections to focus on, threat model assumptions, what 'broken' means). Works with or without a paper."

+ description: "This skill asks questions to define a research goal. You use it when the scope, assumptions, or success criteria are unclear."

user-invocable: true

argument-hint: "\"<research-goal>\" [paper-path]"

license: Apache-2.0

---

# Clarify Goal

- Ask the user targeted questions to sharpen a vague research goal into something the pipeline can act on precisely.

+ You must read and apply the [language rules](../reaper/references/language.md) before you write any output.

## Usage

- Invoke this skill by name with the research goal (and optional paper path). On slash-command hosts, prefix with `/` (e.g. `/clarify-goal "<goal>"`).

+ You invoke this skill by name with a quoted goal and an optional paper path. Slash-command hosts use `/clarify-goal "<goal>"`.

```

- # Without a paper — goal-driven research

clarify-goal "explore the feasibility of post-quantum threshold signatures"

- # With a paper

clarify-goal "is this protocol secure?" path/to/paper.pdf

```

- **Argument parsing:** The research goal (quoted string) is required. If a path to an existing file is also provided, treat it as the paper.

+ The quoted research goal is required. An additional path to an existing file identifies the paper.

## Instructions

- ### 1. Read the Paper (quick scan) — if provided

- **If a paper path was provided:** Read the paper at the given path. Do a fast scan — you are not producing a full analysis, just enough to understand:

- - What the paper is about (topic, system, protocol)

- - What it claims (main theorems, security properties, performance results)

- - Its structure (which sections cover what)

- **If no paper was provided:** Skip this step. You will clarify the goal based on the research prompt alone, using your knowledge of the research domain.

- ### 2. Identify Ambiguities

- Compare the user's research goal against what the paper contains (if provided) or against the research domain in general. Look for:

- - **Scope ambiguity**: Does the goal apply to a whole paper/field or specific sections/theorems/protocols?

- - **Definition ambiguity**: Does the goal use terms that could mean multiple things? (e.g., "secure" — against what adversary? under what model?)

- - **Success criteria ambiguity**: What would a satisfying answer look like? A counterexample? A proof gap? A performance bound?

- - **Assumption ambiguity**: Are there implicit assumptions the user might want to constrain or relax? (e.g., synchrony vs. asynchrony, static vs. adaptive adversary)

- - **Comparison ambiguity**: If the goal involves comparison ("is this better than X?"), what metric and what baseline?

- ### 3. Ask Questions

+ ### 1. Read the Paper

- Ask the user **3-5 targeted questions** (no more). Each question should:

- - Be specific to the paper and goal, not generic

- - Offer concrete options where possible (e.g., "Do you mean the safety proof in Section 4.2 or the liveness proof in Section 5.1?")

- - Have a sensible default so the user can skip questions they don't care about

+ If the user supplies a paper, you scan it for this information:

- Format as a numbered list. After the questions, state what you'll assume if they don't answer a particular question (the defaults).

+ - The paper's topic, system, and protocol.

+ - The paper's main theorems, security properties, and performance results.

+ - The sections that contain each result.

- ### 4. Incorporate Answers

+ You leave full analysis to the `analyze-paper` skill. If the user supplies no paper, you use the goal and research domain.

- After the user responds:

- - Merge their answers with your defaults for any unanswered questions

- - Write the refined research goal and key context to `reaper-workspace/notes/clarified-goal.md`

+ ### 2. Identify Unclear Requirements

- The file should contain:

- ```markdown

- # Clarified Research Goal

+ You check the goal against the paper or research domain.

- ## Original Goal

- <what the user initially said>

+ - **Scope:** You determine which papers, sections, theorems, or protocols the goal covers.

+ - **Definitions:** You identify terms with multiple meanings, such as security under different adversary models.

+ - **Success criteria:** You determine whether the user needs a counterexample, proof gap, or performance bound.

+ - **Assumptions:** You identify assumptions that the user can change, such as synchrony or adversary type.

+ - **Comparison:** You identify the metric and baseline for each comparison.

- ## Clarifying Q&A

- <numbered list of each question you asked and the user's answer, or "(default)" if they didn't answer>

+ ### 3. Ask Questions

- ## Refined Goal

- <precise, unambiguous version incorporating the user's answers>

+ You ask 3-5 questions that address the paper and goal. Each question offers concrete options where possible. Each question has a default answer. You use a numbered list. You state the defaults for questions that the user does not answer.

- ## Scope

- <which parts of the paper/topic are in scope>

+ ### 4. Use the Answers

- ## Key Assumptions

- <assumptions that the investigation should operate under>

+ After the user responds, you combine their answers with defaults for unanswered questions. You write `reaper-workspace/notes/clarified-goal.md` with title `# Clarified Research Goal` and these level-two sections:

- ## Success Criteria

- <what a satisfying answer looks like>

- ```

+ | Section | Content |

+ |---|---|

+ | Original Goal | You copy the user's goal exactly. |

+ | Clarifying Q&A | You record each question and exact answer. You label unanswered items `(default)` and state the default. |

+ | Refined Goal | You state the precise goal with the user's answers. |

+ | Scope | You identify the parts of the paper or topic that the research covers. |

+ | Key Assumptions | You state investigation assumptions. |

+ | Success Criteria | You state the evidence that answers the goal. |

### 5. Report

- Tell the user the refined goal and confirm before the pipeline proceeds.

+ You state the refined goal. You ask the user to confirm it before the pipeline continues.

## Quality Criteria

- - Questions are specific to the paper and goal, not generic

- - Each question offers concrete options or defaults

- - The refined goal in `clarified-goal.md` is precise enough for `/formalize-problem` to act on without further clarification

- - If the paper PDF is unreadable, report the error — do not proceed with fabricated context

+ - The refined goal gives `formalize-problem` enough information to proceed.

+ - If the PDF is unreadable, you report the error. You do not invent context.

- ## Important Notes

+ ## Exceptions

- - This skill is interactive — it requires user input. Do not skip the question-asking step.

- - Keep the quick scan fast. Don't spend time on deep analysis — that's what `/analyze-paper` is for.

- - If the research goal is already precise and unambiguous (e.g., "Does Theorem 4.2 hold when the adversary controls >1/3 of stake?"), you may skip questions and go straight to writing `clarified-goal.md`. Tell the user the goal is clear and proceed.

- - When no paper is provided, focus questions on scoping the research domain, defining key terms, and establishing what kind of output the user expects (survey, feasibility analysis, novel construction, etc.).

+ - If the goal is unclear, you ask questions and request confirmation. Without a paper, you ask about the domain, terms, and expected output.

+ - If the goal is precise, you can omit questions and confirmation. You write `clarified-goal.md`, state that the goal is clear, and continue.