Specification Generator

A framework for guiding AI assistants to create comprehensive feature specifications through structured creativity

The Problem with AI-Generated Specifications

AI assistants are incredibly powerful at generating detailed technical documentation, but they often suffer from two critical flaws when creating product specifications:

1. Scope Creep - They get excited and design elaborate solutions that far exceed what was actually requested
2. Assumption-Making - They fill in gaps with their own interpretations rather than asking clarifying questions

The result? Beautiful, comprehensive documents that solve the wrong problem entirely.

The Solution: Creative Abandon Within Scope

This repository contains a battle-tested framework that solves both problems through a simple but powerful metaphor:

"First, build the fence. Then, explore every inch of the playground."

How It Works

The framework operates on a two-phase approach:

Phase 1: Build the Fence (Boundary Establishment)

The AI assistant must establish clear boundaries before any creative work begins:

• What should this feature not do?
• Can this be broken into phases?
• How does it integrate with existing systems?

Phase 2: Explore the Playground (Creative Abandon)

Once boundaries are locked down, the AI assistant is encouraged to be maximally creative and comprehensive within those constraints.

This approach leverages the AI's natural strengths (creativity, thoroughness, pattern recognition) while preventing its weaknesses (scope creep, assumption-making).

Three Approaches to Use This Framework

1. Primary Approach: AI-Generated Specifications (Formal Guidelines)

Use the formal guidelines to have an AI assistant generate comprehensive PRDs through intelligent conversation:

• File: guidelines/guidelines-for-creatively-generating-feature-specifications.md
• Best for: Most feature requests, especially when you have clear requirements
• Process: AI asks clarifying questions → establishes boundaries → generates complete PRD

2. Few-Shot Templates: Manual Templates as Examples

Use the templates as few-shot examples in AI prompts or for manual specification creation:

• Files:
  • templates/feature-specification-template-simple.md - For straightforward features
  • templates/feature-specification-template-full.md - For complex, strategic features
• Best for: Teaching AI "what good looks like," teams without AI access, highly regulated environments
• Process: Include template examples in AI context OR choose template → fill in sections → review with checklist

3. Freeform Exploration: Creative Fallback

Use the freeform guidelines only when the primary approach fails OR you specifically need creative solutions:

• File: guidelines/guidelines-for-freeform-feature-specification-generation.md
• Best for: Creative exploration when stuck, brainstorming novel solutions, when structured approaches aren't working
• Process: Creative overflow → migrate essentials to formal specification

All three approaches have the capacity to produce high-quality output - choose based on your scenario and needs.

When to Use Which Approach

Scenario	Recommended Approach	Why
Most feature requests	Primary (Formal)	Structured approach prevents scope creep and ensures completeness
Teaching AI "what good looks like"	Few-Shot Templates	Templates serve as concrete examples in prompts
Teams without AI access	Few-Shot Templates	Manual templates provide structure and learning scaffolding
Complex system integrations	Primary (Formal)	AI can handle complexity while maintaining coherence
Simple bug fixes	Few-Shot Templates (Simple)	Quick, straightforward documentation
Regulated environments	Few-Shot Templates	Full control over every word written
When primary approach fails	Freeform Exploration	Creative rescue when structured approach isn't working
Novel, unexplored features	Freeform → Primary	Creative exploration, then migrate to structured spec
Need creative solutions	Freeform Exploration	When you specifically need innovative approaches

Why This Framework Works

The Power of Metaphor in AI Instruction

Traditional AI prompting often relies on rigid rules and lengthy instructions. But well-chosen metaphors can be far more effective because they:

• Create immediate mental models - The AI "gets it" intuitively
• Are memorable - The core concept stays consistent throughout long conversations
• Capture intent, not just rules - The AI follows the spirit rather than mechanically following steps

The playground metaphor immediately communicates the desired behavior: creative exploration within defined limits.

Addressing the 80/20 Problem

Most users (80%) come to AI assistants with clear problems and goals already in mind. Traditional specification processes bog these users down with basic questions about problem definition and target users.

This framework flips the priority:

• Essential questions focus on boundaries and constraints
• Scope control questions handle the basics (only when needed)
• Context-dependent questions gather implementation details

