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

GitHub

agentii.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 ## Clarifications section (- [YYYY-MM-DD] Q: … → A: …).
  • Re-evaluates checklists/thesis-quality.md after 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.