+-------------------------------------------------+
    |   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."          |
    +-------------------------------------------------+

WORKWAY SDK

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.

41/50
Initial Score
48/50
Final Score
+7
Improvement

The Hermeneutic Insight

ALETHEIA

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.

What Emerged Through Praxis

EMERGENT UNDERSTANDING

ActionResult.error Structure

The README didn't capture that result.error is an object { message, code }, not a string. Tests revealed this gotcha. DX helpers were added.

Timeout Patterns

No timeout handling existed. Through implementation, the AbortController pattern emerged as the canonical solution.

Retry Logic

Critical for production use. Exponential backoff with jitter, rate limit awareness—none of this was documented because it only emerged through building real integrations.

Capabilities Honesty

Gmail claimed canHandleAttachments: true but didn't implement it. The Canon (Principle 6: Honest) required correction.

Rams' Principles Applied

CANON
1.
Innovative
5/5
→
5/5
2.
Useful
4/5
→
5/5
3.
Aesthetic
4/5
→
5/5
4.
Understandable
4/5
→
5/5
5.
Unobtrusive
5/5
→
5/5
6.
Honest
3/5
→
5/5
7.
Long-lasting
4/5
→
5/5
8.
Thorough
3/5
→
4/5
9.
Env. Friendly
5/5
→
5/5
10.
As Little As Possible
4/5
→
4/5

Critical Violations Addressed

REMEDIATION
✗ No retry logic
Fix: retry.ts with exponential backoff
✓ Resolved
✗ Capabilities overstatement
Fix: Honest declarations in Gmail, Stripe
✓ Resolved
✗ No request timeout
Fix: AbortController in all 5 integrations
✓ Resolved
✗ No webhook tests
Fix: 42 tests (Stripe + template)
✓ Resolved
✗ Type conflicts
Fix: Removed duplicate definitions
✓ Resolved
ViolationFixStatus
No retry logicretry.ts with exponential backoff✓ Resolved
Capabilities overstatementHonest declarations in Gmail, Stripe✓ Resolved
No request timeoutAbortController in all 5 integrations✓ Resolved
No webhook tests42 tests (Stripe + template)✓ Resolved
Type conflictsRemoved duplicate definitions✓ Resolved

The Circle Closes

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.

View Repository All Experiments