Chapter 10 Exercises: Specification-Driven Prompting

These exercises are organized into five tiers of increasing difficulty, aligned with Bloom's taxonomy. Work through them in order, as later exercises build on skills developed in earlier ones.

Tier 1: Remember and Understand (Exercises 1-6)

Exercise 1: Specification Vocabulary Matching

Match each specification type to its primary purpose:

Exercise 2: Identify the Specification Level

For each of the following prompts, identify which level of specification precision it represents (Level 1: Vague, Level 2: Rough, Level 3: Detailed, Level 4: Formal):

a) "Make a weather app."

b) "Build a weather dashboard using React that shows current conditions and a 5-day forecast, using the OpenWeatherMap API."

c) "Build a weather app with React. Should show weather data."

d) A complete OpenAPI specification defining endpoints for /api/weather/current?city={city} and /api/weather/forecast?city={city}&days={days} with full request/response schemas, error codes, and rate limiting rules.

Exercise 3: Requirements Classification

Classify each requirement as Functional (FR) or Non-Functional (NFR):

a) "The system shall allow users to upload profile pictures in JPEG or PNG format, maximum 5MB." b) "All API responses shall be returned within 300 milliseconds under normal load." c) "The system shall encrypt all personally identifiable information at rest using AES-256." d) "The system shall send a welcome email when a new user registers." e) "The system shall support 5,000 concurrent users." f) "Users shall be able to export their data in CSV format."

Exercise 4: User Story Components

For the following user story, identify the role, capability, and benefit. Then list three missing elements that would make it a better AI prompt:

As a project manager, I want to generate reports
so that I can track team progress.

Exercise 5: Specification Format Recognition

Examine this specification fragment and identify which format it uses and what framework or tool it is designed for:

paths:
  /api/tasks:
    get:
      summary: List all tasks
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, in_progress, completed]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'

Exercise 6: Contract Identification

Given the following function signature with docstring, identify the preconditions, postconditions, and potential invariants:

def transfer_funds(
    from_account: str,
    to_account: str,
    amount: Decimal
) -> TransferResult:
    """Transfer funds between two accounts.

    The amount must be positive and the source account must have
    sufficient balance. After transfer, the sum of both account
    balances must remain unchanged. Neither account balance may
    be negative after the transfer.
    """

Tier 2: Apply (Exercises 7-12)

Exercise 7: Vague to Specified

Take the following vague prompt and rewrite it as a Level 4 formal specification. Include data model, API endpoints, validation rules, and error handling:

Build a todo app.

Your specification should define at least: the todo item data model, CRUD endpoints with request/response schemas, status workflow (e.g., pending -> in_progress -> completed), and authorization rules.

Exercise 8: Write User Stories with Acceptance Criteria

Write three complete user stories with Gherkin-style acceptance criteria (GIVEN/WHEN/THEN) for an online food ordering system. Each story should have at least four acceptance criteria covering the happy path, error cases, and edge cases.

Stories to write: - Adding items to a cart - Applying a discount code - Placing an order

Exercise 9: SQL Schema Specification

Write a complete SQL schema for a simple blog platform with the following entities: - Users (with authentication fields) - Posts (with draft/published status) - Comments (nested, supporting replies) - Tags (many-to-many with posts)

Include all constraints, indexes, and foreign key relationships. Then write a prompt that uses this schema to ask AI for a SQLAlchemy model layer.

Exercise 10: Test-First Specification

Write a complete pytest test suite (at least 8 tests) for a PasswordValidator class that enforces the following rules: - Minimum 8 characters - At least one uppercase letter - At least one lowercase letter - At least one digit - At least one special character from: !@#$%^&* - Cannot contain the user's email username - Cannot be in a list of common passwords

After writing the tests, use them as a prompt for AI to implement the class.

Exercise 11: OpenAPI Specification

Write an OpenAPI 3.1 specification for a bookmark management API with the following endpoints: - POST /bookmarks (create) - GET /bookmarks (list with filtering and pagination) - GET /bookmarks/{id} (get single) - PUT /bookmarks/{id} (update) - DELETE /bookmarks/{id} (delete) - POST /bookmarks/{id}/tags (add tags) - GET /bookmarks/search (full-text search)

Include complete request/response schemas, error responses, and authentication requirements.

Exercise 12: Interface Specification

Write a Python Protocol class for a NotificationService that supports: - Sending email notifications - Sending SMS notifications - Sending push notifications - Querying notification status - Listing notification history for a user

