Key Concepts

Key Concepts

SpecGraph uses specific terminology throughout the platform. Understanding these concepts will make it much easier to navigate the workflow and communicate with your team.

Project

A project is the central container for all work in SpecGraph. Each project represents a single product initiative, feature set, or specification effort. A project has:

• A name and description
• A set of uploaded documents
• A PRD (Product Requirements Document)
• Surveys for each department
• Wishes collected from those surveys
• Conflicts detected between wishes
• Approvals from designated stakeholders
• An exported specification

Projects progress through a series of phases from start to finish.

Phase

A phase represents the current stage of a project. Phases are sequential — each one gates the next, ensuring the workflow is followed correctly. The full phase sequence is:

You can see the current phase on any project card on the Dashboard and in the project detail page's progress bar.

PRD (Product Requirements Document)

The PRD is the core output of SpecGraph. It's a structured document that defines what a product or feature should do, who it's for, and how it should behave. In SpecGraph, the PRD is:

1. Initially generated by AI from your uploaded documents.
2. Enriched by department wishes collected via surveys.
3. Unified by AI after conflicts are resolved.
4. Locked once all stakeholders approve.

The PRD is divided into sections (e.g., Objectives, User Stories, Functional Requirements, Non-Functional Requirements). Each section can receive comments and is tied to specific wishes.

Wish

A wish is a single structured requirement submitted by a department. The term "wish" is intentional — it represents what a department wants from the product, before trade-offs and prioritization happen. Wishes can be:

• Feature Requests — new capabilities the department wants added.
• Enhancements — improvements to existing functionality.
• Concerns — risks, constraints, or objections.
• Questions — clarifications the department needs before they can finalize input.

Every wish includes a title, description, priority, effort estimate, and optional budget impact. Wishes are visible to all departments, and team members can vote on them to signal priority.

Survey

A survey is the mechanism through which a department submits their wishes. When a project lead opens surveys, each department in the organization receives a unique survey link. The survey shows the department the current AI-generated PRD and asks them guided questions to elicit their requirements.

Surveys are asynchronous — departments can complete them at their own pace before the deadline. A department's survey can be submitted once and reviewed by the project lead.

Conflict

A conflict arises when two or more wishes from different departments are contradictory or mutually exclusive. For example, if Engineering wants to use a lightweight database and the Security team requires an enterprise-grade encrypted solution, those wishes conflict.

SpecGraph's AI automatically detects conflicts after all surveys are submitted. Each conflict includes:

• A description of what's in conflict.
• An impact analysis showing which PRD sections would be affected by each resolution path.
• Discussion threads where team members can debate.
• Resolution options with votes, so the team can collectively choose a path forward.

Conflicts are classified by severity: Critical, High, Medium, or Low. Critical and high-severity conflicts must be resolved before the project can advance.

Unification

Unification is the process of merging the original AI-generated PRD with all approved wishes and conflict resolutions into a single, coherent specification. This is done by AI after all conflicts are resolved.

The project lead chooses a unification strategy (Conservative, Balanced, or Aggressive) to control how aggressively department wishes are incorporated into the final spec.

Approval

An approval is a formal sign-off from a designated stakeholder that the unified PRD is acceptable. Before a PRD can be locked, all required approvers must either approve or reject it with comments.

Approvers are typically department leads, senior stakeholders, or product owners. They review the full unified PRD and use the Approvals page to submit their decision.

Export

The export is the final output of a locked SpecGraph project. It packages the PRD and all related artifacts into structured markdown files designed to be fed directly into AI coding tools. The export includes the full specification, acceptance criteria, agent instructions, and implementation guidance.

Organization & Department

SpecGraph is structured around organizations (your company or team) and departments within them (e.g., Engineering, Design, Legal, Finance). Departments determine:

• Which surveys a user participates in.
• How wishes are attributed and grouped.
• How conflict impact is assessed by team.

Users can belong to multiple organizations and switch between them using the organization switcher in the left sidebar.

AI Agents

After a PRD is locked, SpecGraph can generate AI coding agents — specialized AI personas configured to implement specific parts of the project. Each agent has a defined role (e.g., Architect, Developer, QA Engineer) and is given the relevant sections of the PRD to work on. Agents are designed to be used with AI coding tools like Claude Code.

Knowledge Base

The Knowledge Base captures lessons learned, recurring patterns, and reusable insights from completed projects. When a project is closed, AI can extract knowledge from the project's history and store it for future reference across the organization.