Specs aren’t just documentation 
anymore.

Spectagon brings peer review to the specs your agents build from.

acme/api-redesign Update API latency estimates #42
B
A
D
Approve
3 files changed
api-redesign.md 1/3
rollback-strategy.md
migration-plan.md
Alice Chen · Updated 2h ago · Draft
API Redesign: V2 Migration Strategy
Overview The current API surface has grown organically over three years and now serves 14 distinct consumer types. Endpoint naming is inconsistent, authentication varies by service, and error responses follow at least four different formats. This proposal outlines a versioned migration to a unified V2 surface.
Approach
We chose eventual consistency for the notification system rather than strong consistency, accepting a delivery window of up to 30 seconds for non-critical alerts.
All existing V1 endpoints will continue to function behind a compatibility shim for 6 months after V2 launch. The shim translates V1 request shapes to V2 internally, so consumers can migrate at their own pace without coordination. 
GET /v2/notifications?since=2026-03-01
Accept: application/json
Authorization: Bearer {token}

{
  "notifications": [ ... ],
  "cursor": "eyJsYXN0X2lkIjogNDJ9",
  "has_more": true
}
Migration Timeline Phase 1 begins with read-only V2 endpoints mirroring existing V1 behavior. Consumer teams will have four weeks to integrate against the new surface before we enable writes. The payments and billing teams have agreed to serve as design partners during this phase and will validate the contract against their existing integrations.
4 open · 2 resolved Hide resolved
B
Bob Martinez 2h ago
We chose eventual consistency for the notification system
This latency estimate seems low — our p99 for the notification fanout is already at 22s under current load. Have we modeled what happens at 2x consumer count?
A
Alice Chen 1h ago
Good catch. I'll add the load model — we benchmarked at 1.5x and the 30s window held, but 2x is a fair ask.
Bob's thread — resolved
D
Dana Park 45m ago
Suggestion
a delivery window of up to 30 seconds a delivery window of up to 45 seconds under peak load
Accept
Dismiss
B
Bob Martinez 20m ago
Four weeks feels tight for payments — they're mid-migration on their own invoicing rewrite. Can we stagger the design partner timeline so billing starts in week 1 and payments joins in week 3?

Specs belong in the code.

We’ve said “docs should live with the code” for decades. But collaboration tools like Google Docs and Notion were easier to review in — so that’s where specs ended up.

Now there’s a stronger reason than ever to keep them in the repo. Agents build from specs, and specs in the repo give them the context they need. When the spec is what actually gets built, it stays current — not forgotten in a wiki.

The only thing missing is a good way to collaborate on them. That’s what Spectagon is for.

GitHub wasn’t built for reviewing prose.

GitHub’s review experience was built for code — diffs, line numbers, side-by-side views.

So you paste the spec into Notion or Google Docs for review — and the two versions drift out of sync immediately.

api-redesign.md
18 18 ## Approach
19 19
20
- We chose eventual consistency for the notification system rather than strong consistency, accepting a delivery window of up to 30 seconds for non-critical alerts. This keeps the write path fast and avoids coupling notification delivery to the primary database write transaction.
20
+ We chose eventual consistency for the notification system rather than strong consistency, accepting a delivery window of up to 45 seconds under peak load. This keeps the write path fast and avoids coupling notification delivery to the primary database write transaction.
21 21
22 22 ### Migration Plan

Spectagon is a peer review tool
for technical specs.

Structured feedback, inline comments, and clear approvals — all connected to your existing workflow.

Feedback that follows your rewrites.

When you revise a section — by hand or with an agent — comments intelligently re‑anchor to the content they’re about.

A lens on your GitHub PR.

Spectagon reads your markdown through the GitHub API and adds a review layer on top. The link gets posted right on your PR.

Comments & suggestions.

Inline comments, threaded discussions, and suggest mode — propose specific text edits that authors accept with one click.

Rendered for reading.

Mermaid diagrams, syntax-highlighted code blocks, clean typography. Your markdown looks like a published document, not a raw file.

Approval flow.

Approve, merge, and track review status without leaving Spectagon. Status check posted to your PR.

Nothing to migrate.

Spectagon is a read-only lens. If you stop using it, your documents are exactly where they always were, with all review activity preserved on the PR.

The spec is where humans shape the outcome.

With Spec-Driven Development, agents implement the spec literally — every ambiguity, overlooked edge case, and gap gets faithfully reproduced.

There are great tools for AI-assisted review. Spectagon is for the human review that happens before the agent starts building.

2 open · 1 resolved Hide resolved
B
Bob Martinez 2h ago
We chose eventual consistency for the notification system

This latency estimate seems low — our p99 is already at 22s under current load.

A
Alice Chen 1h ago

Good catch. I'll add the load model.

Add error handling

Let's make this concrete. If we want the agent to handle the various edge cases, we should spell them out here.

⌘ Enter · Esc
Comment

Get early access.