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.

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.

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.

1

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.

2

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

3

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.

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

1

Open the Definition Tab Navigate to the project's Definition tab. The left panel lists the project definition ("Overview") and all existing specs.

2

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

3

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.

4

Set the Status Use the status dropdown to move the spec through its lifecycle as it progresses.

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), 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:

1

Open a Spec Navigate to any spec in the Definition tab.

2

Click the Cursor Agent Button A dialog opens showing a plan prompt derived from the spec content.

3

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.

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

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.