Specs Kit Brainstorm

Brainstorming

Provides guided brainstorming to transform ideas into pure functional specifications (WHAT, not HOW). Focus on business logic, use cases, and acceptance criteria — no code, frameworks, or technical patterns.

Overview

This command produces a functional specification — a document that describes WHAT the system should do, without HOW it will be implemented.

The new workflow:

Idea → Scope Assessment → Functional Specification (docs/specs/[id]/) → Architecture & Ontology → Tasks → Implementation → Review → Cleanup → Done
         (Phase 1.5)          (WHAT, not HOW)                             (docs/specs/)               (spec-to-tasks)
                                                                          
If scope is TOO LARGE:
  Idea → Split into Spec A, Spec B, Spec C → Brainstorm each separately → Multiple focused specifications

Output: docs/specs/[id]/YYYY-MM-DD--feature-name.md

Preferred naming is YYYY-MM-DD--feature-name.md. If the spec folder already uses legacy *-specs.md files, keep the existing convention instead of mixing both formats.

Where [id] is a unique identifier in format NNN-feature-name (e.g., 001-hotel-search-aggregation).

What vs. How

Use this command when starting a new feature to define clear functional requirements before any technical decisions.

Usage

/skill:specs-kit-brainstorm [idea-description]

After generating the functional specification, continue with:

/skill:specs-kit-spec-to-tasks docs/specs/[id]/

Arguments

Current Context

The command will automatically gather context information when needed:

• Current git branch and status
• Recent commits and changes
• Available when the repository has history

Argument Details

idea-description

• Purpose: Describes the initial idea, feature, or problem to solve
• Format: Free text describing the concept
• Default: If not provided, the command will ask for it interactively
• Examples: "Add user authentication", "Design caching strategy", "Create a specification for subscription billing"
• Non-examples: "Fix this bug", "Modify this existing behavior", "Refactor payment module" → out of scope for this skill (it only produces new functional specifications)

You are helping a developer transform an idea into a fully formed design. Follow a systematic approach: understand the project context, explore the idea through targeted questions, explore existing code, propose alternative approaches, present the design incrementally, generate professional documentation, review the document, and recommend the next development command.

Core Principles

• Ask only high-signal questions: Use ask_user_question only when the answer materially changes scope, acceptance criteria, or constraints. If the request is already clear, proceed without adding extra checkpoints.
• Multiple choice preferred: Easier to answer than open-ended when possible
• YAGNI ruthlessly: Remove unnecessary features from all specifications
• Functional focus ONLY: Describe WHAT the system should do, never HOW it will be implemented
• No technical decisions: Do NOT mention frameworks, libraries, patterns, or code
• ADR constraint preservation: When the input is an ADR, RFC, or technical analysis document, the architectural decisions it contains are treated as immutable constraints for the functional specification. If the brainstorming process identifies a need to override an ADR decision, the override MUST be explicitly documented in decision-log.md with a DEC entry referencing the original ADR.
• Incremental validation: Present specification in sections, validate each
• Professional documentation: Use specialist agent for high-quality documents
• Be flexible: Go back and clarify when something doesn't make sense
• Use a checklist: Track all progress throughout
• No time estimates: DO NOT provide or request time estimates
• Scope awareness: Validate idea scope early; if too large, guide user to split into multiple focused specifications
• Documentation-only boundary: This command MUST NOT implement, patch, refactor, or modify application/source code. It may only create or update specification artifacts under docs/specs/ and related spec documentation files.
• Stay in scope: If the user asks to fix a bug, change existing behavior, refactor existing code, or "just make the modification", STOP and explain this skill only produces new functional specifications. Do not perform the change. Offer to model the desired end-state as a new specification instead, or stop.

Spec Lifecycle: Deliberate Death

Every specification has a limited lifespan. The spec is a living document that serves its purpose during implementation, but once the feature is built and verified, the spec transitions to a historical record.

The Spec Is Dead, Long Live the Spec

The spec dies when:

1. Implementation is complete and verified against the spec
2. The feature has been in production without spec-related issues
3. The spec has been superseded by a new version

The spec is NOT deleted:

• It becomes archived/ in the spec folder
• It remains as historical record
• Future changes reference it as "original spec" or "preceding spec"

Why "Deliberate Death"?

• Prevents spec rot: specs that never die become stale and misleading
• Encourages accurate specs: knowing a spec will be archived sharpens focus
• Supports knowledge transfer: archived specs provide valuable context
• Enables improvement: each spec lifecycle informs better next specs

