Review the docs in your repo.

Comment on docs instead of diffs, get briefed between review rounds, and see where code and docs disagree. All of it stored in your git repo.

You’re on the list.

acme/platform / docs/specs/billing-migration.md

priya · Updated 3 days ago · In review

Billing migration

Rollback

The worker reads billing.plan_version and refuses to write when the flag is unset, so a partial run leaves nothing to undo.

billing.plan_version was removed in a3f21c9

Checked against main · 2 hours ago

Accounts

Every subscription created after March is already on the new schedule, so the migration only touches the 1,400 accounts still on grandfathered annual pricing. Anything opened before the Stripe upgrade keeps its old anniversary date.

Cutover

The backfill runs in batches of 200 and holds the write lock for under 400ms. The Friday window is the only one with support fully staffed.

Support runs the smoke checks from the runbook once the last batch lands. Anything still on the old schedule after that counts as a bug.

There's a good case for keeping docs in the repo.

Versioned and reviewed like code, context for your agents.

But GitHub treats docs as code.

The diff is hard to read, and the rendered markdown doesn't take comments.

docs/specs/billing-migration.md +14 -1

@@ -18,8 +18,21 @@ ## Billing migration

18 18 ## Rollout

19 19

20 20 Annual plans move off the legacy proration table in three waves.

21 21 Each wave is gated on the one before it settling.

22 22

23 See the [rollout doc](../ops/rollout.md) for the order of operations.

23 | Wave | Accounts | Gate |

24 | ---- | ------------------- | --------- |

25 | 1 | 120 internal | manual |

26 | 2 | 1,400 grandfathered | 48h clean |

27 | 3 | remainder | 48h clean |

29 ```mermaid

30 flowchart LR

31 W1[wave 1] --> C{clean 48h?}

32 C -->|yes| W2[wave 2]

33 C -->|no| H[hold]

34 ```

36 Order of operations is in the [rollout doc](../ops/rollout.md).

24 37

25 38 ## Rollback

Rollout

Annual plans move off the legacy proration table in three waves. Each wave is gated on the one before it settling.

See the rollout doc for the order of operations.

Wave	Accounts	Gate
1	120 internal	manual
2	1,400 grandfathered	48h clean
3	remainder	48h clean

Order of operations is in the rollout doc.

Rollback

The best way to read a markdown file:

Take any GitHub doc URL, swap the domain, and read it here.

acme/platform / docs/architecture/webhook-delivery.md

Webhook delivery

Every event we emit is delivered at least once. The dispatcher writes to webhook_outbox inside the transaction that produced the event. Draining a backlog is covered in the runbook.

Delivery path

select id from webhook_outbox where status = 'pending'
order by created_at limit 200 for update skip locked

Retry schedule

Backoff is exponential with full jitter, capped at four attempts. After the fourth the endpoint is disabled and its owner gets an email.

Attempt	Delay	Jitter	Elapsed
1	immediate	none	0s
2	30s	± 15s	30s
3	5m	± 2m	5m 30s
4	1h	± 30m	1h 5m

Comments show up on your pull request.

Your teammates see them and can reply from GitHub, without ever opening Spectagon.

docs/specs/billing-migration.md #482

42 The worker reads `billing.plan_version` and refuses to write.

spectagon bot commented 2 days ago

priya via Spectagon:

The worker reads billing.plan_version and refuses to write when the flag is unset

This flag got dropped in the Stripe upgrade. What does the worker key off now?

sam replied yesterday

It keys off plan_tier now. I'll update the rollback section this afternoon.

Your comments are commits in your own repo.

Cancel your account and they're still there, readable with plain git.

$ git log --oneline refs/spectagon/reviews

7c41ab9 thread: priya on webhook-delivery.md

3e0f5d2 reply: sam on webhook-delivery.md

b19c884 approve: dana on dunning.md@5db7e10

$ git show 7c41ab9:threads/ad04/thread.md

author: priya

anchor: "capped at four attempts"

created_at: 2026-08-22T14:02:11Z

Four attempts is 65 minutes of cover. A

nightly outage still loses the batch.

Coming soon

Get briefed before you read.

What changed since your last visit, and which parts need your judgment.

Coming soon

Your docs get checked against your code.

When a statement stops being true, it gets flagged, with the commit that changed it.

acme/platform / docs/architecture/auth.md

verified 3 Jun, 12 commits ago

type: living · owners: priya

Authentication

The auth service issues on login, and every service behind the gateway verifies it locally against the shared public key. A token is good for and nothing revokes it early, so a suspended account keeps reaching the API until it expires.

Failed logins are rate limited to five per minute, and the gateway pages on call once one account crosses a hundred in an hour.

Checked on merge

The auth service issues a signed JWT on login

signJwt was deleted here and nothing on main defines it. Login returns an opaque token that the gateway checks against Redis.

