> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reviewing the Project Spec

> Read, refine, and approve your Project Spec using the Project Knowledge drawer and Knowledge chat

export const ProductName = "The Morph Platform";

export const productName = "the Morph Platform";

The **Project Spec** is the detailed document for your migration. It describes exactly how {productName} will transform your code across the repositories in your project. This page is about **that document** — how to review it, refine it with chat, and approve it.

You do that work inside the **Project Knowledge** drawer on the **Roadmap** (the product control is still named Project Knowledge). The first time {productName} generates your Project Spec, that drawer opens automatically so you can review the spec. Select **Project Spec** in the tree, use **Knowledge chat** to interact with {productName}, and approve when you are ready. Any time after that, go to the **Roadmap** and under **Modernization** click **Project Knowledge** to open the same drawer.

For wikis, rules, milestones in that drawer, diffs, and imports, see [Project Knowledge](/customization/project-knowledge).

<Warning>
  Take the time to review the Project Spec carefully. Once approved, it cannot be edited. If you need changes after approval, you'll need to start a new migration.
</Warning>

## Reviewing the Project Spec

After you submit your Modernization Goals, {productName} automatically generates the Project Spec. **Project Knowledge** opens the first time it is ready. To review:

1. Confirm **Project Spec** is selected in the tree (it usually is on first open)
2. Read the generated content and check that it captures your intent
3. Use **Knowledge chat** to ask questions, drill into sections, or request clarifications

**Later visits:** On the **Roadmap**, open **Project Knowledge** (**Modernization**), then select **Project Spec** in the tree.

<Tip>
  Once the Project Spec is ready, the **Roadmap** also surfaces a **Next Step** box at the top of the Getting Started checklist — "Approve your project spec to start planning your roadmap." with an **Approve Project Spec** button. Clicking that button opens the Project Knowledge drawer directly on the Project Spec, so you don't have to navigate through the tree yourself.

  While the spec is still generating you'll see the same box in a loading state ("Generating Project Spec…"); it switches to the actionable Next Step automatically once the spec is ready.
</Tip>

### What to Look For

* **Target stack** — Are the destination technologies correct?
* **Migration approach** — Does the planned transformation make sense?
* **Requirements** — Are all your constraints captured?
* **Scope** — Is it migrating the right parts of your codebase?

## Refining the Project Spec

If something needs adjustment, use **Knowledge chat** in the Project Knowledge drawer. Describe what should change—for example:

```
Add a requirement that all new APIs must return JSON and use
RFC 7807 problem details for errors.
```

```
The spec says we're moving to FastAPI, but we want Starlette
with Jinja2 templates for the admin UI only—please update that.
```

### What You Might Ask For

* Missing requirements or constraints
* Clearer wording on ambiguous sections
* Preferred libraries or patterns
* Scope corrections (include or exclude parts of the codebase)
* Constraints (e.g., "maintain backward compatibility")

### Iterating with {productName}

When the Project Spec has been updated, you can click **Auto-review** to have {productName} compare the latest version against the codebase analysis and your original intent. It may suggest:

* Clarifications for ambiguous statements
* Missing details that could cause issues
* Potential conflicts or inconsistencies

For each recommendation, you can **Accept** or **Reject** it. You must resolve all recommendations before approving.

## Approving the Project Spec

When you're satisfied with the Project Spec:

1. Resolve **Auto-review** recommendations (if any)
2. Click **Approve** in the Project Knowledge drawer
3. Confirm the approval

After approval, {productName} immediately begins planning your migration roadmap.

## What Happens After Approval

The approved Project Spec triggers **Roadmap Generation** — {productName} plans a sequence of milestones based on your Project Spec, the codebase analysis, and the project overview.

See [Milestones](/migration/milestones-and-tasks) for details on how the roadmap executes.

## Best Practices

### Be Explicit About Preferences

Don't assume {productName} will guess your preferences. If you want:

* A specific testing framework → say so
* A particular folder structure → specify it
* Certain naming conventions → include them

### Consider Edge Cases

Think about areas where defaults might not work:

* Configuration files that need special handling
* Environment-specific code
* Integration points with external systems

### Review with Your Team

If others will work with the migrated code, consider having them review the Project Spec before approval. They may catch requirements you missed. You can [hand over onboarding](/setup/collaborative-onboarding) to a teammate so they can review and refine the spec directly.

## Troubleshooting

### "I approved but now I need changes"

Once approved, the Project Spec is locked. To make changes:

1. Review what's already been generated (architecture, milestones)
2. If early in the process, consider starting a new project with updated goals
3. For minor adjustments, use [Rules](/customization/rules) to guide specific behaviors
4. For milestone-level changes, see [Editing Milestones](/customization/editing-milestones)

### "The **Auto-review** recommendations don't make sense"

Recommendations are suggestions, not requirements. If a recommendation doesn't apply to your situation, click **Reject** and proceed.

### "The Project Spec doesn't match my goal"

If the generated Project Spec significantly misses your intent:

1. Use **Knowledge chat** in Project Knowledge to correct the misunderstanding and ask for updates
2. Use **Auto-review** to validate after changes
3. Approve only when satisfied