spec-development_skill

Overview

This skill guides research-first specification development for software and process changes. It enforces a disciplined, collaborative flow: create a research file, discuss until requirements are unambiguous, draft a spec, confirm with the user, then hand off to execution. Announce at start: "Using spec-development. What are we speccing?"

How this skill works

The skill inspects requirements, ambiguity, and existing documentation, then drives a structured discussion to define terms, scope, and decisions. It requires creating a research.md before investigation, logs findings and decisions immediately, and produces a spec.md with required sections (overview, scope, steps, verification, execution plan). The agent always proposes options and asks the user to confirm each decision before proceeding.

When to use it

• When you need a formal spec before any implementation
• When requirements are ambiguous or multiple approaches exist
• When changes affect multiple files, teams, or release processes
• When you must document rationale and trace decisions
• When you need a repeatable template for recurring processes

Best practices

• Always create the research file first and get user confirmation before any work
• Propose options with pros/cons and ask the user to choose — never assume decisions
• Define every term used in the spec; don’t proceed on vague language
• Address one change or question per message to avoid bundling
• Log findings and decisions immediately, but ask before logging anything not explicitly required
• Include an explicit execution plan and ask the user to approve execution mode

Example use cases

• Drafting a deployment procedure that affects multiple services and rollback criteria
• Designing a data migration plan with verification and testing steps
• Creating a standards spec for naming, priority, or acceptance criteria across repos
• Converting an ad-hoc process into a repeatable template and documentation
• Preparing a handoff-ready spec before code or infra changes are executed