Intent Integrity Kit Clarify (Generic Utility)

Ask targeted clarification questions to reduce ambiguity in the detected (or user-specified) artifact, then encode answers back into it.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

If the user provides a target argument (e.g., plan, spec, checklist, testify, tasks, constitution), use that artifact instead of auto-detection.

Constitution Loading

Load constitution per constitution-loading.md (soft mode — parse if exists, continue if not).

Prerequisites Check

1. Run: bash .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/bash/check-prerequisites.sh --phase clarify --json Windows: pwsh .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/powershell/check-prerequisites.ps1 -Phase clarify -Json

2. Parse JSON. If needs_selection: true: present the features array as a numbered table (name and stage columns). Follow the options presentation pattern in conversation-guide.md. After user selects, run:

   bash .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/bash/set-active-feature.sh --json <selection>

   Windows: pwsh .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/powershell/set-active-feature.ps1 -Json <selection>

   Then re-run the prerequisites check from step 1.

3. Determine the target artifact (see "Target Detection" below).

Target Detection

If the user provided a target argument, map it:

If no argument, auto-detect by checking artifacts in reverse phase order. Pick the first that exists:

1. {FEATURE_DIR}/tasks.md
2. {FEATURE_DIR}/tests/features/*.feature
3. {FEATURE_DIR}/checklists/*.md
4. {FEATURE_DIR}/plan.md
5. {FEATURE_DIR}/spec.md
6. {REPO_ROOT}/CONSTITUTION.md

If no clarifiable artifact exists: ERROR with No artifacts to clarify. Run /iikit-01-specify first or /iikit-00-constitution.

Execution Steps

1. Scan for Ambiguities

Load the target artifact and perform a structured scan using the taxonomy for that artifact type from ambiguity-taxonomies.md. Mark each area: Clear / Partial / Missing.

2. Generate Question Queue

Constraints:

• Each answerable with multiple-choice (2-5 options) OR short phrase (<=5 words)
• Identify related artifact items for each question:
  • Spec: FR-xxx, US-x, SC-xxx
  • Plan: section headers or decision IDs
  • Checklist: check item IDs
  • Testify: scenario names
  • Tasks: task IDs (T-xxx)
  • Constitution: principle names or section headers
• Only include questions that materially impact downstream phases
• Balance category coverage, exclude already-answered, favor downstream rework reduction

3. Sequential Questioning

Present ONE question at a time.

For multiple-choice: follow the options presentation pattern in conversation-guide.md. Analyze options, state recommendation with reasoning, render options table. User can reply with letter, "yes"/"recommended", or custom text.

After answer: validate against constraints, record, move to next.

Stop when: all critical ambiguities resolved or user signals done.

4. Integration After Each Answer

1. Ensure ## Clarifications section exists in the target artifact with ### Session YYYY-MM-DD subheading
2. Append: - Q: <question> -> A: <answer> [<refs>]
   • References MUST list every affected item in the artifact
   • If cross-cutting, reference all materially affected items
3. Apply clarification to the appropriate section of the artifact
4. Save artifact after each integration to minimize context loss

Testify exception: .feature files are Gherkin syntax — do NOT add markdown sections to them. Instead:

• Scan .feature files for ambiguities (step 1)
• Write Q&A to {FEATURE_DIR}/tests/clarifications.md (create if missing)
• Apply changes to the .feature files themselves (update scenarios, add/remove steps)

See clarification-format.md for format details.

5. Validation

After each write and final pass:

• One bullet per accepted answer, each ending with [refs]
• All referenced IDs exist in the artifact
• No vague placeholders or contradictions remain

6. Report

Output: questions asked/answered, target artifact and path, sections touched, traceability summary table (clarification -> referenced items), coverage summary (category -> status), suggested next command.

Next command logic: run check-prerequisites.sh --json status and use its next_step field. This returns the actual next phase based on feature state (which artifacts exist), not what was just clarified. Clarify can run at any point — the next step depends on where the feature is, not where clarify was invoked.

Behavior Rules

• No meaningful ambiguities found: "No critical ambiguities detected." and suggest proceeding
• Continue until all critical ambiguities are resolved
• Avoid speculative tech stack questions unless absence blocks functional clarity
• Respect early termination signals ("stop", "done", "proceed")
• For non-spec artifacts, adapt reference format to the artifact's native ID scheme

Dashboard Refresh

bash .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/bash/generate-dashboard-safe.sh

Windows: pwsh .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/powershell/generate-dashboard-safe.ps1

Next Steps

Run: bash .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/bash/next-step.sh --phase clarify --json Windows: pwsh .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/powershell/next-step.ps1 -Phase clarify -Json

Parse the JSON and present:

1. If clear_after is true: suggest /clear before proceeding (always true for clarify — Q&A sessions consume significant context)
2. Present next_step as the primary recommendation
3. If alt_steps non-empty: list as alternatives
4. For next_step and each alt_step, include the model_tier from the JSON so the user knows which model is best for each option. Look up tiers in model-recommendations.md for agent-specific switch commands.
5. Append dashboard link

Format:

Clarification complete!
Next: /clear → <next_step>
[- <alt_step> — <reason> (model: <tier>)]

- Dashboard: file://$(pwd)/.specify/dashboard.html (resolve the path)