Include complete type hints, docstrings with preconditions and postconditions, and custom exception types.

Tier 3: Analyze (Exercises 13-18)

Exercise 13: Specification Gap Analysis

Review the following specification and identify at least five gaps or ambiguities that would cause AI to make incorrect assumptions:

# User Registration Spec
POST /api/register
Body: { email, password, name }
Response 201: { user_id, email, name }
Response 400: { error }

# User Login Spec
POST /api/login
Body: { email, password }
Response 200: { token }
Response 401: { error }

For each gap, explain what assumption an AI might make and how you would fix the specification.

Exercise 14: Specification Comparison

Given the same feature (a shopping cart), compare these two specification approaches and analyze their strengths and weaknesses for AI prompting:

Approach A: Requirements document with 15 functional requirements Approach B: Test suite with 20 pytest test cases

Write a 300-word analysis covering: precision of behavior definition, coverage of edge cases, ability to verify AI output, and maintainability over time.

Exercise 15: Specification Decomposition

You have been given a monolithic specification for an e-commerce platform (5 pages long). The AI assistant's context window cannot handle it all at once. Design a strategy to decompose this specification into manageable chunks that can be fed to the AI incrementally while maintaining consistency.

Define: what chunks you would create, what order you would implement them in, and what shared context you would include with each chunk.

Exercise 16: Specification vs. Implementation Detection

For each of the following, classify it as a specification statement (S) or an implementation instruction (I). If it is an implementation instruction, rewrite it as a specification:

a) "Use a binary search tree for the index." b) "Queries must return within 100ms." c) "Create a function called validate_email that uses regex." d) "Email addresses must conform to RFC 5322 format." e) "Store the data in a Python dictionary with the user ID as the key." f) "Each user can have at most 10 active sessions." g) "Implement the Observer pattern for event handling." h) "The system must notify administrators when disk usage exceeds 90%."

Exercise 17: MoSCoW Prioritization Exercise

You are building a project management tool. Categorize the following 12 features using MoSCoW prioritization and justify each decision in one sentence:

1. User authentication
2. Create/edit/delete projects
3. Kanban board view
4. Time tracking
5. File attachments
6. Activity audit log
7. Email notifications
8. Mobile responsive design
9. Gantt chart view
10. Third-party integrations (Slack, GitHub)
11. Team member roles and permissions
12. Custom report builder

Exercise 18: Test-First Analysis

Given the following test, reverse-engineer the specification it implies. Write out the complete business rules, edge cases, and data types that the implementation must handle:

def test_discount_calculation():
    cart = ShoppingCart()
    cart.add_item("SHIRT-001", quantity=2, price=Decimal("29.99"))
    cart.add_item("PANTS-001", quantity=1, price=Decimal("49.99"))

    assert cart.subtotal == Decimal("109.97")

    cart.apply_discount("SAVE10")
    assert cart.discount_amount == Decimal("10.997")
    assert cart.total == Decimal("98.973")

    cart.apply_discount("FREESHIP")
    assert cart.shipping_discount == True
    assert cart.shipping_cost == Decimal("0.00")

    with pytest.raises(DiscountLimitError):
        cart.apply_discount("ANOTHER20")

Tier 4: Evaluate (Exercises 19-24)

Exercise 19: Specification Quality Review

Review the following OpenAPI specification and rate it on a scale of 1-5 for each criterion: completeness, consistency, clarity, and correctness. Provide specific feedback for each rating:

openapi: 3.0.0
info:
  title: Notes API
paths:
  /notes:
    get:
      responses:
        200:
          description: List of notes
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                content:
                  type: string
      responses:
        201:
          description: Created
  /notes/{id}:
    get:
      parameters:
        - name: id
          in: path
      responses:
        200:
          description: A note
    delete:
      responses:
        204:
          description: Deleted

Exercise 20: Specification Approach Selection

For each of the following scenarios, evaluate which specification approach (or combination) would be most effective and justify your choice:

a) A solo developer building a personal finance tracker over a weekend b) A team of five building a healthcare API that must comply with HIPAA c) A startup building an MVP to demo to investors next week d) A data science team building an internal data pipeline e) A team rewriting a legacy system with existing documentation

Exercise 21: Specification Overhead Analysis

Calculate the time investment of specification-driven prompting vs. iterative conversational prompting for the following scenario:

You need to build a REST API with 8 endpoints. Based on experience: - Writing a full OpenAPI spec takes ~2 hours - Each conversational prompt iteration takes ~15 minutes - Without specs, each endpoint requires ~3 iterations to get right - With specs, each endpoint requires ~1 iteration

