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 to determine the actual next phase based on feature state.

Behavior Rules

• No meaningful ambiguities found: "No critical ambiguities detected." and suggest proceeding
• 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

Commit, Dashboard & Next Steps

Run post-phase to commit, refresh dashboard, and compute next step in a single call:

bash .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/bash/post-phase.sh --phase clarify --commit-files "-u" --commit-msg "clarify: <target-artifact> Q&A"

Windows: pwsh .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-clarify/scripts/powershell/post-phase.ps1 -Phase clarify -CommitFiles "-u" -CommitMsg "clarify: <target-artifact> Q&A"

Parse next_step from JSON. Present per model-recommendations.md:

Clarification complete!
Next: [/clear → ] <next_step> (model: <tier>)
[- <alt_step> — <reason> (model: <tier>)]
- Dashboard: file://$(pwd)/.specify/dashboard.html

Recommend /clear before proceeding to the next phase.