# Definition & Specs

The **Definition** tab is where you capture and maintain the scope, goals, and detailed requirements for your project. A project definition is the high-level overview, while specs break it down into discrete, trackable deliverables — each with its own lifecycle status.

{% hint style="success" %}
**From documents to definition in seconds**: Upload your RFP, SOW, and meeting transcripts to the project, then click **Generate** — Darcy will analyze everything and produce a structured project definition automatically.
{% endhint %}

## Project Definition

### What Is a Project Definition?

A project definition is a living document that captures the project's goals, scope, stakeholders, and context. It serves as the single source of truth for what the project is about and keeps everyone aligned. Definitions are written in Markdown and saved automatically as you edit.

### Generating a Definition with AI

If your project has items in its knowledge base (uploaded documents, meeting transcripts, etc.), Darcy can generate a definition for you.

{% stepper %}
{% step %}
**Open the Definition Tab** Navigate to the project and click the **Definition** tab. If no definition exists yet, you will see the empty-state options.
{% endstep %}

{% step %}
**Click "Generate a project definition"** Darcy begins analyzing your project's knowledge base and items using server-sent events (SSE). You will see:

* **Tool calls** — each research step Darcy performs (e.g., searching documents, summarizing meetings)
* **Streaming Markdown** — the definition appears in real time as it is generated
  {% endstep %}

{% step %}
**Review and Edit** Once generation is complete, the definition opens in the Markdown editor. Review the output, make any adjustments, and your changes save automatically.
{% endstep %}
{% endstepper %}

### Writing a Definition Manually

Prefer to write from scratch? Click **"Write manually"** on the empty state to open a blank Markdown editor with a suggested template:

* **Goals** — what the project aims to achieve
* **Scope** — what is and is not included
* **Stakeholders** — who is involved and their roles

All changes save automatically.

***

## Specs

### What Are Specs?

Specs are detailed sub-documents that break a project definition into discrete, trackable deliverables. Each spec focuses on a specific feature, workstream, or requirement and follows a structured template with sections for context, users, solution overview, features and acceptance criteria, out-of-scope items, commitments, and success metrics.

While the **definition** answers "what is this project?", each **spec** answers "what exactly are we building for this part?"

### Spec Lifecycle Statuses

Every spec has a status that tracks where it is in the review process:

| Status         | Meaning                                            |
| -------------- | -------------------------------------------------- |
| **Draft**      | Work in progress — still being written or refined  |
| **In Review**  | Complete and shared with stakeholders for feedback |
| **Approved**   | Finalized and accepted — ready for implementation  |
| **Superseded** | Replaced by a newer version or no longer relevant  |

Change a spec's status from the dropdown next to its name in the left navigation.

### Creating a Spec

{% stepper %}
{% step %}
**Open the Definition Tab** Navigate to the project's Definition tab. The left panel lists the project definition ("Overview") and all existing specs.
{% endstep %}

{% step %}
**Click the + Button** At the top of the specs list, click the **+** button. A new spec is created with the structured template pre-filled.
{% endstep %}

{% step %}
**Edit the Spec** The template includes sections for Context, Users, Solution Overview, Features & Functionality (with acceptance criteria), Out of Scope, Commitments, and Success Metrics. Fill in each section. All changes save automatically.
{% endstep %}

{% step %}
**Set the Status** Use the status dropdown to move the spec through its lifecycle as it progresses.
{% endstep %}
{% endstepper %}

### Searching and Managing Specs

* **Search**: Use the search bar in the left panel to filter specs by name
* **Navigate**: Click any spec to open it in the editor
* **Delete**: Click the delete button on a spec to remove it (with confirmation)

***

## Inline Feedback

Team members can leave feedback on specific sections of a definition or spec without leaving the page.

### Leaving Feedback

1. **Select text** in the definition or spec editor
2. A **Comment** action appears in the selection toolbar
3. Click it to open the comment popover and write your feedback
4. The feedback is posted as a **feedback thread** linked to the specific section heading

### Reviewing Feedback

* **Feedback badges** appear next to section headings that have unresolved feedback
* Click a badge to see the feedback and the commenter
* **Acknowledge** feedback to mark it as resolved, or **Decline** if it does not apply
* Use the **floating feedback list button** to see all unresolved feedback across the document and jump to each section

Feedback threads are also visible in the project's **Thread** tab, where they can be filtered by type.

***

## PR Citations

When your project is connected to GitHub (see [Development](/workspace/projects/development.md)), Darcy can create semantic links between pull requests and sections of your definition or specs.

### How Citations Work

* After PRs are reviewed, Darcy analyzes their content and maps them to relevant headings in your definition and specs
* **Citation badges** appear next to headings that have linked PRs
* Click a badge to see which PRs reference that section, with direct links to the PR detail panel

### Stale Citations

If the definition or spec content has changed since citations were last computed, badges appear as **stale**. Click the **Recompute Citations** button on the Development tab to refresh them.

### Why Citations Matter

Citations create traceability from requirements to implementation. When a stakeholder asks "has this been built?", you can see exactly which PRs address each section of the spec.

***

## Launching a Cursor Agent from a Spec

If your organization has both the **Cursor Cloud Agents** feature and a **GitHub connection** configured for the project, an additional action appears in the spec toolbar:

{% stepper %}
{% step %}
**Open a Spec** Navigate to any spec in the Definition tab.
{% endstep %}

{% step %}
**Click the Cursor Agent Button** A dialog opens showing a plan prompt derived from the spec content.
{% endstep %}

{% step %}
**Customize and Launch** Optionally add extra instructions and select a model. Click **Launch** to start the Cursor agent, then navigate to the Development tab to monitor progress.
{% endstep %}
{% endstepper %}

This bridges the gap between requirements and code — write a spec, then let an AI coding agent begin implementation.

***

## Best Practices

| Practice                          | Recommendation                                                                                |
| --------------------------------- | --------------------------------------------------------------------------------------------- |
| **Generate first, refine second** | Use AI generation to get a solid starting point, then edit by hand for precision              |
| **Keep definitions current**      | The Dashboard tracks definition freshness — update within 30 days to avoid staleness warnings |
| **Break into specs early**        | Don't wait for the definition to be perfect — create specs for known deliverables right away  |
| **Use feedback, not email**       | Leave inline feedback on specific sections instead of sending separate messages               |
| **Set status consistently**       | Move specs through Draft → In Review → Approved so the team knows what's finalized            |
| **Review citations regularly**    | After a sprint, recompute citations to see which specs have implementation coverage           |

{% hint style="info" %}
**Pro Tip**: When creating your first spec, use the Dashboard's "Create your first spec" checklist item — it opens Darcy Chat with a prompt that generates a spec based on your project definition and context.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.darcyiq.com/workspace/projects/definition-and-specs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.