Spec Death Protocol

1. During spec-to-tasks: Spec is alive, every decision traces back to it
2. During implementation: Spec guides, deviations are documented
3. During task-review: Spec is validated against, findings trace to spec
4. During sync: Spec is updated to reflect implemented behavior
5. After completion: Spec is archived, not deleted

Archive command (after feature completion):

mv docs/specs/[id]/YYYY-MM-DD--feature-name.md \
   docs/specs/[id]/archived/YYYY-MM-DD--feature-name.md

Add to archived/README.md:

## [Date] - [Feature Name] - COMPLETED
- Implementation: complete
- Status: verified against spec
- Superseded by: [link or N/A]

Requirement Syntax: EARS Standard

All functional requirements in the generated specification MUST use EARS syntax (Easy Approach to Requirements Syntax).

Syntax Forms

Mandatory Keywords

• SHALL — obligation (use for MUST requirements)
• WILL — intention (use for planned features)
• MAY — permission (use for optional behaviors)

Forbidden Words (cause ambiguity)

• "robust", "intuitive", "fast", "scalable", "efficient", "user-friendly"
• Replace with measurable criteria

Requirement ID Format

• Format: REQ-XXX (e.g., REQ-001, REQ-002)
• Numbering: Sequential per spec
• Placement: Before each requirement text

Example Good vs Bad

# BAD (vague)
"The system must be fast and secure."

# GOOD (EARS)
"The system SHALL encrypt all stored passwords with bcrypt and cost factor ≥12."

# BAD (missing trigger)
"The user receives a confirmation email."

# GOOD (EARS)
"WHEN a purchase is completed THEN the system SHALL send a confirmation email to the customer's registered address."

Validation Checklist

Before Phase 5 generation, verify:

• Every requirement has REQ-ID prefix
• Every requirement uses SHALL/WILL/MAY
• Every requirement has a trigger (WHEN/IF) or is generic
• No forbidden words present
• Each requirement is testable (can verify pass/fail)

Non-Goals Enforcement

Every specification MUST include an explicit "Non-Goals" section that lists what the feature does NOT do.

Purpose: Prevent AI agent from adding "helpful" features outside the intended scope.

Rules:

1. If the feature doesn't include social login → add "No social login providers"
2. If the feature doesn't support real-time → add "No real-time updates or WebSocket support"
3. If there's no admin panel → add "No administrative interface"
4. Always include at least 3 non-goals

Format:

## Non-Goals

This feature does NOT include:

- **Feature X**: [Brief explanation why excluded]
- **Feature Y**: [Brief explanation why excluded]
- **Feature Z**: [Brief explanation why excluded]

Trigger Pattern: "The system will NOT do X" or "X is out of scope for this feature"

Common Non-Goals Templates (use as starting point)

Web Application

• No social login (OAuth, Google, GitHub, etc.)
• No multi-language support (English only)
• No real-time updates (no WebSocket, SSE, or polling)
• No offline mode or PWA support
• No mobile app (web-only)

Backend/API

• No GraphQL (REST only)
• No async processing (synchronous only)
• No caching layer
• No message queue integration
• No third-party integrations

Database/Data

• No data export functionality
• No data import/migration tools
• No backup/restore utilities
• No data archiving

Security

• No two-factor authentication
• No role-based access control (RBAC)
• No API key management
• No audit logging

Operations

• No monitoring/observability setup
• No CI/CD pipeline setup
• No containerization
• No deployment automation

Rule: Start with project-specific exclusions, then add domain-specific ones.

Negative Requirements

Every specification SHOULD include explicit "Negative Requirements" that describe behaviors the system must NOT exhibit. These are constraints that prevent common failures, security issues, or anti-patterns.

Purpose

• Prevent failures: Define what the system MUST NOT do to avoid known failure modes
• Block security issues: Specify anti-patterns that must never appear (SQL injection, XSS, etc.)
• Document constraints: Make implicit exclusions explicit for future maintainers
• Guide implementation: Help developers avoid dangerous patterns during implementation

Negative Requirements vs Non-Goals

Common Categories

Security Constraints (OWASP Top 10 based):

• No SQL string concatenation (use parameterized queries)
• No eval() or dynamic code execution
• No hardcoded credentials or secrets
• No user-generated content without sanitization
• No insecure direct object references

Data Integrity Constraints:

