spec-creation

Spec Creation Skill

Шаг ① workflow — создание ТЗ с валидацией по IEEE 29148:2018, ветки и коммита.

Workflow Contract

entry:
  branch: main | master
  trigger:
    - "создай ТЗ"
    - "new feature"
    - "новая фича"
    - "bugfix"
    - "исправь баг"

exit:
  artifacts:
    - .ai/specs/{branch-type}-{slug}.md
  branch: feature/* | bugfix/*
  commit: "docs: add spec for {feature-name}"

recommended_next_skill: spec-implementer  # Рекомендуемый следующий skill для Codex

When to Use This Skill

• User requests creating a technical specification (ТЗ, техническое задание)
• User says "создай ТЗ", "напиши спецификацию", "создай spec"
• User reports a bug → создать bugfix spec с красным тестом
• Starting workflow step ① (per project workflow guide)

Output Location

Specifications are created in .ai/specs/ directory with naming pattern:

• feature-{slug}.md for new features
• bugfix-{slug}.md for bug fixes

A git branch will be created with pattern:

• feature/{slug} for new features
• bugfix/{slug} for bug fixes

The spec file will be committed to the new branch.

Core Principles

Iterative Requirement Refinement

This skill uses multi-round validation with IEEE 29148:2018 quality criteria:

Critical: A specification is NOT complete until validation achieves ≥85% score.

Progressive Disclosure

• Keep spec template concise in SKILL.md
• Reference detailed templates in references/ directory
• Load templates only when needed

IEEE 29148:2018 Quality Assessment Framework

The requirements quality score is calculated from 5 sections, each containing specific criteria with maximum weight of 5 per criterion.

Section 1: Core Quality Attributes (40 points total)

Criterion	Weight	Check
Necessary	5	Does the requirement define an essential capability/characteristic?
Unambiguous	5	Is there only one possible interpretation?
Complete	5	Are all necessary capabilities/characteristics/constraints described?
Consistent	5	Is it free of conflicts with other requirements?
Singular	5	Does it address only one concern (not compound)?
Feasible	5	Is it achievable with given constraints (time, budget, technology)?
Traceable	5	Can it be linked to stakeholder needs and business objectives?
Verifiable	5	Can fulfillment be measured through testing/inspection?

Section 2: Context & Rationale (20 points total)

Criterion	Weight	Check
Implementation-free	5	Does it avoid dictating HOW to implement (WHAT vs HOW)?
Affordable	5	Is it within budget/resource constraints?
Bounded	5	Are scope boundaries clearly defined?
Rationale stated	5	Is the reason for this requirement explained?

Section 3: Completeness of Description (20 points total)

Criterion	Weight	Check
Inputs defined	5	Are all inputs clearly specified (data, parameters, user actions)?
Outputs defined	5	Are expected outputs clearly described (return values, UI changes, side effects)?
Constraints identified	5	Are technical/business/environmental constraints noted?
Edge cases covered	5	Are error scenarios and boundary conditions addressed?

Section 4: Traceability & Stakeholders (10 points total)

Criterion	Weight	Check
Stakeholder mapping	5	Can the requirement be linked to specific stakeholders/users?
Business value	5	Does it align with stated business objectives or user needs?

Section 5: Acceptance & Prioritization (10 points total)

Criterion	Weight	Check
Prioritization clear	5	Is priority level specified (must-have vs nice-to-have)?
Success criteria	5	Are measurable acceptance criteria defined?

Maximum Score: 100 points Threshold: 85 points minimum to proceed

Iterative Validation Process

Round Structure

For each validation round:

1. Display Current Requirements Version - Show the accumulated requirements in markdown format
2. Calculate IEEE 29148 Score - Evaluate each criterion and calculate total
3. Decision Point:
   • If score ≥ 85: Proceed to next phase
   • If score < 85: ask the user a concise clarification question
4. Enrich & Re-evaluate - Update requirements with answers and re-score

Round 1: Core Requirements Validation

Initial Requirements Gathering:

## Initial Requirements

### Feature Overview
- **Feature name**: {from user}
- **Type**: {new feature/bug fix/enhancement}
- **Vision**: {one sentence}

### Core Requirements
- {Must-have requirements from user}

### Stakeholders
- {Target users, roles}

### Constraints
- {Technical/business constraints}

Evaluate using Section 1 (Core Quality Attributes) + Section 2 (Context & Rationale)

Common Gaps to Address via direct user questions:

• Unambiguous: "Which specific notification channels?" (email, in-app, SMS?)
• Complete: "What data needs to be stored for each notification?"
• Feasible: "Are there rate limits or API constraints?"
• Implementation-free: "What business outcome, not which library?"

Round 2: Technical Completeness Validation

Extended Requirements:

## Technical Requirements

### Functional Requirements
- {Specific functional behaviors}

### Non-Functional Requirements
- {Performance, security, usability}

### API & Database Changes
- {Endpoints, schemas, migrations}

### Frontend Changes
- {Pages, components, templates}

Evaluate using Section 3 (Completeness of Description)

Common Gaps to Address:

• Inputs defined: "What parameters does the API accept?"
• Outputs defined: "What response format/status codes?"
• Constraints identified: "Are there authentication requirements?"
• Edge cases covered: "What happens if the external service is down?"

Round 3: Traceability & Acceptance Validation

Final Requirements:

## Implementation Plan

### Stages
- {Logical breakdown with dependencies}

### Acceptance Criteria per Stage
- {Measurable, testable criteria}

### File Changes
- {Concrete paths: src/...}

### Documentation Updates
- {ARCHITECTURE.md, API docs, etc.}

Evaluate using Section 4 (Traceability) + Section 5 (Acceptance)

Common Gaps to Address:

• Stakeholder mapping: "Which user role triggers this workflow?"
• Business value: "What problem does this solve for the user?"
• Success criteria: "How do we verify this works?" (not "it works")
• Prioritization: "Is this must-have for MVP or can it wait?"

Output Format

After all validation rounds pass, generate the specification file AND create branch with commit:

Step 1: Confirm Branch Creation with User

Ask the user directly for confirmation:

ТЗ готово (оценка IEEE 29148: ≥85%). Создать ветку и закоммитить ТЗ?
- Да, создать ветку и закоммитить
- Только создать файл спецификации (без ветки и коммита)

Step 2: Determine Branch Type

If user confirms "Да", determine branch type:

• Feature: for new functionality, enhancement (feature/{slug})
• Bugfix: for fixing bugs (bugfix/{slug} or bugfix/{issue-id}-{slug})
• Refactor: for code restructuring without behavior change (feature/refactor-{area})
• Hotfix: for urgent production fixes (hotfix/{description})

Infer from spec type or ask the user directly if unclear:

Какой тип ветки создать?
- feature (новая функциональность)
- bugfix (исправление бага)
- refactor (рефакторинг)
- hotfix (срочный фикс для production)

Step 3: Check Current Branch

git branch --show-current
git status

Protection Policy: If on main or master, warn user:

⚠️ Вы находитесь на ветке main/master. Прямые изменения не рекомендуются.
Создать feature branch?

Ensure no uncommitted changes remain before creating new branch.

Step 4: Create Branch

git checkout -b {branch-type}/{slug}

Examples:

• feature/thermocalc-response-differentiation
• bugfix/login-validation-error
• bugfix/142-auth-token-expiry
• feature/refactor-user-service
• hotfix/payment-gateway-timeout

Branch naming conventions:

• Use lowercase letters
• Separate words with hyphens
• Keep descriptions short but descriptive
• For bugfixes, include issue ID if available
• For hotfixes, use prefix hotfix/ for urgent production fixes

Step 5: Verify Branch Creation

git status

Ensure:

• New branch is created
• It's based on the correct starting point (typically main)
• No uncommitted changes remain on main branch

Step 6: Write Spec File and Commit

# Write spec to .ai/specs/{filename}.md
git add .ai/specs/{filename}.md
git commit -m "docs

---

*Content truncated.*