Working with Specs
Specs are build specs generated for each priority.
Spec Sections
Every spec contains 5 core sections:
1. What to Build Clear, actionable task statement. One sentence describing exactly what to implement.
2. Why It Matters Business context — who's affected, revenue impact, urgency level.
3. Customer Voice Real quotes from feedback:
- Key Quote — The most impactful verbatim quote (5–20 words)
- Supporting Quotes — 3 additional quotes with user type and emotion
4. Files to Touch Suggested code locations (requires GitHub connection):
- File paths with (new) or (modify) labels
- Based on your connected repository structure
5. Done When Clear exit criteria: what defines success.
Specs may also include conditional sections when relevant:
- Heads Up — Warnings, risks or constraints the builder should know before starting
- What Circuit Remembers — Previous ships, corrections and related context (see Memory)
- Competitive Context — When customers mention competitors, a short summary of who and why
Spec Status
| Status | Meaning | Next Action |
|---|---|---|
| Ready | Waiting for action | Start building |
| Building | In progress | Complete and ship |
| Shipped | Feature deployed | Share back with customers |
| Shared | Complete — customers notified | Monitor feedback for V2 |
Working with Specs
View a spec: Click any priority to expand and see the spec inline.
Edit a spec: Click the edit icon to open the full spec in an editor. Make your changes, then click Save to apply. Changes are saved as a new version.
Refresh spec: Click the refresh icon to regenerate with the latest feedback data. A Refresh badge appears automatically when new feedback has changed the scope since the spec was last generated.
Section-aware refresh: when you refresh, sections you've manually edited are preserved. Only untouched sections regenerate. Your edits are never overwritten.
Version history: Click V1, V2, etc. to compare previous versions. Two triggers create a new version: new feedback arriving on a shipped spec (automatic) or you editing or refreshing a spec (manual). All versions are kept indefinitely.
Export to coding tools:
- Click Copy to grab the full spec (title, metadata, all sections) and paste into your coding tool (Cursor, Claude Code, etc.)
Export as markdown:
- Click Export on any spec to download as a
.mdfile - Or use batch export: select multiple priorities from the list, then click Export to download all their specs at once
Keyboard navigation:
- ← → arrow keys to move between specs
- Enter to expand a priority
Managing Feedback in a Spec
The feedback accordion in a spec lists every item that contributed to that priority. You can remove individual feedback items from a priority — useful if an item was miscategorised or is no longer relevant. Removing an item from a priority does not delete it. It returns to the feedback pool and is re-categorised in the next pipeline sweep — it may reappear in the same or a different priority.
What Specs Remember
After a few ships, specs show what Circuit remembers: previous ships, corrections and related context. If the team has shipped something similar before, the spec surfaces it. This helps avoid duplicate work and build on past decisions. See the Memory article for how this works.
What Happens When You Ship
When you click Mark as Shipped, the Share Back dialog opens.
1. Choose your channels
| Channel | What happens |
|---|---|
| Branded notification sent to eligible customers | |
| Surface banner | Banner shown in the float surface for returning visitors |
| Both | Email + surface banner (default) |
2. Review recipients
The dialog lists every customer eligible for notification — those whose email is on file from any feedback source (widget, CSV, manual entry, API). Each shows their email, name (if available) and a feedback snippet. Uncheck any recipient to skip them individually. Click Skip to send nothing and keep the spec as Shipped without notifying anyone.
3. Customise the email
Notification emails use your workspace branding: company name, logo URL, accent colour, footer text and sender display name. Configure in Settings → Integrations → Surface → Notification branding. Without custom branding, Circuit's default styling applies.
4. Status changes to Shared
After sending, the spec moves to Shared — the final stage in the pipeline. Shared means the feature shipped and customers were notified. A ship memory is recorded at this point: theme, volume and customer segment at time of ship. This is what Circuit learns from over time. New feedback arriving on the same theme after a spec is shared feeds into a V2 of the spec.
5. Spec quality feedback
After marking as shipped, Circuit asks for a quick thumbs up or down on spec quality. This takes one click and helps improve future specs.
Further reading: What good product specs look like now →