• No lost updates (optimistic locking or versioning)
• No data loss on concurrent operations
• No state corruption on failure

Performance Constraints:

• No N+1 query patterns
• No blocking operations in request handlers
• No unbounded data structures

Reliability Constraints:

• No silent failures (errors must be logged)
• No single points of failure without mitigation
• No data inconsistency across services

Template Format

## Negative Requirements

The system SHALL NOT:

### Security
- [Constraint 1 with REQ-ID]
- [Constraint 2 with REQ-ID]

### Data Integrity
- [Constraint 3 with REQ-ID]

### Reliability
- [Constraint 4 with REQ-ID]

EARS Syntax for Negative Requirements

Example:

## Negative Requirements

The system SHALL NOT:

### Security
- REQ-NR001: IF user input is used in SQL query THEN the system SHALL NOT concatenate directly; it SHALL use parameterized queries with placeholders
- REQ-NR002: The system SHALL NOT store passwords in plain text; it SHALL use bcrypt with cost factor ≥12

### Data Integrity
- REQ-NR003: The system SHALL NOT allow concurrent updates to overwrite each other without detection; it SHALL implement optimistic locking

Generating Negative Requirements

During Phase 5, identify negative requirements by asking:

1. "What failures could occur if we don't specify this?"
2. "What security issues could happen with this feature?"
3. "What anti-patterns might developers use?"
4. "What race conditions or data corruption could happen?"

Validation Checklist

• At least 3 Negative Requirements present
• Each has REQ-NR prefix and EARS syntax
• Categories are identified (Security, Data Integrity, Reliability)
• No contradictions with positive requirements
• Directly traceable to anti-patterns or known failure modes

[NEEDS CLARIFICATION] Marker Rules

Every specification may include [NEEDS CLARIFICATION] markers to identify areas requiring user input. However, to prevent specification bloat and ensure actionable outcomes, markers are strictly limited to 3 maximum.

Why Maximum 3?

• Focus: Each marker represents a significant scope decision. Too many markers indicate the spec is not ready.
• Actionability: Resolving markers requires user time. More than 3 creates friction.
• Quality over quantity: Better to have 3 well-defined markers than 10 vague ones.

Marker Requirements

When to Use a Marker

Mark with [NEEDS CLARIFICATION: specific question] ONLY when ALL of these are true:

1. The choice significantly impacts feature scope or user experience
2. Multiple reasonable interpretations exist with different implications
3. No reasonable default exists for the domain

When NOT to Use a Marker (Make an Informed Guess Instead)

Marker Syntax

The system must support [NEEDS CLARIFICATION: which payment providers should be supported at launch?] for processing transactions.

The marker is placed INLINE within the requirement text. It does not replace the requirement — the requirement still stands with a best-guess default.

Marker Validation Checklist

Before Phase 5 generation, verify:

• Maximum 3 markers present in the specification
• Each marker has a specific question (not vague "needs clarification")
• Markers are inline within requirement text
• Markers are prioritized by impact (scope > security > UX > technical)
• No markers for areas with reasonable defaults

Marker Enforcement Examples

# GOOD: Specific question, high impact
The system SHALL process payments via [NEEDS CLARIFICATION: which payment providers should be supported at launch?] (Stripe, PayPal, or both?)

# BAD: Vague question
The system SHALL support payments via [NEEDS CLARIFICATION: what should we support?] (unspecified)

# BAD: Technical detail (has reasonable default)
The database should use [NEEDS CLARIFICATION: PostgreSQL or MySQL?] for storage.
→ Default: PostgreSQL. Document assumption in Assumptions section.

# BAD: Has reasonable default (REST API)
The system must expose [NEEDS CLARIFICATION: REST or GraphQL?] endpoints.
→ Default: REST. Document assumption in Assumptions section.

Marker Count Validation in Phase 5

After generating the specification:

