AI Reasoning & Prompting
Relevant source files
The following files were used as context for generating this wiki page:
This document provides a comprehensive overview of the AI reasoning processes and effective prompting strategies used within the Spec-Driven Development framework. Understanding these concepts is crucial for collaborating effectively with AI systems to produce high-quality specifications. The goal is to provide transparency into how AI systems approach spec development, enabling users to provide better input, anticipate outcomes, and learn systematic thinking patterns.
Sources: spec-process-guide/ai-reasoning/README.md:18-28, spec-process-guide/prompting/README.md:18-28
AI Thought Processes
AI systems follow systematic analysis patterns when developing specifications. These patterns are applied across the three main phases of spec development: Requirements, Design, and Tasks. Understanding these thought processes helps in providing better input and anticipating how the AI will approach a given problem.
Sources: spec-process-guide/ai-reasoning/thought-processes.md:12-14
Requirements Analysis Pattern
When a feature request is initiated, the AI follows a structured mental model to decompose and understand the request before generating requirements.
This diagram shows the AI's initial processing pattern for a new feature request.
A key technique used is the "Five Whys" to determine the root requirement behind a user request. For example, a vague request like "Make the dashboard faster" is iteratively questioned to uncover the actual need, such as implementing progressive loading with prioritized widgets.
Sources: spec-process-guide/ai-reasoning/thought-processes.md:57-67
Design Analysis Pattern
During the design phase, the AI employs a structured reasoning pattern to translate requirements into a technical design. This involves mapping requirements to components, evaluating technical approaches, and identifying risks.
The following diagram illustrates the traceability the AI maintains from a requirement through design and into specific implementation tasks.
A critical part of design analysis is the trade-off analysis, where the AI systematically compares different options against weighted factors relevant to the project's context.
| Factors to Evaluate | Client-Side Rendering | Server-Side Rendering | Hybrid (SSG/SSR) |
|---|---|---|---|
| Performance (initial) | ⚠️ Slower | ✅ Fast | ✅ Fast |
| Performance (nav) | ✅ Instant | ⚠️ Slower | ✅ Instant |
| SEO | ❌ Poor | ✅ Excellent | ✅ Excellent |
| Complexity | ✅ Simple | ⚠️ Moderate | ⚠️ Complex |
| Cost | ✅ Low | ⚠️ Moderate | ⚠️ Moderate |
| Interactivity | ✅ Excellent | ⚠️ Limited | ✅ Excellent |
Sources: spec-process-guide/ai-reasoning/thought-processes.md:172-195
Task Planning Logic
For the final phase, the AI applies dependency analysis to break the design into a sequence of actionable tasks. The primary goals are to minimize blocking, enable early testing, and show incremental progress. Task sizes are calibrated to be achievable within a 2-6 hour timeframe for an experienced developer.
Sources: spec-process-guide/ai-reasoning/thought-processes.md:210-226, spec-process-guide/ai-reasoning/thought-processes.md:280-287
Core Prompting Strategies
Effective prompting is key to successful AI collaboration. The following strategies are designed to provide clear, structured input that leverages the AI's reasoning capabilities.
Sources: spec-process-guide/prompting/strategies.md:15-17
Strategy 1: Context-First Prompting
Always provide rich context before making a request. This includes project background, technology stack, constraints, and user information.
Poor Approach:
Create requirements for a user profile feature.
Better Approach:
I'm working on a web application for a fitness tracking platform. We need to add user profile functionality where users can manage their personal information and fitness goals.
Context:
- Technology: React frontend, Node.js backend
- User base: Health-conscious individuals, age 18-65
- Key constraint: Must comply with GDPR for EU users
- Integration: Will connect with existing authentication system
Please help me create requirements for the user profile feature.
Sources: spec-process-guide/prompting/strategies.md:22-44, skills/ai-prompting/SKILL.md:23-44
Strategy 2: Phased Interaction
Follow the spec-driven methodology by working through the Requirements, Design, and Tasks phases sequentially. Do not proceed to the next phase until the current one is complete and validated.
This diagram illustrates the phased interaction flow.
Strategy 3: Iterative Refinement
Treat spec development as a conversation. Build on the AI's responses, ask clarifying questions, and refine the output incrementally rather than expecting a perfect result from a single prompt.
This sequence diagram shows an example of iterative refinement for a spec.
Other Key Strategies
| Strategy | Description |
|---|---|
| Example-Driven Prompting | Provide concrete examples of the desired output format or quality to calibrate the AI. |
| Constraint-Explicit Prompting | Clearly state all functional and non-functional constraints, such as performance targets, budget, or infrastructure limitations. |
| Role-Based Prompting | Frame requests from the perspective of a specific role (e.g., Product Owner, Tech Lead, Developer) to get more targeted outputs. |
| Validation-Oriented Prompting | Ask the AI to review and validate its own output against a set of criteria, such as completeness, testability, or conflict detection. |
| Trade-Off Exploration | Instead of asking for a single "best" answer, ask the AI to compare several options and present the trade-offs in a structured format. |
Sources: spec-process-guide/prompting/strategies.md:111-200, skills/ai-prompting/SKILL.md:92-188
Prompting Best Practices & Troubleshooting
Phase-Specific Best Practices
- Requirements Phase: Start with user problems, not technical solutions. Use the "As a [role], I want [goal], so that [benefit]" format and specify measurable acceptance criteria. Avoid implementation details.
- Design Phase: Reference specific requirements when making design decisions. Explain trade-offs and consider scalability, maintainability, and non-functional requirements.
- Tasks Phase: Request tasks that build incrementally and can be completed in 2-4 hours. Specify testing requirements for each task and ensure dependencies are clear.
Sources: spec-process-guide/prompting/best-practices.md:52-101
Troubleshooting Common Issues
| Problem | Solution |
|---|---|
| Responses are too generic | Add more specific context, constraints, and concrete examples. Instead of "How should I structure my database?", provide schema details, user load, and performance targets. |
| Requirements keep changing (scope creep) | Establish a clear MVP scope first. Explicitly list core requirements for the initial version and defer "nice-to-have" features. |
| Design becomes too complex | Refocus on current requirements. Simplify the design to handle the current user load and tech stack, avoiding over-engineering for hypothetical future needs. |
| Tasks are too abstract | Request a breakdown into specific, actionable coding steps. Ask for exact files/components to create, functions to implement, and tests to write. |
Sources: spec-process-guide/prompting/best-practices.md:143-207
Quality Validation
Incorporate validation checks directly into your prompts to ensure high-quality outputs.
- Requirements Validation: Ask the AI to check for completeness, testability (e.g., using EARS format), and clear scope.
- Design Validation: Ask the AI to validate the design against all functional and non-functional requirements, and to check for well-defined interfaces and error handling.
- Task Validation: Ask the AI to check if tasks are specific, actionable, correctly sequenced, and include testing considerations.
Sources: spec-process-guide/prompting/best-practices.md:212-249
Conclusion
The Spec-Driven Development process is significantly enhanced by effective AI collaboration. This is achieved by understanding the AI's systematic reasoning patterns and employing structured, context-rich prompting strategies. By treating the process as an iterative conversation and building in validation at each phase, teams can leverage AI to create clear, comprehensive, and high-quality specifications that reduce ambiguity and minimize rework.
Sources: spec-process-guide/methodology/philosophy.md:49-52, spec-process-guide/prompting/strategies.md:264-270