home / skills / vladimirbrejcha / ios-ai-skills / spec-creation-updating

spec-creation-updating skill

safe

This skill helps you create, update, and verify technical specifications that are testable, complete, and implementation-ready across projects.

npx playbooks add skill vladimirbrejcha/ios-ai-skills --skill spec-creation-updating

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

3.0 KB

---
name: spec-creation-updating
description: Create, update, review, and improve technical specification documents so they are complete, testable, and implementation-ready. Use when defining new features/systems/APIs, updating existing specs, restructuring documents, auditing missing requirements, or converting vague plans into concrete, verifiable requirements and acceptance criteria.
---

# Spec Creation Updating

## Overview

Produce specs that reduce ambiguity and can be implemented with minimal back-and-forth.
Apply this workflow to any project domain (product, backend, API, data, UI, infrastructure, ops).

## Workflow

### 1. Set boundaries

- Capture the objective and user/business value.
- Define in-scope and out-of-scope behavior.
- Record assumptions, dependencies, and constraints.
- Ask clarifying questions when decisions affect architecture, cost, security, or user-visible behavior.

### 2. Choose depth

- Write a lightweight spec for isolated, low-risk changes.
- Write a full system spec for cross-team, risky, or high-impact work.
- Keep the same quality gates regardless of depth.

### 3. Build structure

- Start from [`references/spec-template.md`](references/spec-template.md).
- Preserve repository naming, section ordering, and style if they already exist.
- Add domain-specific sections as needed, but do not remove mandatory content.

### 4. Fill concrete requirements

- Write requirements as testable statements, not intentions.
- Define success paths, edge cases, and failure behavior.
- Specify interfaces, data contracts, and state transitions when relevant.
- Specify non-functional requirements: performance, reliability, scalability, observability.

### 5. Define verification and completion

- Map each requirement to a verification method.
- Include reproducible commands, tests, and manual checks when automation is unavailable.
- Define completion criteria with pass/fail outcomes.

### 6. Close traceability

- Link related specs, ADRs, designs, and operational docs.
- Update version, last-updated date, and status.
- Record unresolved questions and decision owners.

### 7. Run quality gate

- Validate against [`references/spec-must-have-checklist.md`](references/spec-must-have-checklist.md).
- Use [`references/spec-review-scorecard.md`](references/spec-review-scorecard.md) when auditing an existing spec.
- Treat any missing MUST item as blocking.

## Writing rules

- Prefer precise language over broad terms like "optimize", "support", or "handle".
- Use explicit units, limits, and conditions.
- Mark implemented vs planned behavior with explicit status labels.
- Keep requirements and facts in the spec; keep narrative concise.
- Avoid embedding secrets or private credentials in reusable specs.

## Output expectations

- When creating a spec, deliver:
  - A complete spec document.
  - A list of unresolved questions.
  - A verification plan mapped to requirements.
- When reviewing a spec, deliver:
  - Prioritized gaps and risks.
  - Concrete rewrite suggestions.
  - A readiness verdict based on MUST items.

Overview

This skill creates, updates, and reviews technical specification documents so they are complete, testable, and implementation-ready. It applies a repeatable workflow across product, API, backend, data, UI, and ops domains to reduce ambiguity and minimize back-and-forth during implementation. The output is a concrete spec, a verification plan, and a short list of unresolved questions or risks.

How this skill works

I capture objectives, scope, assumptions, and constraints, then choose the appropriate depth (lightweight or full-system) based on risk and cross-team impact. The spec is structured with mandatory sections, concrete, testable requirements, non-functional criteria, and clear verification steps. Every requirement is mapped to a verification method and completion criteria; traceability links and a status update are recorded.

When to use it

Defining a new feature, API, or system prior to design and implementation
Updating or restructuring an existing spec to remove ambiguity
Auditing specs to find missing requirements, edge cases, or testability gaps
Converting high-level or vague plans into verifiable acceptance criteria
Preparing cross-team or high-risk changes that need a full-system view

Best practices

Start with clear objectives and explicit in-scope/out-of-scope statements
Write requirements as verifiable statements with units, limits, and conditions
Always include success paths, edge cases, and failure behavior
Map each requirement to a concrete verification method and pass/fail criteria
Preserve existing repo naming and style; add domain sections but keep mandatory content

Example use cases

Drafting an API contract: endpoints, request/response schemas, error states, and load expectations
Converting product acceptance notes into testable requirements and a QA checklist
Reviewing a legacy spec to identify missing non-functional requirements and observability needs
Creating a rollout plan with verification commands and rollback criteria for an infra change
Auditing a cross-team feature to surface integration assumptions and ownership

FAQ

What deliverables do I get when you create a spec?

A complete spec document, a verification plan mapped to each requirement, and a list of unresolved questions or decision owners.

How do you decide between a lightweight spec and a full-system spec?

Choose lightweight for isolated, low-risk changes; choose full-system for cross-team, risky, or high-impact work. The same quality gates apply to both.