Checked against main, 2 hours ago

Open thread · owner priya

services/auth/src/session.ts main

110 export async function createSession(userId: string) {

111 const token = randomBytes(32).toString('base64url')

112 await redis.set(`sess:${token}`, userId, { ex: SESSION_TTL })

113 return token

114 }

4c1e07b auth: opaque session tokens, drop JWT signing priya, 11 June

Checked on merge

A token is good for fifteen minutes and nothing revokes it early

SESSION_TTL is seven days on main, and a revoked session stops working straight away. Neither half of the sentence still holds.

Checked against main, 2 hours ago

Open thread · owner priya

services/auth/src/config.ts main

6 export const SESSION_COOKIE = 'acme_sess'

8 // Long lived now that revocation is instant.

9 export const SESSION_TTL = 60 * 60 * 24 * 7

d0b8e41 auth: session ttl to seven days sam, 24 June

Filed by an agent

Failed logins are rate limited to five per account per minute

The limiter keys on the client IP. Five failed logins from one office address lock out everyone behind it, and this line has read that way since April.

Found by an agent working in this repo, 19 August

Open thread · owner priya · 1 reply from sam

services/gateway/src/rate-limit.ts main

32 export function limitKey(req: Request) {

33 // TODO(sam): scope to the account once sessions land

34 return `login:${clientIp(req)}`

35 }

2b90d1c gateway: extract limitKey dana, 12 April

Coming soon

Your agent stops building from a stale spec.

It sees the same accuracy flags and open threads you see, over MCP or a CLI.

$ claude "implement the billing migration spec"

spectagon · read_doc(docs/specs/billing-migration.md)

2 accuracy flags · 2 open threads

Stopping before I write any code. The spec says the billing worker reads billing.plan_version, but that column was dropped in June. priya asked about the same sentence two days ago and nobody answered. Use plan_tier, or wait for her?

Comments outlive the pull request.

Open any doc on main and comment on it.

acme/platform / docs/rfcs/0042-webhook-retries.md

dana · Merged 4 weeks ago · No open PR

Webhook retries

Delivery failures retry on an exponential backoff, capped at six attempts over 24 hours. After that the endpoint goes cold and we stop sending.

Backoff

Retries are idempotent by delivery id, so a handler that already succeeded sees a no-op.

The first retry goes out after 10 seconds and each gap triples after that. A Retry-After header on the failed response overrides the schedule.

Cold endpoints are swept nightly. A replay re-enqueues at the front of the queue, so a customer who fixes their handler sees traffic within the minute.

Jump to the docs people are working on.

Recent edits and open threads at the top.

Spectagon

acme / platform

main 12 docs

Platform README.md pinned

Active

Billing migration docs/specs/billing-migration.md Comment from priya · 2h ago

in #4823 open

Proration rules docs/specs/proration.md Comment from sam · 6h ago

2 open

Webhook retries docs/rfcs/0031-webhook-retries.md Updated 9h ago

Plan versioning docs/adr/0009-plan-versioning.md Comment from dana · 2d ago

in #4861 open

Dunning and retries docs/specs/dunning.md 4 open threads · latest 5d ago

4 open

All docs

Platform README.md

docs/adr

Plan versioning docs/adr/0009-plan-versioning.md

Idempotency keys docs/adr/0011-idempotency-keys.md

docs/rfcs

Invoice PDF rendering docs/rfcs/0028-invoice-pdf.md

Webhook retries docs/rfcs/0031-webhook-retries.md

docs/runbooks

Failed payments docs/runbooks/failed-payments.md

Stripe incident response docs/runbooks/stripe-incident.md

docs/specs

Billing migration docs/specs/billing-migration.md

Dunning and retries docs/specs/dunning.md

Proration rules docs/specs/proration.md

Refunds docs/specs/refunds.md

Tax rates docs/specs/tax-rates.md

Reading is free.

You pay when your team reviews docs in a private repo.

One repo at a time.

It installs as a GitHub App and nobody else on the team has to change anything.

We’re adding repos a few at a time, so leave your email.

You’re on the list.

Questions.

Where do my comments live?

In your repo, on refs/spectagon/reviews: one directory per thread, markdown with frontmatter. Fetch the ref and read it with git log and git show.

Do my teammates need Spectagon accounts?

No. Your comments post to the pull request, and anything they write back there lands in the same thread.

What access does the GitHub App need?

Read and write on repository contents, plus pull requests. It writes review threads to refs/spectagon/reviews and never commits to your branches.

What does it cost?

Reading is free. We have not set the price for team review in a private repo yet.

Is it GitHub only?

Yes, today. Threads are stored as ordinary git objects, so the format itself does not depend on GitHub.

Can I write docs in Spectagon?

No. Spectagon is for reading and commenting on docs that are already in your repo. Keep writing them in your editor or with your agent, and commit them as usual.