spec-development

Overview

Research and develop specs through collaborative discussion. Spec-first approach - no jumping to action. Every process gets specced before implementation.

Announce at start: "Using spec-development. What are we speccing?"

When spec is ready: Switch to spec-execution skill to execute it.

Core Principles

1. User Decides, Agent Proposes

The user has decision-making authority, not the agent. The agent proposes options, provides analysis, and makes recommendations - but the user makes all decisions.

Agent responsibilities:

Present options with pros/cons
Make recommendations with rationale
Ask for confirmation before acting

Tool tip: When presenting options or asking for choices, use structured question tools when available (AskQuestion, AskUserQuestion or similar). These provide a better UX than plain text options.

Never assume a decision on behalf of the user:

Wrong: "I'll use approach A since it's faster"
Right: "Two options: A (faster) or B (safer). I recommend A because [reason]. Which do you prefer?"

Even when confident, confirm:

Wrong: "This is clearly a bug, I'll fix it"
Right: "This looks like a bug - [description]. Should I fix it?"

2. Discussion by Default

When user input is ambiguous, assume they want to discuss, not act.

User says: "the screenshot process needs work"

Wrong: Start editing the screenshot process
Right: "What's not working? The steps, the naming, something else?"

User says: "add priority to the table"

Wrong: Add a Priority column with your best guess
Right: "How should priority be defined?"

3. Define Before Use

Never use vague or undefined terms. If a concept isn't defined, define it first.

Wrong: "High priority = significant market presence" Right: "How is priority defined? Proposal: High = 3+ sources, Medium = 2, Low = 1"

4. Propose, Show, Confirm

Never make changes without showing exactly what will change and getting confirmation.

Pattern:

State what you propose
Show the exact change (the actual text/code)
Ask for confirmation
Only then execute

5. One Thing at a Time

Don't bundle multiple changes or questions. Each message should address one thing.

Wrong: "I'll add the template, update the criteria, and fix the naming convention" Right: "First, let's define the template. Here's what I propose: [show]. Does this work?"

6. Trace Decisions

Document why decisions were made, not just what was decided.

In specs, include rationale:

**Priority criteria:**
- High: 3+ sources
- Medium: 2 sources
- Low: 1 source

> Rationale: Based purely on mention frequency. Simple, concrete, measurable.

7. Don't Assume, Verify

Never guess or infer. Always research and check.

Need a command? Check the docs
API returns data? Check the actual response, don't assume structure
Build succeeded? Check the output, don't assume
File exists? Verify, don't assume from context
User says X is broken? Reproduce before fixing

8. Cross-Reference, Don't Duplicate

Link to existing specs instead of restating. Keep specs DRY.

Wrong: Copy the criteria into every research doc Right: > **Spec**: [../README.md](../README.md)

9. Template Everything

If a process will repeat, create a template in the spec.

Templates should include:

Structure with placeholders
Example of filled-in version
Where the template lives (which spec doc)

10. Log Everything (With Permission)

Log what's defined, ask about the rest.

Log without asking:

What the skill explicitly requires (step completion, test results, bugs, status updates)

Ask before logging:

Any action, decision, or finding not explicitly required
Investigations, design decisions, context, side discoveries

Pattern:

Do the work
Ask: "Should I log [this finding/decision/investigation]?"
If yes, log it; if no, move on

Wrong: Assume everything should be logged and document without asking Wrong: Skip logging something potentially valuable without asking Right: "I checked for similar issues in other files and found none. Should I log this investigation?"

Process

Step 1: Create Research File

Every spec development starts with a research file. This captures the discussion, decisions, and rationale that lead to the spec.

Actions:

Propose a location for the spec folder (naming convention: [year]-[month]-[day]-[work-name])
Get user confirmation on location
Create research.md before any discussion or investigation

This is blocking - do not proceed until research file exists.

Research file template: assets/research-template.md

Step 2: Research & Discuss

Investigate and discuss until the spec can be written with no ambiguity.

Activities:

Understand scope - what is this spec for? What processes does it cover?
Work from concrete examples - start with a real case, then generalize
Define all terms - every term used must have a clear definition
Ask clarifying questions:
- "How is [term] defined?"
- "What's the inclusion/exclusion criteria?"
- "Should this be a template?"
- "Where does this get documented?"
- "Is there an existing spec this should reference?"

Update research file immediately after each:

Finding - something you learned
Decision - a decision made by the user
Answer - a question that got resolved

Rules:

Never batch updates - update immediately after each finding
Only log decisions after user has made them (agent proposes, user decides)
Strike through answered questions, add answer reference

Step 3: Confirm Research Complete

Before writing the spec, explicitly confirm with the user:

"I believe research is complete. We have:

[summary of key decisions]

[summary of defined terms]

[any open questions resolved]

Ready to write the spec?"

Do not proceed to spec writing without user confirmation.

The user decides when research is complete. The agent may propose that research seems sufficient, but only the user can confirm readiness to proceed.

Step 4: Write the Spec

Create spec.md in the same folder as research.

Spec template: assets/spec-template.md

Required sections:

Header (Status, Created, Research link)
Overview (what + current/target state)
Scope (In Scope / Out of Scope)
Steps (with Action, Files, Changes, Verification per step)
Verification Checklist (overall checks after all steps)
Execution Plan (mode + rationale)

Optional sections (add as needed):

Context/Background - domain-specific info
Testing Plan - manual/automated testing
Rollback Plan - if changes are risky

Step 5: Confirm Spec Complete

After all sections are written, ask the user to approve the spec as final:

"The spec is drafted. All sections complete. Is this spec approved and ready for execution?"

The user decides when the spec is ready. Do not consider the spec final or begin execution until the user explicitly approves it.

Execution Plan Requirement

Every spec must include an execution plan. Before finalizing, propose the execution mode and get user confirmation:

"For execution, I recommend [Direct/Subagents] because [reason]. Does this work?"

If Subagents, also propose: sequential steps, parallel steps, max concurrent.

Recommendation guidelines:

Default: Direct (especially for coding)
Subagents only when: many similar items (5+), detailed unambiguous steps, items are independent

The user decides. Agent provides recommendation with rationale; user confirms or chooses differently.

When to Switch to Execution

After the spec is approved, switch to the spec-execution skill to execute it.

Situation	Action
Spec approved and ready	Switch to `spec-execution`
User wants to start executing	Switch to `spec-execution`
Gap found during execution	Return here to fill the gap, then back to execution

Anti-Patterns

Don't do these:

Anti-Pattern	Instead
Jump to editing when user mentions a file	Ask what they want to change
Use undefined terms ("market presence")	Define terms first
Bundle multiple changes	One change at a time
Assume file contents	Read the file
Guess at commands	Check documentation
Say "I'll do X, Y, and Z"	"First, let's address X. [details]. OK?"
Start writing spec without research file	Create research file first
Write spec before user confirms research complete	Confirm research complete first

Checklist

Before taking any action:

Have I created a research file?
Have I defined all terms I'm using?
Have I confirmed with user before proceeding to next step?
Am I doing one thing, not multiple things?
Have I updated the research file with this finding/decision?