iikit-01-specify

name	iikit-01-specify
description	Create a feature specification from a natural language description — generates user stories with Given/When/Then scenarios, functional requirements (FR-XXX), success criteria, and a quality checklist. Use when starting a new feature, writing a PRD, defining user stories, capturing acceptance criteria, or documenting requirements for a product idea.
license	MIT
metadata	{"version":"1.6.4"}

Intent Integrity Kit Specify

Create or update a feature specification from a natural language description.

User Input

$ARGUMENTS

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

Constitution Loading

Load constitution per constitution-loading.md (soft mode — warn if missing, proceed without).

Execution Flow

The text after /iikit-01-specify is the feature description.

0. Bug-Fix Intent Detection

Before proceeding with feature specification, analyze the user description for bug-fix intent using contextual analysis (not keyword-only):

Bug-fix signals (keywords in a fixing context): "fix", "crash", "broken", "bug", "doesn't work", "fails", "error" when used to describe existing broken behavior.

NOT bug-fix (keywords in a new-feature context): "Add error handling", "Implement crash recovery", "Create bug tracking" — these describe new capabilities, not fixes to existing behavior.

Decision rule: Is the primary intent to fix existing broken behavior or to add new capability? Keywords alone are insufficient — evaluate the full description.

If bug-fix intent is detected:

1. Display: "This sounds like a bug fix. Consider using /iikit-bugfix instead."
2. Show example: /iikit-bugfix '<the user description>'
3. Ask the user to confirm: proceed with specification (it's genuinely a new feature) or switch to /iikit-bugfix
4. If the user confirms it is a new feature: proceed to Step 1
5. If the user wants bugfix: stop and suggest they run /iikit-bugfix

1. Generate Branch Name

Create 2-4 word action-noun name from description:

• "I want to add user authentication" -> "user-auth"
• "Implement OAuth2 integration for the API" -> "oauth2-api-integration"

2. Create Feature Branch and Directory

Check current branch. If on main/master/develop, suggest creating feature branch (default). If already on feature branch, suggest skipping.

Unix/macOS/Linux:

bash .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --short-name "your-short-name"
# Add --skip-branch if user declined branch creation

Windows (PowerShell):

pwsh .tessl/tiles/tessl-labs/intent-integrity-kit/skills/iikit-core/scripts/powershell/create-new-feature.ps1 -Json "$ARGUMENTS" -ShortName "your-short-name"
# Add -SkipBranch if user declined

Parse JSON for BRANCH_NAME, SPEC_FILE, FEATURE_NUM. Only run ONCE per feature.

3. Generate Specification

1. Parse user description — if empty: ERROR with usage example
2. Extract key concepts: actors, actions, data, constraints
3. For unclear aspects: make informed guesses. Only use [NEEDS CLARIFICATION: question] (max 3) when choice significantly impacts scope and no reasonable default exists
4. Fill User Scenarios with independently testable stories (P1, P2, P3 priorities)
5. Generate Functional Requirements (testable, with reasonable defaults)
6. Define Success Criteria (measurable, technology-agnostic)
7. Identify Key Entities (if data involved)

Write to SPEC_FILE using spec-template.md structure.

4. Phase Separation Validation

Scan for implementation details per phase-separation-rules.md (Specification section). Auto-fix violations, re-validate until clean.

5. Create Spec Quality Checklist

Generate FEATURE_DIR/checklists/requirements.md covering: content quality (no implementation details), requirement completeness, feature readiness.

5b. Generate QA Acceptance Criteria

Generate FEATURE_DIR/qa/acceptance-criteria.md from the spec's SC-XXX success criteria:

# Acceptance Criteria — {Feature Name}
Generated from spec.md | {date}

## Success Criteria Checklist
- [ ] SC-001: {description} — Target: {measurable target}
- [ ] SC-002: {description} — Target: {measurable target}
...

## Traceability
| SC | Linked FR | Verifiable By |
|----|-----------|---------------|
| SC-001 | FR-001, FR-002 | Unit test / E2E |

Each SC-XXX from spec.md becomes a checkable acceptance criterion with a measurable target.

6. Handle Clarifications

If [NEEDS CLARIFICATION] markers remain, present each as a question with options table and wait for user response.

7. Report

Output: branch name, spec file path, checklist results, readiness for next phase.

Guidelines

• Focus on WHAT users need and WHY — avoid HOW
• Written for business stakeholders, not developers
• Success criteria: measurable, technology-agnostic, user-focused, verifiable

Semantic Diff on Re-run

If spec.md already exists: extract semantic elements (stories, requirements, criteria), compare with new content per formatting-guide.md (Semantic Diff section), show downstream impact warnings, ask confirmation before overwriting.

Commit

git add specs/*/spec.md specs/*/checklists/requirements.md .specify/active-feature
git commit -m "spec: <feature-short-name> specification"

Dashboard Refresh

Regenerate the dashboard so the pipeline reflects the new spec:

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

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

Next Steps

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

Parse the JSON and present:

1. If clear_after is true: suggest /clear before proceeding
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:

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

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