clarify
The research-domain clarification skill — find underspecified items in a thesis spec.md (prose wrong_if, universe rows without rationale, missing budget/expiry/pins, ambiguous pillars), ask the human
SKILL.mdplugins/vertical-plugins/scenarios/skills/agentii/clarify/SKILL.md
GitHubagentii.clarify
The 8th kit command — closes the gap Q32 itself assumed: upstream
speckit-clarify re-evaluates the quality checklist after every spec write, but
spec 046 never named the command that performs the clarification.
Invocation
Both phases run kit Python. Resolve the kit root once per shell first —
contracts/kit-root.md. The kit's scripts do NOT ship with the skills, and this
skill's old path (kit-scripts/, below) did not exist at all: it named a directory
that has never been in this repository, so every documented invocation of clarify
failed with "No such file or directory".
# Resolve the kit root — contracts/kit-root.md. Never assume the CWD is the checkout.
KIT=""
for c in "${AGENTII_KIT_ROOT:-}" \
"$(cat "$HOME/.claude/skills/agentii/.kit-root" 2>/dev/null)" \
"${CLAUDE_PLUGIN_ROOT:-}"; do
[ -n "$c" ] && [ -f "$c/scripts/agentii_cmd.py" ] && { KIT="$c"; break; }
done
if [ -z "$KIT" ]; then d="$PWD"; while [ "$d" != "/" ]; do
[ -f "$d/scripts/agentii_cmd.py" ] && { KIT="$d"; break; }; d="$(dirname "$d")"; done; fi
[ -n "$KIT" ] || { echo "agentii kit not found — see contracts/kit-root.md" >&2; exit 1; }
Two phases
1. Analyze (deterministic)
python3 "$KIT/scripts/agentii_cmd.py" clarify --thesis theses/001-… --questions
Emits a JSON list of candidate questions, each with:
id(stable — content-derived from the target)target(pillar id / field / universe row)question(exact, in the spec's working language)options(derived where possible; null = free-form)
Candidates come from a deterministic scanner (never vibes): prose wrong_if
(missing metric=/threshold=/source=), universe rows without rationale,
missing budget, missing expiry_triggers, subscription tokens not in
TICKER × skill form, missing as_of/pins, pillars without priority.
2. Encode (after the human answers)
# $KIT comes from `## Invocation` above — re-run that resolver if this is a new shell.
python3 "$KIT/scripts/agentii_cmd.py" clarify --thesis theses/001-… --answers '<json>'
- Appends each answer to
spec.md's## Clarificationssection (- [YYYY-MM-DD] Q: … → A: …). - Re-evaluates
checklists/thesis-quality.mdafter the write (Q32: the machine-maintained checklist is bidirectional — report "N/M items passing" plus regressions).
Rules
- Max 5 questions per round (upstream v1.0.4's tightened limit; spec recorded it as the convention to follow).
- Only ask what blocks the next step — every question must name the field it unblocks.
- Answers are encoded verbatim (professional English); a Chinese question is translated to English before encoding (the project's first language is English).
- Never ask about facts obtainable from the platform (that's the skills' job); clarify intent only.