1. Count all [NEEDS CLARIFICATION: occurrences
2. If count > 3: Flag the spec and identify the excess markers
3. For excess markers: Either convert to a best-guess assumption OR defer to a future spec-check session
4. Report final marker count in the completion summary

Hard Boundary: No Implementation During Brainstorming

This command is a specification authoring workflow only.

Allowed File Changes

The command may create or edit only specification artifacts, such as:

• docs/specs/[id]/YYYY-MM-DD--feature-name.md
• docs/specs/[id]/user-request.md
• docs/specs/[id]/brainstorming-notes.md
• docs/specs/[id]/decision-log.md
• docs/specs/ontology.md

Forbidden Actions

The command MUST NOT:

• Edit source code, tests, configuration, migrations, build files, or runtime assets
• Apply bug fixes, refactors, patches, or behavior changes
• Run code-formatting or code-modifying commands
• Create commits or branches for implementation work
• Treat a user request for "fix", "modify", "change", "patch", "refactor", "correggi", "modifica", "risolvi", or "sistema" as permission to change code

Required Response for Fix/Modification Requests

If the user request is primarily a bug fix or modification of existing behavior, respond with a message instead of implementing:

This request is a bug fix or change to existing behavior, so this skill is not the right tool: it only produces new functional specifications, and I will not modify code from here.

I can instead model the desired end-state as a new functional specification, if that helps. Otherwise, stop here.

After showing the message, always ask the user whether they want to create a new functional specification instead.

Use ask_user_question with these options:

• "Create a new functional spec" (continue only with documentation)
• "Exit without changes"

Only continue with brainstorming if the user explicitly confirms they want a new functional specification and not a direct code change.

Phase 0: Input Mode Detection & ADR Discovery

Goal: Determine whether the input is a free-form idea, an ADR/RFC, or a structured analysis document. If the input is a structured document, extract architectural decisions as constraints before proceeding.

Context: The the skill arguments parameter may contain:

• A free-text idea (e.g., "Add user authentication with JWT tokens")
• A path to an existing document (e.g., @docs/adr/039-git-worktree-management.md)
• A reference to a file containing architectural decisions, RFC, or analysis

Actions:

1. Detect input mode:

   • If the skill arguments contains a file path pattern (starts with /, ./, docs/, or @docs/): Structured Document Mode
   • If the skill arguments is free text describing a feature: Free-Form Idea Mode
   • If the skill arguments is empty: Ask user for input and detect mode from their response

2. If Structured Document Mode:

   • Read the referenced document
   • Extract all architectural decisions documented in the file:
     • Configuration values, defaults, and file paths
     • CLI flags and command structures proposed
     • Integration patterns with existing systems
     • Error handling and edge-case strategies
     • Directory structures and documentation conventions
   • Create a constraints list in memory with the extracted decisions
   • Do NOT re-evaluate these decisions — they are the architectural foundation. The functional specification must work within them.
   • If a decision in the ADR contradicts project conventions (e.g., architecture.md, ontology.md), flag it as a conflict, not as a candidate for change

3. If Free-Form Idea Mode:

   • Proceed directly to Phase 1 — no constraints to extract
   • The brainstorming will discover all decisions collaboratively

4. Decision override protocol:

   • If during brainstorming you identify that an ADR decision should be overridden:
     • Create a DEC entry in decision-log.md with:
       • Reference to the original ADR (e.g., "Overrides ADR-039, Section 3: Configuration")
       • Justification for the override
       • Impact on the specification
     • Only then modify the constraint
   • Without a DEC entry, ADR constraints remain immutable

5. Summarize constraints (Structured Document Mode only):

   • After extraction, produce a brief summary:

   Input Mode: Structured Document (ADR-039)
   Constraints extracted:
   - Config: worktreeBasePath (default: ../<repo-name>-worktrees)
   - CLI: No explicit flags mentioned
   - Integration: ADR-038 branch creation
   - Behavior: Worktree creation + manual cleanup command
   Override DEC entries: None / DEC-XXX
   

Phase 1: Context Discovery

Goal: Understand the current project state and the initial idea, within the bounds of any extracted constraints

Initial idea: the skill arguments

Actions:

1. Create todo list with all phases (including Phase 0 if Structured Document Mode)
2. Determine workflow tier before codebase exploration, document generation, or any action that could become implementation:
   • Bug fix (defect in existing system):
     • STOP the brainstorming workflow by default
     • Do NOT inspect files with the intent to patch them
     • Do NOT edit source code, tests, configuration, migrations, or build files
     • Explain that bug fixes are out of scope for this skill (it produces new specifications only)
     • Ask via ask_user_question only to confirm routing:
       • Options:
         • "Create a new functional spec" (only if the user wants a new specification instead of a bug fix)
         • "Exit without changes"
   • Modify existing behavior / refactor / delta change:
     • STOP the brainstorming workflow by default
     • Do NOT apply the requested change
     • Explain that modifications to existing behavior are out of scope for this skill (it produces new specifications only)
     • Ask via ask_user_question only to confirm routing:
       • Options:
         • "Create a new functional spec" (only if the user wants a new specification instead of a delta/change)
         • "Exit without changes"
   • Direct implementation request (e.g., "fix it", "make the change", "implement this now"):
     • Refuse to implement inside brainstorming
     • Explain that brainstorming only writes specs
     • Recommend the appropriate implementation/debugging workflow after a spec/task exists
   • New feature (any scope): Continue with brainstorm
3. Only after the request is confirmed as a new feature specification, explore the current project state (for context only - do NOT include in specification):
   • Read recent commits to understand what's being worked on
   • Check for existing documentation (README, docs/, existing specs)
   • Look for related features or similar implementations
4. If the idea is unclear, ask the user for:
   • What problem are they trying to solve?
   • What is the high-level goal?
   • Any initial thoughts or constraints?

Phase 1.5: Complexity Assessment & Scope Validation

Goal: Assess idea complexity early and guide user to split if scope is too large for a single specification

Actions:

1. Estimate implementation scope based on the idea description and context from Phase 1:

   • Count distinct user stories / use cases mentioned
   • Identify separate functional domains or bounded contexts
   • Note integration points with external systems
   • Assess data model complexity (entities, relationships)
   • Evaluate user interaction complexity (flows, edge cases)

2. Classify scope size using these indicators:

   Small Scope (proceed normally - will generate 3-8 tasks):

   • Single user story or use case
   • One functional domain
   • 0-2 integration points
   • Simple data model (1-3 entities)
   • Straightforward user flow
   • Examples: "Add password reset", "Implement search filter", "Add user profile photo upload"

   Medium Scope (proceed normally - will generate 8-15 tasks):

   • 2-4 user stories
   • One focused functional domain
   • 2-4 integration points
   • Moderate data model (4-8 entities)
   • Multiple user flows but related
   • Examples: "User authentication with roles", "Product catalog with categories"

   Large Scope (WARNING - will likely generate >15 tasks - see step 3):

   • 5+ user stories
   • Multiple functional domains or bounded contexts
   • 5+ integration points
   • Complex data model (9+ entities)
   • Multiple independent user flows
   • Examples: "Full E-commerce system", "Multi-provider travel aggregator", "Complete CRM system"

3. If scope is classified as LARGE:

   • Inform the user: "This idea has a very large scope. To ensure high-quality implementation and maintainable code, I recommend splitting it into smaller, focused specifications."
   • Propose a split strategy: Suggest 2-3 smaller specifications that cover the original idea incrementally.
     • Example split:
       • Spec 1: Core domain and data model
       • Spec 2: Primary user flows and API
       • Spec 3: Advanced features and integrations
   • Use ask_user_question to offer options:
     • Options:
       • "Split the idea into the suggested specifications" (recommended)
       • "Focus only on one part of the idea" (ask which one)
       • "Continue with a single large specification" (not recommended - warn about task count limit)
   • If user chooses to split: Focus the current brainstorming session on the FIRST part of the split.
   • If user chooses to focus on one part: Focus the current session on that part.
   • If user chooses to continue: Proceed with a warning that spec-to-tasks will reject the spec if it exceeds 15 tasks.

Phase 2: Idea Refinement

Goal: Clarify the requirements and constraints through a dialogue with the developer

Actions:

1. Ask up to 3 targeted questions to refine the idea:
   • Focus on ambiguities or missing information
   • Ask about edge cases or specific behaviors
   • Ask about integration with existing features
   • Ask about exclusions and negative requirements (what should the system NOT do?)
2. Incorporate any extracted constraints from Phase 0 into your questions
3. If the user provides a lot of information, summarize it to ensure alignment
4. If the user changes the idea significantly, restart the refinement phase

Negative Requirements Question: During Phase 2, ask about exclusions that could become Negative Requirements:

• "Are there security constraints or anti-patterns we must avoid?"
• "Are there known failure modes or race conditions to prevent?"
• "Are there data integrity constraints beyond normal validation?"

Phase 3: Functional Approach Exploration

Goal: Present 2-3 different functional approaches with trade-offs (WHAT, not HOW)

Actions:

1. Based on the refined idea, develop 2-3 distinct approaches focusing on BEHAVIOR:

   • Approach A: Simple/MVP (fastest to implement, may lack some features)
   • Approach B: Balanced (good feature set, reasonable complexity) - typically your recommendation
   • Approach C: Comprehensive (full-featured, more complex)

2. For each approach, describe ONLY functional aspects:

   • User behaviors supported
   • Business rules and constraints
   • Data requirements (what, not how)
   • Integration points (capabilities needed, not technical implementation)
   • Pros (benefits for users/business)
   • Cons (limitations, complexity for users)

3. CRITICAL: Do NOT mention any technical details:

   • NO frameworks (Spring, NestJS, React, etc.)
   • NO patterns (Repository, Service, Controller, etc.)
   • NO libraries or dependencies
   • NO code or pseudo-code

4. If there are materially different scope options, use ask_user_question to present them:

   • Lead with your recommended option
   • Explain your reasoning

5. If one approach is clearly dominant, select it, record the rationale, and proceed without an extra gate

6. After approach selection, log the decision:

   • Create an in-memory note of DEC-001: Approach Selection
   • Record: date, approach chosen, alternatives presented, rationale
   • This will be written to decision-log.md in Phase 6

Phase 4: Contextual Codebase Exploration (Optional)

Goal: Understand existing codebase for context only — do NOT influence the specification with technical decisions

NOTE: This phase is OPTIONAL. Skip if not needed. The functional specification should be technology-agnostic.

Actions:

1. Only if the feature needs to integrate with existing systems, explore the codebase directly (there is no subagent dispatch; do it in this session):

   Explore codebase for integration context — understand what existing systems, APIs, or data structures the new feature must integrate with.

   Focus on:

   1. Existing APIs or interfaces the feature must use
   2. Shared data structures or models
   3. Existing business rules that apply

   Return:

   • List of integration requirements (capabilities needed, not implementation)
   • Do NOT suggest frameworks, patterns, or technical solutions

2. Incorporate findings as integration requirements in the specification

3. Do NOT let this influence technical decisions — keep the specification functional

Phase 5: Functional Specification Presentation

Goal: Present the functional specification in validated sections

DO NOT START WITHOUT APPROACH APPROVAL

Template: Read the functional specification template at templates/functional-specification.md (in this skill directory) to understand the target structure. The specification MUST follow this template.

Actions:

1. Once the approach is selected, present the functional specification in sections of 200-300 words each

2. Incorporate any integration requirements from Phase 4

3. Cover the following areas in separate sections (matching the template structure):

   Section 1: Business Context (→ template: ## Business Context)

   • What problem does this feature solve?
   • Who are the users and what are their goals?
   • How does this fit into the overall system purpose?

   Section 2: Functional Requirements (→ template: ## Functional Requirements)

   • User stories and use cases
   • Business rules and constraints
   • Data requirements (what data, not how to store)
   • External system capabilities needed

   Section 3: User Interactions (→ template: ## User Interactions)

   • User flows and journeys
   • Alternative paths and edge cases
   • Error scenarios and how users are informed

   Section 4: Acceptance Criteria (→ template: ## Acceptance Criteria)

   • Clear, testable criteria for each user story
   • Success conditions in natural language
   • Edge case handling
   • MANDATORY: Acceptance Criteria Taxonomy — Every criterion MUST be classified with one of:
     • [IMP] Implementable: Requires new code, configuration, or explicit system behavior. Only these generate implementation tasks.
     • [SEF] Side-Effect: A natural, automatic consequence of an [IMP] criterion being satisfied. These do NOT generate standalone tasks but should be verifiable in e2e tests.
     • [EXT] External Verification: Verified by external tools, user observation, or existing system behavior. These do NOT generate tasks but should appear as e2e checkpoints.
   • 60% Rule: At least 60% of acceptance criteria should be [IMP]. If fewer than 60% are [IMP], the specification is too descriptive and not prescriptive enough — return to Section 2 and refine.
   • Why this matters: spec-to-tasks uses [IMP] criteria to generate atomic tasks. [SEF] and [EXT] criteria that are misclassified as [IMP] produce "false work" — tasks that verify natural behavior rather than implement functionality.

   Section 5: Integration Requirements (→ template: ## Integration Requirements)

   • What existing systems must integrate with (capabilities, not implementation)
   • Data exchange requirements (not technical protocols)

4. CRITICAL: Throughout all sections, NEVER mention:

   • Frameworks, libraries, or tools
   • Technical patterns or architectural styles
   • Code or pseudo-code

5. Validate only at meaningful checkpoints:

   • Default: generate all sections, then present one consolidated review
   • Use ask_user_question mid-way only if a section introduces new ambiguity or a major scope decision

6. If no major ambiguity is detected, proceed directly to Phase 5.3 and collect feedback on the complete draft

Phase 5.3: Non-Goals Definition

Goal: Explicitly define what this feature does NOT include

Actions:

1. Review the idea description and identify:

   • What was explicitly mentioned as out of scope
   • What was mentioned as in scope
   • Common related features that could be assumed

2. Brainstorm potential Non-Goals by asking:

   • "What would a developer naturally assume but is NOT in scope?"
   • "What related features could be 'helpful' but are excluded?"
   • "What technical capabilities are related but not required?"

3. Generate Non-Goals list (minimum 3):

   • Platform limitations (e.g., "No mobile app", "No offline mode")
   • Feature exclusions (e.g., "No social login", "No real-time sync")
   • Scope boundaries (e.g., "No multi-tenancy", "No plugin system")
   • Technical exclusions (e.g., "No WebSocket", "No GraphQL")

4. Format each Non-Goal:

   • Bold the excluded feature name
   • One sentence explaining why it's excluded
   • Connects to business logic when possible

Output:

## Non-Goals

This feature does NOT include:

- **Social Login**: Only email/password authentication is supported
- **Multi-language Support**: Interface is English only
- **Real-time Updates**: No WebSocket or SSE support
- **Admin Panel**: User management done via database directly
- **Export/Import**: No data migration utilities

Validation:

• Minimum 3 Non-Goals present
• Each Non-Goal has explanation
• No contradictions with functional requirements
• Non-Goals are mutually exclusive with requirements

Phase 6: Specification Generation

Goal: Generate professional functional specification document

Actions:

1. Compile all validated specification sections

2. Generate unique spec ID:

   • Count existing folders in docs/specs/ to determine next sequence number
   • Create slug from feature name (lowercase, hyphenated)
   • Format: NNN-feature-slug (e.g., 001-hotel-search-aggregation)
   • Example: If 5 specs exist, next ID is 006-feature-name

3. Create spec folder: docs/specs/[id]/

4. CRITICAL: Save the original user request:

   • Create a file user-request.md in docs/specs/[id]/ containing:
     • The original user input/idea description
     • Any constraints or requirements mentioned
     • This file will be used by spec-to-tasks to verify all requirements are captured
   • Example content:

     # User Request
     
     **Original Input**: [what the user asked for]
     
     **Key Requirements Mentioned**:
     - [requirement 1]
     - [requirement 2]
     
     **Constraints**: [any constraints mentioned]
     

5. Generate a professional functional specification document directly (there is no subagent dispatch; do it in this session), based on the following validated specification:

   Feature Title: [title] Date: [current date] Spec ID: [id] (e.g., 001-hotel-search-aggregation)

   Business Context:

   • Problem solved: [from Section 1]
   • Target users: [from Section 1]
   • System fit: [from Section 1]

   Functional Requirements:

   • User stories: [from Section 2]
   • Business rules: [from Section 2]
   • Data requirements: [from Section 2]
   • External capabilities: [from Section 2]

   User Interactions:

   • User flows: [from Section 3]
   • Alternative paths: [from Section 3]
   • Error scenarios: [from Section 3]

   Acceptance Criteria:

   • Testable criteria: [from Section 4 — each MUST be tagged with [IMP], [SEF], or [EXT]]
   • Success conditions: [from Section 4]
   • Edge cases: [from Section 4]
   • 60% Rule Check: Ensure at least 60% of criteria are [IMP]; if not, flag for refinement

   Integration Requirements:

   • Systems to integrate: [from Section 5]
   • Data exchange: [from Section 5]

   Non-Goals: [from Phase 5.3] Negative Requirements: [security, data integrity, reliability constraints] Open Questions: [list]

   Read the functional specification template at templates/functional-specification.md (in this skill directory) and use it as the document structure. Fill in the gathered information into the template sections. Save the result to: docs/specs/[id]/YYYY-MM-DD--feature-name.md

   IMPORTANT:

   • Read and follow the template at templates/functional-specification.md
   • This is a FUNCTIONAL specification, NOT a technical design
   • Do NOT mention any frameworks, libraries, or tools
   • Do NOT include code or pseudo-code
   • Focus on WHAT the system should do, not HOW
   • Use EARS syntax (SHALL/WILL/MAY) for all requirements
   • Include REQ-XXX prefix for each

…(truncated)