| name | spx-clarify |
| description | Existing-spec repair workflow for advanced coding models. Use when a specification package has planning-critical ambiguity, weak acceptance, contradictions, or new constraints that should be absorbed without recreating the feature. |
SPX Clarify
Read references/project-learning.md and apply its consume-capture policy.
Read references/project-cognition.md, using cognition intent plan,
references/clarification-contract.md, and references/consequence-gate.md
only on its triggers.
Read references/ui-quality-gate.md when the planning blocker concerns UI
experience, design readiness, states, responsive behavior, or fidelity.
Resolve the existing feature with the installed prerequisite script in
paths-only mode. Do not create a new feature. Read spec-contract.json first,
then only the views, discussion handoff, UI evidence, project rules, or live
paths needed for the named gaps.
Before any write, run
{{specify-subcmd:specify-runtime workflow show --feature-dir <feature-dir> --format json}}.
FEATURE_DIR/workflow.json is CLI-owned; this auxiliary skill must not write
it, and its expected required-stage owner is specify. On missing, corrupt,
different, or completed runtime state, stop with the returned blocker or a
typed owner handoff containing the observed stage, expected owner, affected
files, exact next action, unblock criteria, and resume argv. Never overwrite
either state surface to force entry.
Create or resume rich workflow-owned workflow-state.md before substantive
work, using the installed workflow-state template only when it is absent. Record
active_command: sp-clarify, phase_mode: planning-only, the source revision,
target boundary, current blocker, and next route without copying spec truth.
Run {{specify-subcmd:specify-runtime hook validate-state --command clarify --feature-dir <feature-dir> --autofix --format json}}
and fail closed if the repaired state still does not validate.
Identify decisions whose alternatives materially change behavior, acceptance,
interfaces, lifecycle, security, compatibility, or scope. Resolve repository
facts from evidence. Ask the user only for product decisions the repository
cannot own, in a small prioritized batch. Preserve confirmed scope and record
safe assumptions explicitly.
Apply accepted answers to the authoritative spec contract and its referenced
views. The complete clarification working set is spec.md, alignment.md,
context.md, references.md, workflow-state.md,
clarification/handoffs/, clarification/evidence-index.json, and
clarification/checkpoints.ndjson; initialize missing clarification evidence
surfaces, preserve existing records, and consume every accepted handoff into a
named artifact section, explicit deferral, or blocker. Ensure every planning
blocker is resolved, explicitly retained, or routed to $spx-deep-research.
Run
{{specify-subcmd:specify-runtime hook validate-artifacts --command clarify --feature-dir <feature-dir> --format json}}
before reporting planning readiness. Repair owned artifacts or fail closed on a
non-OK result.
This invocation authorizes only this workflow stage. Do not plan or implement.
Do not invoke $spx-deep-research. Do not invoke $spx-plan. Report the
applicable workflow as the next handoff when the package needs research or
becomes planning-ready; otherwise report the exact unresolved decision and why
it blocks.
