Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sigilix.ai/llms.txt

Use this file to discover all available pages before exploring further.

This page traces a single review end-to-end so you know exactly what happens between a git push and a sigilix[bot] comment.

​
Trigger conditions

Sigilix reviews fire on these GitHub webhook events:
EventWhen it fires
pull_request.openedNew PR created
pull_request.synchronizeNew commit pushed to the PR branch
pull_request.reopenedA closed PR is reopened
pull_request.ready_for_reviewA draft PR is converted to ready
Mention triggers (@sigilix on a PR comment thread) fire a separate, lighter pipeline that posts a single conversational reply — not a full review.

​
The pipeline stages

1. Webhook received
   ↓
2. Pre-flight: dedupe + stale-head guard
   ↓
3. Diff fetch + reviewable-position parse
   ↓
4. Router: which specialists fire?
   ↓
5. Pre-flight retrieval (codebase context)
   ↓
6. Specialist fan-out (parallel)
   ↓
7. Quorum check
   ↓
8. Synthesizer (Core)
   ↓
9. Post-validation (provenance + line check)
   ↓
10. Stale-head guard #2
   ↓
11. Submit to GitHub
   ↓
12. Telemetry recorded

​
1. Webhook received

GitHub POSTs a webhook payload to Sigilix. Sigilix verifies the HMAC signature against GITHUB_WEBHOOK_SECRET and rejects unsigned or wrong-signed payloads with 401.

​
2. Pre-flight: dedupe + stale-head guard

Sigilix checks KV for an existing review on (prNumber, headSha). If found, the new webhook is a duplicate (e.g., GitHub redelivered) and is skipped. The stale-head guard fetches the PR’s current head SHA from GitHub. If the webhook’s SHA doesn’t match, the push has been superseded — the review is aborted and the new webhook will fire its own.

​
3. Diff fetch + reviewable-position parse

Sigilix fetches the unified diff via the GitHub Pulls API. The diff is parsed into a map of path → reviewable positions, where each position records { line, side: LEFT|RIGHT }. This map is used later to validate inline anchors.

​
4. Router

The router decides which specialists to fire based on the diff:
  • Docs-only PR (markdown / RST changes only) → no specialists; pr-overview only
  • CSS-only PR → Spark only (performance considerations)
  • Auth-related path touched → Warden required
  • Migration / schema files changed → Warden + Glyph
  • Lockfile changes → Warden (supply-chain check)
  • Default → all four specialists
The router currently runs default-on per the v3.1 spec. A future Phase 4b release will activate the conditional gating.

​
5. Pre-flight retrieval

Sigilix runs a single retrieval call against the codebase index for the PR’s title + body. The retrieved chunks are passed to all specialists as context, so they don’t each re-retrieve. This is the per-PR retrieval cache.

​
6. Specialist fan-out

The four (or fewer, per router) specialists run in parallel via Promise.allSettled with per-specialist timeouts. Each gets:
  • The diff
  • The PR title + body
  • The retrieval snapshot
  • Its own system prompt
  • Its own model (deepseek-v4-pro for Glyph, deepseek-v4-flash for Warden/Weave, minimax-m2.1 for Spark)
If a specialist’s primary model fails (transient: 503, 429), retry. If retries exhausted, fallback to a different provider’s model. If the fallback also fails, that specialist’s contribution is skipped.

​
7. Quorum check

Sigilix requires a minimum number of successful specialists to proceed:
  • Shadow mode (telemetry-only): 2 of 4
  • Post mode (production reviews): 1 of required + 1 other
If quorum isn’t met, the review is aborted with internal_error. In post mode, this triggers a fallback to Phase 3 single-agent review.

​
8. Synthesizer (Core)

See the Synthesizer page for the four sub-stages.

​
9. Post-validation

Before posting, Sigilix validates:
  • Every inline finding’s path:line is a valid reviewable position in the diff
  • Every finding’s structural provenance (which specialist findings it traces back to) is intact
  • Score-1 findings are aggregated into the summary, not posted inline
Findings that fail validation are dropped. The verdict and inline-finding list are finalized.

​
10. Stale-head guard #2

A second stale-head check runs immediately before submission. If the PR’s head SHA has changed since pre-flight, the review is aborted and the new webhook will fire its own.

​
11. Submit to GitHub

Sigilix posts the review via POST /repos/:owner/:repo/pulls/:number/reviews with event: APPROVE | REQUEST_CHANGES, the body containing the synthesizer summary, and comments: [] for inline findings. If the inline-anchor submission fails (422 — bad position), Sigilix falls back to an anchorless review with all findings rolled into the body. The verdict is still posted.

​
12. Telemetry

A telemetry record is written to KV with the review duration, finding counts, severity distribution, specialist outcomes, and any fallback flags. Used for monitoring and per-PR cost accounting.

​
Guarantees

  • Idempotency. Re-firing the same webhook never produces a duplicate review.
  • Stale-safe. A review is never posted on an outdated SHA.
  • Verdict survival. If GitHub rejects inline anchors, the verdict is still posted (anchorless fallback).
  • Cross-provider resilience. If one model provider is down, specialists fall back to alternatives.
  • No silent dropping. Every finding either makes it into the review or is logged as suppressed in telemetry.

Confidence Scoring

How findings are ranked, suppressed, and escalated by Core.

Rate Limits

The 5-hour window, burst behavior, and how to monitor your usage.