Creative Abundance vs. Creative Paralysis

Many specification frameworks attempt to control AI creativity through restrictions. This framework takes the opposite approach: it unleashes creativity by first establishing safe boundaries.

The result is specifications that are both:

• Comprehensive - Exploring every possibility within scope
• Focused - Never straying beyond defined boundaries

The Framework in Action

Here's how a typical specification process unfolds:

1. User provides initial request - Often brief or high-level
2. AI establishes boundaries first - "What should this NOT do?"
3. AI confirms scope and phasing - "Can this be broken down?"
4. Creative exploration begins - Within the established constraints
5. Comprehensive PRD generated - Thorough but focused

Sample Interaction Flow

User: "I need a user dashboard for our app"

AI: "Before I design this dashboard, let me establish some boundaries:
- What should this dashboard NOT include or do?
- Are there any existing features this shouldn't overlap with?
- Should this be built all at once, or can we phase it?"

User: "Don't include admin functions, don't duplicate the settings page, 
and let's start with just the core metrics."

AI: "Perfect! Now I can explore every possibility for a user dashboard 
focused on core metrics, avoiding admin functions and settings overlap. 
Let me create a comprehensive specification..."

What You'll Find Here

guidelines/guidelines-for-creatively-generating-feature-specifications.md

The complete framework document containing:

• Clarifying Questions Framework - Prioritized question categories
• PRD Structure - Template for comprehensive specifications
• Guiding Principles - The core philosophy including "Creative Abandon Within Scope"
• Process Flow - Step-by-step implementation guide
• Testing Considerations - Integrated testing requirements and scenarios
• Feature Tagging Strategy - Institutionalized approach for descriptive tagging
• Implementation Journey Best Practices - Complete process from creative exploration to production

This isn't just documentation - it's a battle-tested system that consistently produces high-quality specifications while preventing the most common AI pitfalls.

Real-World Validation

See the examples/ directory for two battle-tested PRDs that led to successful implementations:

1. Budget Filtering - Complex business logic feature with 5 explicit constraints, delivered in record time
2. Persistent Display CSS Grid Solution - UI/UX optimization using creative exploration approach

These examples demonstrate the framework's evolution from theoretical guidelines to proven methodology with measurable results.

Getting Started

For AI-Generated Specifications:

1. Copy the guidelines file (guidelines/guidelines-for-creatively-generating-feature-specifications.md) to your AI assistant context
2. Use the activation prompt: "Please follow the Feature Specification / Product Requirements Document (PRD) guidelines. Feature request: [YOUR REQUEST]"
3. Let the AI establish boundaries first before exploring solutions
4. Watch it create comprehensive specs that actually meet your needs

For Manual Specifications:

1. Choose your template:
   • Simple: For bug fixes, minor enhancements, single features
   • Full: For major features, integrations, strategic initiatives
2. Fill out sections in order - Don't skip the boundaries!
3. Use the quality checklist before finalizing
4. Keep for reference during implementation

Results You Can Expect

Teams using this framework report:

• Faster specification cycles - Less back-and-forth clarification
• More focused features - Reduced scope creep and feature bloat
• Better AI collaboration - Clearer expectations and outputs
• Improved developer handoffs - Specifications that junior developers can actually implement

Why Open Source This?

Product managers, developers, and AI practitioners everywhere struggle with the same challenge: how to harness AI's creative power without losing control of scope and requirements.

This framework represents dozens of iterations and real-world testing, building on inspiration from innovative work in the open-source community - particularly Aaron Nichols and Ryan Carson, whose projects demonstrated the power of structured AI collaboration.

By open-sourcing this approach, I hope to:

• Standardize AI specification practices across teams and organizations
• Enable better human-AI collaboration in product development
• Demonstrate the power of metaphor-driven AI instruction

Contributing

This framework is the result of practical experimentation with AI-assisted product development. If you have improvements, variations, or real-world results to share, contributions are welcome.

The goal is simple: make AI assistants better partners in building great software.

---

"The framework explicitly tells an AI Assistant: 'First, build the fence. Then, explore every inch of the playground.'"