Skip to content

positioning: lead with "observe → compile → replace" + governance, demote the "save LLM calls" hero #225

@dgenio

Description

@dgenio

Problem

The current README hero leads with "deterministic tool paths waste an LLM call between every step; compile them away." That framing invites the strongest objection a skilled reader can raise: "If I already know the exact sequence, I'll just write a Python function with four calls — why do I need a framework?" The before/after diagram (4 LLM calls → 0) reads as a strawman, because nobody who already knows a deterministic path is putting a model between each step.

This caps our addressable audience and is the likely reason engagement is flat despite strong engineering.

The stronger value props (already in the repo, under-sold)

  1. Observe → compile → replace (the moat). ChainAnalyzer + the runtime observer (Implement runtime chain observer with auto-flow suggestion #78) + suggest imply a capability no competitor ships: watch an agent repeat a tool sequence at runtime, then auto-propose compiling it into a deterministic flow. You don't hand-write the flow — the system discovers it. This answers "why a framework" directly.
  2. Governance / observability for tool pipelines. Typed I/O at every step, file-serializable flows, schema-drift detection, determinism attestation, property fuzzing, structured audit traces, profiling. The value is disciplined, auditable, portable deterministic pipelines — not "run 3 functions."

Proposal

  • Rewrite the README hero and docs/index.md to lead with discovery + governance; keep the cost/latency argument as a secondary supporting point, not the headline.
  • Add an explicit "Why not just write a function?" FAQ entry that answers the objection head-on (discovery, schemas, traces, drift, attestation, portability/export).
  • Re-frame the comparison matrix so the differentiator reads as "the only LLM-free, typed, file-serializable, auto-discovered tool-flow runner."

Acceptance criteria

  • README hero no longer leads with the "N LLM calls → 0" diagram as the primary message.
  • A "Why not just write a plain function?" section exists and answers the objection in ≤6 bullets.
  • docs/index.md and the readthedocs landing page mirror the new positioning.
  • The auto-discovery story (Implement runtime chain observer with auto-flow suggestion #78) is referenced from the hero as the flagship capability.

Related: #78, #17.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions