Spec Is Not the Cure — Unless It’s Discovered Through Discussion

Over the past year, three terms have dominated conversations around AI coding:

Spec / Plan / Design Document

There’s a growing belief that if a model can first generate a comprehensive spec, and an agent can then execute against it, complex tasks can be automated end-to-end.

It sounds reasonable.

In practice, it rarely works that way.

The problem isn’t that specs are unimportant.

The problem is that we’re generating them in the wrong way.

That’s precisely the gap CodeFlicker is designed to address.

1. We’ve Misunderstood What a Spec Actually Is

In most AI IDEs, a “spec” typically means:

• A document generated before coding


• A description of implementation steps or architecture


• A one-shot artifact that drives downstream execution

This mindset is inherited from traditional software engineering.

But in AI-native workflows, this definition breaks down.

The real value of a spec is not the “plan” itself.

It’s whether the spec encodes sufficient context.

A spec is not a plan.

A spec is an explicit representation of context.

If the context is wrong or incomplete, the spec merely amplifies the error.

2. Why One-Shot Spec Generation Fails by Design

Most AI coding workflows implicitly assume:

Given partial context, ask the model to generate a complete, usable spec in one go.

This assumption is structurally flawed.

2.1 Models Are Biased Toward Early Convergence

Large language models are optimized to produce coherent, well-structured answers quickly.

They are not optimized to:

• Exhaustively explore edge cases


• Construct counterfactual reasoning paths


• Challenge their own assumptions


• Perform adversarial validation

Yet a production-grade spec requires exactly that:

• Coverage of boundary conditions


• Explicit trade-offs


• Rejected alternatives and their rationale


• Hidden constraints surfaced explicitly

This runs counter to the model’s default generation dynamics.

2.2 When Business Context Is Missing, the Model Hallucinates Plausibility

In a coding agent scenario, the model can access:

• Repository structure


• APIs and type information


• Limited commit history

Call this technical context.

But what actually determines task success is often:

• Why is this feature being built now?


• What defines success?


• Which approaches were previously rejected?


• What constraints are non-negotiable but not expressed in code?

That is business context.

And business context is rarely encoded in the repository.

When that layer is missing, a one-shot spec becomes a plausible fiction.

3. Why Small Tasks Seem Fine — and Large Tasks Collapse

There’s a critical complexity boundary here.

For small tasks (0.5–1 engineering day):

• Context is narrow


• Constraints are visible


• Failure cost is low

One-shot planning can occasionally succeed.

For multi-week initiatives:

• Context is deeply entangled


• Implicit constraints dominate


• Directional errors are expensive

One-shot specs almost always degrade.

This isn’t a model capability issue.

It’s a complexity scaling issue.

4. Specs Shouldn’t Be Generated. They Should Be Discussed.

This is where CodeFlicker takes a fundamentally different approach.

Instead of encouraging users to “generate a spec,” CodeFlicker introduces:

Discuss Mode

This is not a casual chat mode.

It’s an engineered workflow constraint.

In Discuss Mode:

• The model’s convergence is intentionally slowed


• It is prevented from outputting a full solution prematurely


• Assumptions must be surfaced


• Edge cases are interrogated


• Rejected paths are documented

The spec is not produced in one shot.

It emerges across structured dialogue as a progressively refined context model.

This shifts the problem from document generation to epistemic alignment.

5. Where the Efficiency Actually Comes From

We validated three development paradigms on ~10 engineering-day initiatives.

1. Traditional Development (~10 PD)

• 1–2 days writing a design doc


• Remaining time spent coding and debugging

2. Typical AI-Assisted Coding (~8 PD)

• Human still writes the design


• Agent accelerates 0.5-day sub-tasks


• Saves ~1–2 PD

AI acts as a productivity multiplier, not a structural transformer.

3. Discuss + Plan-First Workflow (~2.5 PD)

• First 2 days in Discuss Mode


• Systematically surface business constraints and assumptions


• Produce a deeply detailed, execution-grade spec


• Freeze context before implementation


• Main implementation completed in 4–6 hours

The efficiency gain does not come from typing code faster.

It comes from eliminating directional error early.

Complexity is absorbed upfront rather than leaking into execution.

6. The Dual-Mode Workflow in CodeFlicker

In CodeFlicker, complex tasks typically follow:

Discuss → Plan → Execute

Step 1: Discuss

Output: outline.md

Captures:

• Core decisions and trade-offs


• Explicit constraints and “no-go zones”


• Rejected approaches and rationale

The goal is clarity, not solution generation.

Step 2: Plan

Outputs:

• tech-design.md


• plan.md

The technical design is decomposed into verifiable tasks with explicit acceptance criteria.

Step 3: Execute

• Code is generated against a frozen plan


• 70–90% implementation coverage


• Code review is validated against plan constraints

At this stage, the agent no longer guesses intent.

It executes against a contract.

7. The Real Bottleneck in AI Coding

The limiting factor in AI coding isn’t code generation quality.

It’s contextual completeness.

Without context, a spec is formatting.

With context, a spec becomes an execution contract.

Discuss Mode in CodeFlicker exists to:

• Delay premature convergence


• Surface hidden assumptions


• Freeze boundaries before execution


• Construct a high-fidelity context model

Only then can an agent operate reliably in production-scale tasks.

Conclusion

Specs are not a silver bullet.

A one-shot spec simply helps an AI move faster in the wrong direction.

But a spec that emerges through structured discussion can serve as a stable execution foundation.

If you’re building multi-week features with AI tooling, the missing piece might not be a better model.

It might be an environment that supports discussion-driven spec formation.

That’s the problem CodeFlicker is built to solve.