From ce6224304415dac653b2a8f2732e616f2e58ace8 Mon Sep 17 00:00:00 2001
From: Branimir Georgiev <66906831+braboj@users.noreply.github.com>
Date: Wed, 21 Oct 2026 23:59:57 +0300
Subject: [PATCH] refactor(webhooks): one instruction per rule

Long rules with trailing reasons split into short ones; the two lead-in
paragraphs become one sentence. Every rule keeps its strength.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 templates/backend/webhooks.md        | 40 ++++++++++++----------------
 tests/baselines/template-quality.txt |  2 +-
 2 files changed, 18 insertions(+), 24 deletions(-)

diff --git a/templates/backend/webhooks.md b/templates/backend/webhooks.md
index 2ce53555..7acb275e 100644
--- a/templates/backend/webhooks.md
+++ b/templates/backend/webhooks.md
@@ -3,43 +3,37 @@
 [DEPENDS ON: templates/backend/http.md, templates/backend/messaging.md]
 [DEPENDS ON: templates/security/security.md, templates/backend/observability.md]
 
-Rules for receiving inbound webhooks (provider callbacks, integration
-events) under bursty load. Compose this template on demand for a service
-that receives webhooks — it is not part of any stack chain by default.
-
-The generic resilience substrate — idempotency, retry/backoff, DLQ,
-debounce/coalesce, backpressure, fairness — is inherited from
-messaging.md; this template adds only the HTTP-ingestion-specific surface.
+Rules for receiving provider callbacks under bursty load, on top of the
+messaging rules for idempotency, retries, DLQs and backpressure.
 
 ## Intake
 
-- Expose a distinct intake URL per provider or connection — never
-  multiplex unrelated providers onto one endpoint; per-integration URLs
-  isolate failures, scope signature handling, and sharpen observability
+- Expose one intake URL per provider or connection; never multiplex
+  providers onto one endpoint
+- Scope failures, signature handling and metrics to that URL
 
 ## Verify at the edge
 
-- Verify the provider signature before doing any work — reject forged or
-  malformed payloads before parsing, persisting, or enqueueing
-- Verify against the exact bytes received, not a re-serialised copy, and
-  treat the raw body as untrusted until the signature checks out
+- Verify the provider signature before any work; reject a forged or
+  malformed payload before parsing, persisting or enqueueing it
+- Verify the exact bytes received, never a re-serialised copy
+- Treat the raw body as untrusted until its signature checks out
 
 ## Respond fast
 
-- Return 2xx within the provider's timeout budget: acknowledge receipt,
-  then process asynchronously — never run heavy work inline on the
-  request path
+- Return 2xx within the provider's timeout: acknowledge, then process
+  asynchronously, never inline on the request path
 - Persist or enqueue the event before responding so an acknowledged
   event is never lost
 
 ## Survive provider retries
 
-- Account for retry amplification — a non-2xx response makes the provider
-  resend, so a slow or failing handler multiplies inbound load
-- Return 2xx even when intentionally skipping an event (duplicate,
-  irrelevant); reserve 5xx strictly for failures where redelivery is wanted
-- Deduplicate on the provider's event ID — at-least-once delivery means
-  the same event will arrive more than once
+- Expect a non-2xx response to make the provider resend, so a slow or
+  failing handler multiplies inbound load
+- Return 2xx for an event skipped on purpose (duplicate, irrelevant)
+- Return 5xx only where redelivery is wanted
+- Deduplicate on the provider's event ID; at-least-once delivery sends the
+  same event more than once
 
 ## Testing
 [EXTEND: base-testing]
diff --git a/tests/baselines/template-quality.txt b/tests/baselines/template-quality.txt
index 968ad08a..d894f892 100644
--- a/tests/baselines/template-quality.txt
+++ b/tests/baselines/template-quality.txt
@@ -17,7 +17,7 @@ templates/backend/messaging.md 96.8
 templates/backend/microservices.md 93.5
 templates/backend/monitoring.md 98.5
 templates/backend/observability.md 96.6
-templates/backend/webhooks.md 86.9
+templates/backend/webhooks.md 100.0
 templates/core/agents.md 100.0
 templates/core/config.md 99.3
 templates/core/docs.md 99.1