↓Skip to main content
  1. Posts/

Why I started SpecStream: specs should flow, not rot in tickets

·9 mins

Why this topic matters #

I started thinking seriously about SpecStream around five or six weeks ago.

At first it was just a persistent feeling that something in the current workflow is broken. I only started coding around two weeks ago, but the idea itself had already been sitting in my head for a while because the problem is not subtle anymore.

We now live in a strange engineering moment.

AI can generate code fast. Teams move across multiple repositories. Product decisions come from different people. Context is spread across docs, tickets, Slack threads, calls, and local AI sessions.

And still, one of the most important things in the whole process is weak: specification.

Not because teams do not care, but because the path from idea to implementation is still full of manual translation.

That is exactly why I started SpecStream.

First, what is SpecStream? #

In simple terms, SpecStream is an idea for treating specifications as the real unit of work.

Not tickets. Not scattered prompts. Not half-remembered meeting notes.

Specs.

What does that mean?

It means the system should take an idea, understand the architectural context, help refine the scope, freeze a version for execution, and keep a traceable line between intent and code.

That is the core belief behind the project:

the spec should be the thing that flows through the whole engineering process.

That is why I call it SpecStream.

The problem I keep seeing #

Here is the pattern I think many teams are dealing with right now:

  1. Someone from product, business, or operations says what they need.
  2. That idea gets translated into a ticket.
  3. A developer reads the ticket and reconstructs missing context.
  4. Then the developer explains it again to AI.
  5. Then the generated code has to be interpreted again during review.

That is too many translations for one piece of intent.

And every translation is a chance to lose information.

This is the part I care about the most. The problem is not only that tickets are imperfect. The problem is that the whole chain is lossy.

Business intent becomes project language. Project language becomes ticket language. Ticket language becomes implementation guesses. Implementation guesses become AI prompts.

By the time code lands, the original intent is often diluted.

Why this hurts even more now #

Ten years ago, teams already had bad tickets.

But now the cost is higher because AI amplifies both clarity and ambiguity.

If the spec is good, AI becomes a powerful implementation assistant. If the spec is weak, AI becomes a very fast confusion machine.

That is why I think the old workflow is starting to collapse under modern conditions.

A vague ticket used to slow a developer down. Now it can also generate a lot of code that looks plausible while drifting from the real goal.

This is one of the biggest reasons I think specifications suddenly matter much more than before.

What I want to change #

The idea behind SpecStream is not “let’s create better tickets.”

I think that is too small.

What I want is to move the center of gravity from tickets to structured specs.

That means a few things:

  • the system should understand the workspace at a high level
  • the system should know which repositories and domains are affected
  • the system should help turn a business request into a real spec
  • the spec should be reviewed and refined collaboratively
  • the approved version should become the execution contract
  • the implementation should remain traceable back to that approved intent

This is important: I do not see the spec as documentation after the fact.

I see it as the operational object that connects stakeholders, developers, AI, and Git history.

Why I think “spec as the unit of work” is the right model #

Tickets are usually too small in the wrong places and too vague in the places that matter.

A ticket might tell you what to build, but it usually does not carry enough architectural context, enough constraints, enough non-goals, or enough traceability.

A proper spec can.

That does not mean every team needs a giant design document for every button change. I am not arguing for process theater.

I am arguing that, for real engineering work, the unit of execution should be a structured agreement.

A good spec can hold:

  • objective
  • scope
  • affected systems
  • constraints
  • non-goals
  • acceptance criteria
  • execution boundaries

That is much closer to what teams actually need than a short ticket plus tribal knowledge plus five disconnected AI chats.

Why this is not only a developer problem #

One thing I care about a lot is that specifications are usually treated as a technical artifact too early.

I think that is a mistake.

The best specs start before code and before deep technical discussion. They start as clarified intent.

That means the system should be useful for more than one role:

  • stakeholders need outcome clarity
  • product people need scope clarity
  • developers need technical clarity
  • AI needs structured boundaries

This is why I keep thinking about the problem as a shared understanding problem, not just a coding workflow problem.