Show the math and discuss when the specification investment pays off.

Exercise 22: Critique a Specification Template

The following specification template is used by a development team. Identify at least five problems with it and propose improvements:

# Feature Spec Template
Feature name:
Description:
Requirements:
- [list requirements]
Tech stack:
Database changes:
- [list changes]
API changes:
- [list changes]
Done when:
- [list criteria]

Exercise 23: Cross-Specification Consistency Audit

Given the following three specification fragments for the same system, identify all inconsistencies between them:

Fragment 1: SQL Schema

CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    status VARCHAR(20) DEFAULT 'pending',
    total DECIMAL(10,2),
    created_at TIMESTAMP DEFAULT NOW()
);

Fragment 2: API Spec

/orders:
  post:
    requestBody:
      schema:
        properties:
          user_id:
            type: string
            format: uuid
          items:
            type: array
          total:
            type: number
            format: float

Fragment 3: Pydantic Model

class Order(BaseModel):
    id: int
    user_id: UUID
    status: Literal["new", "processing", "shipped", "delivered"]
    total: Decimal
    created_at: datetime
    updated_at: datetime

Exercise 24: Evaluate AI Output Against Specification

Given the specification below and the AI-generated code that follows it, evaluate the code's compliance. List all deviations from the spec, classify each as critical, major, or minor, and explain what you would fix:

Specification: "Implement a rate limiter that allows max 100 requests per minute per API key. Use a sliding window algorithm. Return HTTP 429 with a Retry-After header when rate limited. Include X-RateLimit-Remaining and X-RateLimit-Reset headers in all responses."

AI-Generated Code (to evaluate):

from collections import defaultdict
import time

class RateLimiter:
    def __init__(self, max_requests=100, window_seconds=60):
        self.max_requests = max_requests
        self.window = window_seconds
        self.requests = defaultdict(list)

    def is_allowed(self, api_key: str) -> bool:
        now = time.time()
        self.requests[api_key] = [
            t for t in self.requests[api_key]
            if now - t < self.window
        ]
        if len(self.requests[api_key]) >= self.max_requests:
            return False
        self.requests[api_key].append(now)
        return True

Tier 5: Create (Exercises 25-30)

Exercise 25: Full Specification for a New Feature

Write a complete specification for adding a "favorites" or "wishlist" feature to an existing e-commerce application. Your specification must include: - Data model (SQL schema) - API endpoints (OpenAPI format) - User stories with acceptance criteria (at least 3 stories) - Test specifications (at least 10 tests) - Interface definition (Python Protocol) - Non-functional requirements

Exercise 26: Specification-First Project

Design and fully specify a URL shortener service. Write every specification document needed to have AI generate the complete application: 1. Requirements document (functional + non-functional) 2. Database schema 3. API specification (OpenAPI) 4. Test specification (pytest test cases) 5. Configuration specification 6. A deployment specification (Docker Compose)

Then use each specification as an AI prompt and evaluate the generated code against your specifications.

Exercise 27: Custom Specification Template

Design a specification template for a domain not covered in this chapter. Choose one: - IoT device management platform - Educational learning management system - Event-driven microservices architecture - Real-time collaborative editing system

Your template should include all relevant sections, with guidance comments explaining what to fill in for each section.

Exercise 28: Specification-Driven Refactoring

Take a piece of existing code (your own or an open-source project) that lacks clear specifications. Write retroactive specifications for it (document what it currently does), then use those specifications to prompt AI to refactor the code for improved quality while maintaining identical behavior.

Exercise 29: Multi-Specification Integration

Create a complete set of specifications for a three-service microservice architecture: - Service A: User management - Service B: Content management - Service C: Notification service

Your specifications must define: each service's internal API, the inter-service communication contracts (including event schemas), shared data formats, and integration test specifications that verify the services work together.

Exercise 30: Specification Evolution

Design a versioned specification strategy for an API that must evolve over time without breaking existing clients. Define: - Version 1.0 of a resource API (4 endpoints) - Version 1.1 adding new optional fields - Version 2.0 with breaking changes

Write the OpenAPI specs for all three versions, a migration guide specification, and a prompt that asks AI to implement backward-compatible routing that serves all three versions simultaneously.

Solutions

Solutions to the coding exercises (Exercises 7, 9, 10, 11, 12) are available in code/exercise-solutions.py. For analysis and evaluation exercises, sample responses are provided in the answer key for instructors.