Guru Clarify Requirements

---
name: guru-clarify-requirements
description: Clarify initial requirements, active-task scope changes, or explicit review requests through an evidence-first semantic loop with dialogue-local choices and typed exits.
---

# Guru Clarify Requirements

The current executing AI is this Skill's semantic owner. Read the complete
contract and perform its review yourself before authoring the current owner
result and calling record, check, and invoke. `owner_not_yet_executed` is an
internal state to continue this review, not a typed stop or a missing external
owner. Do not wait for another agent, agent ID, subagent evidence, or a
pre-existing owner result. Real missing authority or prerequisites still
follow this Skill's declared routes; runtime cannot supply your judgment.

Use this Skill after `guru-discover-change-context:context_ready`, when an
active task receives scope-changing input, or for an explicit standalone
requirements review.

For active-task scope change, the canonical workflow mandatory invokes this
same Skill with an exact caller-aware `resume_target`; no caller may duplicate
classification or planning-update semantics.

Before this owner creates a scope proposal, asks a scope question, or assigns a
terminal scope disposition to a newly observed scenario, form only candidate
refs and live locators and invoke `guru-qualify-normal-scenario` with
`requirements_scope_set`. Rejected candidates are final for the current
invocation and must not become clarification questions. The
`normal_scenario_scope_confirmation` public profile instead consumes only the
qualifier's minimal `scope_confirmation_required` projection and asks the exact
authority choice before returning to the declared original owner. It does not
repeat or reinterpret qualification and accepts no decision, reason, severity,
authorization, result locator, or qualification artifact.

Before a proposed clarification mechanism can affect scope, questions, or an
authority action, invoke `guru-qualify-solution-mechanism` with the same
profile. A `mechanism_revision_required` result removes or replaces only that
mechanism and returns here for fresh qualification; it is not a scope
confirmation route.

Before answering repository-searchable questions or evaluating duplicate and
prior-decision evidence, read `.trellis/spec/workflow/semantic-retrieval.md` and
apply it in this Skill's semantic gate. Do not infer absence from a
single-language zero result or expose the query process through the public DTO.

From the repository root, load
`.trellis/guru-team/skills/packages/guru-clarify-requirements/references/contract.md` and
`trellis-brainstorm`. Execute the semantic closed loop in its declared order,
ask at most one highest-value question per round, complete the AI Review Gate
and any real action/proposal choice before calling recorder/checker,
keep that authorization in the current dialogue, then return exactly one
declared typed exit.

Record only clarification rounds and answers that actually occurred. Unknown,
unasked, or unanswered choices are not refused, deferred, or answered; never
invent an interaction to fill the schema. When a required real choice cannot
be obtained, express the unresolved conflict through the existing blocked Gate,
not a fabricated round, answer, or pass. Follow Questions And Convergence in
the contract for the no-answer blocked shape.

A scope/product conflict does not erase known target identity or duplicate
facts. Complete the independent target disposition when the facts suffice,
even for blocked, and preserve the real Discovery snapshot. Null disposition
is not a blocked shortcut; it applies only where the target decision itself
is genuinely missing and the existing invocation contract permits it.
Return only successful public invoke stdout as the final DTO. Record/check
`typed_exit` is not a public exit; handle an invoke error truthfully through
the existing repair/re-entry rules, never by hand-writing a blocked DTO.

Use only the dispatcher wrappers for deterministic recording and checking.
Pre-task and standalone results are stdout-only. This Skill has no mutation
executor and no dedicated tracked clarification artifact. GitHub writes remain
AI-owned and require an exact current payload plus a live reread; the result
records only objective action and mutation facts.

Fail closed on missing/current-context drift, repository `answered` without
checked evidence, invalid question
lifecycle, open load-bearing questions, payload/live mutation or
digest mismatch, missing/stale/multiple target disposition, unresolved or
stale duplicate-candidate decisions, closed targets without an explicit legal
disposition, empty/non-final active-task proposal sets on `clear`/`new_task`,
any unresolved scope classification, any classification task update not bound
to the same current proposal set,
mechanism disposition with a classification trail or mutation, incomplete or
stale planning content, missing compact
owner-result `decision_trail`, or missing live GitHub-visible scope authority,
load-bearing clarification without a current issue/draft
authority action, authority/context/task-update order mismatch, invalid caller
resume, stale active-task evidence, non-current artifact input, unknown exits,
or missing current runtime. This package is not self-contained or portable.

## Installed Commands And Authoring

Run from the repository root through the managed package wrappers:

```bash
bash .trellis/guru-team/skills/packages/guru-clarify-requirements/scripts/record-requirements-clarification.sh --mode workflow --input - --json
bash .trellis/guru-team/skills/packages/guru-clarify-requirements/scripts/check-requirements-clarification.sh --input - --json
bash .trellis/guru-team/skills/packages/guru-clarify-requirements/scripts/invoke.sh --invocation - --json
```

Use `--mode standalone` for standalone recording. Feed the reviewed semantic
owner JSON to record, its stdout result to check, and the complete invocation
envelope to invoke. Keep these values in memory; do not create repository files.
The contract's `Minimal Recorder Authoring` table lists required semantic fields
and the exact omittable fields. The full checked-result example is at
`.trellis/guru-team/skills/packages/guru-clarify-requirements/examples/requirements-clarification.json`;
remove only the listed derived fields when using it as an authoring shape, and
replace every example judgment and fact with the current reviewed result.
Agent discovery projections do not contain the package scripts or examples.

After the semantic gate and owner recorder/checker complete, invoke the command
above with the closed call-local public input,
`context_current` transition, and checked owner result on stdin to serialize
the minimal handoff. The runtime validates the envelope's mode, target, and
transition bindings, reruns the existing checker, and derives the route and
output from the checked `typed_exit` and declared transition. Callers cannot
select the route or provide a separate `typed_output` field. Private
clarification evidence is not a public input or output template.