If the same spec can serve different views without becoming a mess, then the whole process becomes more aligned.

The distributed context problem #

A big part of modern engineering is that context is fragmented.

Some context lives in the repo. Some lives in architecture docs. Some lives in diagrams. Some lives in people’s heads. Some lives in AI conversations that disappear after the session ends.

This is one of the strongest motivations behind SpecStream.

I do not think the issue is only “we need better writing.” I think the issue is that the knowledge needed for good implementation is spread across too many places with no stable center.

So the project is also based on another belief:

teams need a shared system of intent, not only a backlog system.

That wording matters.

A backlog system tracks work. A system of intent explains why the work exists, what it touches, what it must not do, and how it connects to the broader architecture.

Why I do not want raw specs dumped into the repo #

This is another opinion I have become more convinced about while thinking through the project.

I do not want repositories to become random storage for every generated artifact or every evolving spec draft.

The repo should stay clean.

What should remain in Git is what helps traceability:

  • where execution started
  • where execution ended
  • which approved spec version was used
  • what context snapshot mattered for that execution

That is very different from turning the repo into a dumping ground for process noise.

So for me the goal is not repo pollution in the name of traceability. The goal is precise execution metadata with clear boundaries.

A simple mental model for the flow #

This is how I think the flow should work in principle:

  1. A stakeholder describes a need in plain language.
  2. The system interprets that need using architectural context.
  3. A structured spec is generated.
  4. The spec is refined collaboratively.
  5. One version gets approved and frozen.
  6. That approved version becomes the unit developers execute against.
  7. Execution is linked back to commits and context.

This matters because the workflow stops being:

idea -> ticket -> guesswork -> prompt -> code

and starts becoming:

idea -> spec -> refinement -> approval -> execution -> traceable history

That is a much healthier model for teams using AI seriously.

Why I think this idea is arriving at the right time #

I do not think SpecStream would feel as urgent a few years ago.

Now it does, because three things are happening at the same time:

  • AI can produce implementation faster than teams can validate intent
  • software systems are spread across multiple repos and domains
  • product and engineering communication is under pressure to move faster

When those three things meet, weak specifications become a structural problem.

This is why I believe the next wave of developer tooling will not only be about “generate code faster”.

It will be about:

  • preserving context
  • structuring intent
  • reducing translation loss
  • making execution traceable

That is the space where I think SpecStream belongs.

What SpecStream is not #

It is not a pitch for bureaucracy.

It is not an argument that every task needs a heavy process.

It is not a claim that tickets are useless in every situation.

And it is not about exposing implementation details before they are ready.

The point is simpler:

for work that actually matters, the current mix of tickets, fragmented context, and disconnected AI sessions is too fragile.

Who I think this is for #

I think this idea matters most for engineering teams that:

  • work across multiple repositories or domains
  • involve more than just developers in requirement definition
  • use AI in real implementation workflows
  • care about review quality and traceability
  • feel that tickets are no longer enough

Small teams can still benefit from this way of thinking, but the pain becomes much more obvious as systems and organizations grow.

Why I am working on it #

The honest answer is that I think the current workflow is behind the reality of how software is now built.

We have better code generation. We have more system complexity. We have more context fragmentation.

But our core coordination object is still often a ticket that was manually rewritten three times.

That no longer feels good enough.

So SpecStream started as a response to that mismatch.

I have been thinking about the idea for around five or six weeks, and I only started coding it around two weeks ago, but the direction feels right because it is grounded in a problem I keep seeing again and again:

people do not only struggle to write code. They struggle to preserve intent from idea to implementation.

Conclusions #

SpecStream exists because I think specifications deserve a much more central role in modern software development.

Not as passive documentation. Not as bureaucratic paperwork. As the thing that carries intent through the system.

If that sounds opinionated, it is, but I think the industry is moving in that direction anyway.

The more AI we use, the less we can afford vague execution inputs.

That is why I am working on this project. Not because “specs” sound formal, but because clear, structured, traceable intent is becoming one of the most practical needs in engineering teams.