From Coding To Completion

You have come a long way. Over the last two units, you have built the core components of RecipeBox — from data models and services to specifications and agent orchestration plans. You have written specifications, decomposed tasks, and used AI agents to orchestrate the entire build process. In our previous lesson, we focused on "Orchestrated Multi-Task Execution," where we saw how parallel workflows can drastically speed up development.

Now, we enter the final phase of the software development lifecycle: the Retrospective. In a professional setting, building the code is only half the battle. To be a top-tier engineer, you must also be able to document your technical decisions, measure your performance, and present your work to stakeholders. This lesson will show you how to synthesize everything you've learned into a professional portfolio piece that proves your mastery of Spec-Driven Development (SDD).

Before we finalize our project, let's briefly look back at the three pillars that made this build possible:

• The Specification (Course 1): We learned that a high-quality "blueprint" prevents expensive rework. By giving our AI agents a clear PRD and functional spec, we avoided the "what should this do?" confusion mid-build.
• Task Decomposition (Course 2): We broke a complex app into 23 small, atomic tasks. This allowed us to map out dependencies and identify which parts of the RecipeBox (like the Recipe API and Meal Planning) could be built at the same time.
• Agent Orchestration (Course 3): We used the task-executor agent to handle the heavy lifting. By giving the agent a "fresh context" for every single task, we ensured that the quality of the code stayed high from the first file to the last.

Documentation is the face of your project. If another developer looks at your code, they shouldn't have to read every line to understand how it works. On CodeSignal, you have access to a specialized doc-updater agent that helps you generate this documentation automatically.

First, let's look at how to structure a professional README.md. We can ask Codex to spawn the doc-updater agent to build this for us by providing the high-level features and architecture details.

Spawn a doc-updater agent: "Generate README.md for RecipeBox. Structure:

## RecipeBox
Brief description: Personal recipe manager with meal planning and shopping list generation

## Features
- Recipe Management: Create, edit, and organize recipes.
- Meal Planning: Plan weekly meals and adjust servings.
- Shopping Lists: Auto-generate lists from meal plans.

The agent will generate a clean structure. Once the structure is there, your job is to add the "human touch," such as specific installation steps or a diagram of your database.

Next, we need an ARCHITECTURE.md. While the README is for users, the ARCHITECTURE file is for developers. It explains the "how" behind your system. Here is how we might explain our data model:

## Data Model
RecipeBox uses 8 entities with specific relationships:
- Recipe → RecipeIngredients ← Ingredient (A many-to-many relationship)
- MealPlan → MealPlanItems → Recipe (A plan refers to multiple recipes)

In this documentation, we explain that our shopping list isn't just a list of items; it's an aggregation. If three recipes in your meal plan use eggs, the system must sum those eggs together into one single shopping list item. Writing this down helps you (and others) understand the logic you implemented.

An Architectural Decision Record (ADR) is a short document that captures a specific choice you made during development. This is a standard practice in production environments because it prevents teams from having the same argument twice.

Let's look at how to build an ADR for our database choice. We start with the Context (why we needed to make a choice).

# ADR-001: SQLite for Development Database

## Context
We need a database that is easy to set up for a learning project without requiring a full server installation like PostgreSQL.

Next, we state the Decision and the Alternatives we considered.

## Decision
Use SQLite for local development, while keeping the code compatible with PostgreSQL for production.

## Alternatives
- Full PostgreSQL: Rejected because it adds setup complexity for students.
- MongoDB: Rejected because our data (Recipes, Ingredients) is highly relational.

Finally, we list the Consequences. This is the most important part because it shows you understand the trade-offs.

## Consequences
- (+) Simple setup with no extra software.
- (-) Some advanced PostgreSQL search features aren't available.
- (Neutral) We use SQLAlchemy, so switching to PostgreSQL later is easy.

By following this pattern, you show that your technical choices are deliberate and calculated, not accidental.

The goal of SDD is to make development faster and of higher quality. To prove this worked, we perform a retrospective. We compare the Actual Time spent using SDD against the Estimated Time it would take to build manually.

In our RecipeBox project, the results look like this:

You might notice that we spent more time on specifications than a manual developer would. This is normal! In SDD, we move the effort "upstream." By spending 4 hours on a perfect spec, we saved nearly 10 hours during the coding phase because we didn't have to stop and fix mistakes or clarify requirements.

Beyond just time, we also measure Quality. In this project, we maintained 96% test coverage. In a typical manual project, coverage often drops as the project gets bigger because the developer gets tired or loses track of previous tasks. Because we used agent orchestration, Task 23 was just as high quality as Task 1.

The final piece of your portfolio is the demo. You have built complex logic, like the Serving Scaling Algorithm, and you want to show it off. A good demo script follows a logical flow.

Note: The examples below are simplified for clarity. In practice, all endpoints require a JWT token in the Authorization header, and the response shapes shown here are conceptual illustrations of the behavior being described.

First, you show the basic creation:

# Create a recipe for 4 people
curl -X POST http://localhost:8000/api/recipes -d '{"name": "Pasta", "servings": 4}'

Then, you show the "Magic" (the business logic):

# Add that recipe to a meal plan, but for 8 people
curl -X POST http://localhost:8000/api/meal-plans/1/meals -d '{"recipe_id": "1", "servings": 8}'

Finally, you show the result:

Response: {
  "message": "Meal added",
  "scaled_ingredients": [
    {"name": "Pasta", "amount": 800} # Originally 400g, now doubled!
  ]
}

By showing the inputs and the outputs, you demonstrate that your API isn't just a database; it's a tool that solves real problems for users.

You have completed the final lesson of the SDD Capstone. The practices ahead will give you the chance to apply everything you've learned. You have moved from high-level requirements to a production-ready application with documentation, tests, and metrics to prove its value.

Let's summarize the key patterns you can take to any future project:

• Domain Model First: Always draw your data relationships before you write a single line of code.
• Target a Spec Score of 85+: Use the 5-dimension framework to ensure your instructions are clear before the AI starts building.
• Phase Checkpoints: Review your progress every 4-6 tasks to keep the project on track without slowing down your momentum.
• Automated Quality Pipeline: Use agents to check your test coverage and documentation constantly.

In the upcoming practice exercises, you will use the CodeSignal IDE to complete the features section of your README.md, write an Architectural Decision Record, and calculate the SDD time efficiency metrics for your project. This is your chance to polish your work and complete your capstone. You should be very proud of the work you've done to master Spec-Driven Development. Happy coding!