+-------------------------------------------------+
| WORKWAY SDK CANON AUDIT |
| |
| Pre-understanding Emergent understanding |
| (README) (Implementation) |
| |
| | | |
| v v |
| ActionResult ──────► DX Helpers |
| IntegrationError ───► Error Taxonomy |
| Timeout ────────────► AbortController |
| Retry ──────────────► Exponential Backoff |
| |
| Score: 41/50 ──────────────────► 48/50 |
| |
| "The circle closes: implementation |
| reveals what documentation cannot." |
+-------------------------------------------------+
The Hermeneutic Circle in Practice
Applying Dieter Rams' 10 Principles to integration SDK development. The canon doesn't exist in isolation—it's validated through practice.
The README represented pre-understanding—how we thought the SDK worked. But through building concrete integrations (Gmail, Slack, Stripe, Notion, GoogleSheets), a different understanding emerged.
This is the hermeneutic circle: the whole (SDK architecture) is understood through the parts (individual integrations), and the parts are understood through the whole. Each iteration deepens understanding.
The README didn't capture that result.error is an
object { message, code }, not a string. Tests
revealed this gotcha. DX helpers were added.
No timeout handling existed. Through implementation, the AbortController pattern emerged as the canonical solution.
Critical for production use. Exponential backoff with jitter, rate limit awareness—none of this was documented because it only emerged through building real integrations.
Gmail claimed canHandleAttachments: true but didn't
implement it. The Canon (Principle 6: Honest) required correction.
| Violation | Fix |
|---|---|
| No retry logic | retry.ts with exponential backoff |
| Capabilities overstatement | Honest declarations in Gmail, Stripe |
| No request timeout | AbortController in all 5 integrations |
| No webhook tests | 42 tests (Stripe + template) |
| Type conflicts | Removed duplicate definitions |
Pre-understanding (README) described what the SDK does. Emergent understanding (DEVELOPERS.md) describes how to build with it—the practical knowledge that only emerges through praxis.
This is the hermeneutic circle applied to software: implementation reveals what documentation cannot. The canon is not static dogma but living philosophy, validated and refined through practice.