Problem: The Forge trait abstracts GitHub/Linear, but abstractions always leak. "milestone" means GitHub milestone, but Linear has projects, cycles, and initiatives. "state" is open/closed, but Linear has rich workflow states. Users hit these differences unexpectedly.
Goal: Document where the abstraction leaks and make trade-offs explicit.
Success criteria:
- Audit each Forge trait method for semantic differences across forges
- Document in DESIGN.md: "Abstraction boundaries and known leaks"
- For each leak, document: what differs, why we chose this mapping, workarounds
- Consider: should some operations be forge-specific instead of abstracted?
Context (Rich Hickey's Simple Made Easy): Complecting = braiding together things that should be separate. A leaky abstraction complects the generic with the specific. Better to be honest about boundaries than pretend they don't exist.
Why later: Not blocking anything. Documentation/design clarity, not implementation.
Problem: The Forge trait abstracts GitHub/Linear, but abstractions always leak. "milestone" means GitHub milestone, but Linear has projects, cycles, and initiatives. "state" is open/closed, but Linear has rich workflow states. Users hit these differences unexpectedly.
Goal: Document where the abstraction leaks and make trade-offs explicit.
Success criteria:
Context (Rich Hickey's Simple Made Easy): Complecting = braiding together things that should be separate. A leaky abstraction complects the generic with the specific. Better to be honest about boundaries than pretend they don't exist.
Why later: Not blocking anything. Documentation/design clarity, not implementation.