DEV Community

Manjunath Hanamantgad
Manjunath Hanamantgad

Posted on

I Killed My 6-Task Plan and Built a 300-Line Reference Implementation Instead

This is the story of how I turned a 1,200-line production sketch into a 300-line reference implementation — and why the smaller version is more useful.

Architecture diagram

What you will learn:

  • The warning signs of an over-engineered side project.
  • How to separate the core contract from the infrastructure.
  • Why a complexity budget beats an ambitious plan.
  • How a smaller artifact can be more credible than a larger one.

The original plan

I set out to build a durable AI workflow lab. The goal was to prove that an approval-gated ticket workflow could survive crashes without duplicating an external ticket.

The plan grew quickly:

  1. Strict contracts and synthetic failure cases.
  2. Idempotent mock receiver with PostgreSQL.
  3. Durable admission, decisions, and tenant-scoped API.
  4. Checkpointed LangGraph workflow with single-worker resume.
  5. Real crash boundary proof with SIGKILL.
  6. Telemetry, runbooks, benchmarks, and ADRs.

The stack was equally ambitious: FastAPI, PostgreSQL, Pydantic, LangGraph, Docker Compose, OpenTelemetry, pytest.

Before any workflow behavior existed, the repository had:

  • 177 lines of implementation plan
  • 150 lines of design spec
  • 195 lines of contract code
  • 218 lines of contract tests
  • 161 lines of merge-local tooling
  • 208 lines of merge-tool tests
  • 24 synthetic cases defined but not executed

Total: 1,209 lines of plan, tooling, and tests for the first task.

The warning signs

Three things made me stop:

  1. The core insight was buried. The write/ack gap — the reason the project existed — was one concept among twenty. A reader would have to wade through auth, multi-tenancy, checkpoints, and telemetry before understanding the actual guarantee.

  2. Every task depended on every other task. The receiver needed the database, which needed Docker, which needed the API, which needed auth, which needed the worker, which needed LangGraph. There was no independently useful milestone.

  3. The learning goal was unclear. Was I building a portfolio piece? A product? A study aid? The plan tried to be all three and ended up being none.

The reset

I asked one question: what is the smallest artifact that proves the write/ack gap?

The answer:

  • One Command type with a stable key and payload digest.
  • One MockReceiver backed by SQLite.
  • One UNIQUE(command_key) constraint.
  • Five pytest proofs.

I deleted:

  • The six-task plan.
  • The design specs.
  • The merge-local tooling.
  • The large Pydantic contract suite.
  • The 24-case fixture manifest.
  • PostgreSQL, Docker, FastAPI, LangGraph, auth, multi-tenancy, telemetry.

What remained:

  • src/p01/contracts.py — 40 lines.
  • src/p01/receiver.py — 112 lines.
  • tests/test_gap.py — 84 lines.
  • README.md — 35 lines.
  • AGENTS.md — 11 lines.
  • pyproject.toml — 19 lines.
  • LICENSE — 21 lines.

Total: ~360 lines, including license and docs.

What the smaller version proved

The reduced implementation still demonstrates the full durable-systems insight:

  • A retry after a lost acknowledgement returns the original ticket.
  • Ten concurrent retries create exactly one ticket.
  • A changed payload under a reused key is rejected.
  • The stored result survives a receiver restart.

All five tests run in ~0.05 s with no Docker, no network, and no external services.

The new rules

The reset produced three rules I now apply to every project:

  1. Start with the minimum artifact that proves understanding. Not the minimum artifact that looks impressive. Not the minimum artifact that covers a curriculum. The minimum artifact that proves the concept.

  2. Set a complexity budget. For these labs, the budget is ~500 lines of source + tests + docs unless the concept truly needs more. That constraint forces scope decisions early.

  3. Separate public artifacts from local learning notes. The README, license, and diagrams are public. Plans, journals, and drafts stay local. This keeps the public repository polished and focused.

Public-facing result

I rewrote the README as a finished reference implementation rather than a learning exercise. It includes:

  • A clear problem statement.
  • Real-world use cases across six domains.
  • Three rendered SVG diagrams.
  • A usage example.
  • Explicit scope boundaries.
  • A test command that runs in under a second.

The repository is now something another engineer can understand and use in five minutes.

When to expand

The smaller implementation is not the final state. It is the foundation. Future layers — HTTP API, auth, multi-tenancy, LangGraph, crash-recovery proofs — can be added only when a workload actually needs them, and each layer can be tested independently.

That is the point: a small, correct primitive is easier to extend than a large, half-correct system.

Takeaway

Over-engineering is not about writing too much code. It is about solving problems you do not have yet, before solving the problem you do have.

If you cannot prove the core contract in a few hundred lines, adding infrastructure will not fix it. It will only hide it.

Your turn

Pick one side project or feature you are working on. What is the smallest artifact that would prove the core idea? Strip away everything else for one commit and see if the idea still stands.

Reference implementation: github.com/manjunath-hanmantgad/durable-ai-workflow-lab


If you enjoyed this, you might also like Closing the Write/Ack Gap with Receiver-Side Idempotency and 5 Ways Idempotency Fails Without Receiver-Side Deduplication.

What are you currently over-engineering?

Top comments (0)