compounding engineering

rule

choose actions that make the next correct action easier, faster, and safer. compounding engineering turns a solved problem into a reusable local advantage: an exact symbol, glossary term, generated contract, mapper, slice, query, verification path, or debugging system.

do not optimize only for finishing the current change.
leave the smallest durable asset that prevents future rediscovery.
no speculative abstraction.

why

work that leaves nothing behind must be repeated in full:

the next similar capability hand-copies the least understood implementation.
each copy carries the bug independently.
one verified reference plus its local owner makes the 2nd through nth capability a reuse decision with a known-good boundary.
a pattern-level fix becomes one edit instead of many.

invariant: solved problems accumulate into reusable local advantage instead of resetting to zero each time.

fifth endpoint with pagination:

compounding:      update reference slice → replicas follow one proven pattern.
not compounding:  hand-write cursor logic again; four diverging copies exist;
                  a pattern bug must be fixed four separate times.

cost of optimizing only for the current change, endpoint by endpoint:

endpoint 2 does not reuse endpoint 1's verified pattern; it copies the least-understood part and hand-writes pagination or cursor logic again.
a pattern bug (e.g., cursor validation breaks on exact-boundary values) exists independently in each implementation.
agent 1 fixes their version; agent 2 rediscovers the same bug weeks later and fixes it again; a third implementation sees neither fix — no documented single source of truth.
by endpoint 5: five subtly different pagination strategies, three broken. a refactor touches all five — no shared reference existed to update once.

reference-slice replication

build one correct vertical slice first, write the local specification for the pattern it proves, then apply that pattern to similar capabilities. this is reference-slice replication: its first complete slice is the local reference implementation.

phase	required result
reference	one complete, verified path across the relevant user, contract, domain, persistence, and runtime boundaries.
distillation	one local owner that names the proven pattern, symbols, and verification.
replication	focused forward-only changes that follow the local reference, not copied opaque files.
correction	repair the reference and its specification first, then update replicas.

do not

copy an incomplete first attempt across several domains.
call a happy-path component or endpoint a reference slice.
introduce a generic framework before a reference proves a stable seam.
leave a repeated debugging failure without a reusable evidence path.

good and bad

bad

// endpoint 1: hand-written pagination
app.get("/users", async (c) => {
  const cursor = c.req.query("cursor");
  const limit = parseInt(c.req.query("limit") || "10");
  // custom cursor parsing, validation, error handling
});

// endpoint 2: similar but different
app.get("/orders", async (c) => {
  const cursor = c.req.query("cursor");
  const pageSize = Number(c.req.query("pageSize"));
  // slightly different pagination logic
});

// endpoint 3: another variation
app.get("/products", async (c) => {
  const after = c.req.query("after");
  const count = parseInt(c.req.query("count"));
  // third pagination approach
});

three endpoints each hand-write pagination parsing, cursor validation, and error copy. endpoint 4 copies the least broken version, so every future correction requires rediscovering all four paths.

good

// reference pagination endpoint (slices/api/paginated-list.mdx)
app.get("/users", async (c) => {
  const result = PaginatedListSchema.safeParse(c.req.query());
  if (!result.success) {
    return c.json({ error: "invalid_pagination", details: result.error.format() }, 400);
  }

  const { cursor, limit } = result.data;
  const users = await db.query.users(cursor, limit);

  return c.json({
    items: users.items,
    nextCursor: users.nextCursor,
    hasMore: users.hasMore,
  });
});

// later endpoints reuse the proven schema
app.get("/orders", async (c) => {
  // same validation, query mapper, response contract
  const result = PaginatedListSchema.safeParse(c.req.query());
  // ...
});

one complete endpoint proves an explicit cursor schema, query mapper, response contract, and verification command. its owning standard records that vertical slice. later endpoints reuse the proven boundary and update the reference first when the pagination rule changes.