DEV Community: wingtao

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

wingtao — Sat, 14 Feb 2026 09:10:16 +0000

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.

Stop Switching Repos: The Hidden Efficiency Ceiling in Multi-Repo Debugging — Broken by One Feature

wingtao — Sat, 14 Feb 2026 08:41:50 +0000

You’re probably doing something inefficient every day: switching repositories.

If you work on mid-to-large scale systems, you’re almost certainly dealing with a multi-repo architecture:

One repo for the frontend
One for the gateway
One for core services
One for the design system / component library
Several more for downstream dependencies

The problem is: bugs don’t stay confined to a single repository.

You see an anomaly in Repo A. The root cause lives in Repo B.
To verify an implementation detail, you have to:

Switch projects
Wait for indexing
Locate the entry point
Switch back
Re-explain all prior context

Every time you switch repositories, you lose context.

Logs, trace IDs, parameter differences, feature branch background — you have to restate everything.

This is not a developer capability issue. It’s a tooling issue.

The Real Friction in Multi-Repo Collaboration

Let’s look at a few common scenarios.

Scenario 1: API anomaly, but you're only in the frontend repo

An API response is missing fields.

You suspect the backend.

So you:

Switch to the backend repo
Locate the route
Find the handler
Trace into the service layer
Inspect the data source
Switch back

There is zero cognitive value in that sequence.
It’s pure operational overhead.

Scenario 2: Component behavior doesn’t match documentation

Your business project uses <Xxx />, but its behavior is off.

You suspect a default prop or an edge-case branch inside the component library.

So you:

Switch to the design system repo
Find the component entry
Inspect prop handling
Track default values
Compare against business usage

What you actually need is simple:

“Tell me what this component truly does, and how it should be used correctly.”

Instead, you’re doing manual archaeology.

Scenario 3: Cross-service tracing and debugging

You have a traceId.
The request flows from: Gateway → Orchestrator → Core Service → Downstream Service.

You want to know:

What does the call chain look like?
Where could the timeout occur?
Is there idempotency handling?
Where might duplicate execution happen?

You start digging repo by repo.

The issue isn’t that you can’t find the answer.
The issue is that the process is painfully inefficient.

What You’re Actually Missing Isn’t Search — It’s Cross-Repository Understanding

Most IDE-based AI models operate within a single-repo context.

When the problem spans repositories:

The model guesses
Or it infers based only on the current repo
Or it asks you to manually copy code across

None of these qualify as an engineering-grade solution.

What you really need is this:

Without switching projects, let an Agent investigate other repositories, trace the implementation, and return with evidence.

What CodeFlicker’s Cross-Repo Capability Enables

Inside CodeFlicker, within your current conversation, you can explicitly bring multiple repositories into context:

#repo backend-service
#repo design-system
#repo downstream-service

Once declared, the Agent can:

Trace the implementation chain in target repos
Identify entry files
Locate critical branches
Extract default values
Detect idempotency guards
Inspect retry logic
Aggregate evidence
Return structured conclusions

You don’t switch repositories.
You don’t lose context.
You don’t restate background.

How Is This Different from “Global Search”?

Global search gives you matches.

Cross-repo research gives you reasoning.

The output is typically structured:

Conclusion (most probable root cause)
Evidence (file paths + key entry points)
Recommendation (frontend workaround / backend fix / validation steps)

What you receive is:

A complete implementation path
Critical decision points
Actionable next steps

Not “43 search results.”

Three High-Impact Use Cases

1️⃣ API Implementation Tracing (Frontend ↔ Backend)

From the frontend repo:

#repo frontend
#repo backend-service

The Agent will:

Trace from route definition
Locate the handler
Inspect service logic
Identify data sources
Highlight branching conditions

You get:

Why fields are missing
What conditions trigger divergence
Whether the frontend can mitigate

2️⃣ Understanding Real Component Behavior

From your business repo:

#repo biz-project
#repo design-system

The Agent will:

Locate component entry
Enumerate key props
Identify default values
Detect boundary conditions
Provide minimal usage examples

You get:

An accurate behavior explanation
Recommended usage patterns
Anti-patterns
Common pitfalls

3️⃣ Cross-Service Call Chain Analysis

Given a traceId, include multiple service repos:

#repo gateway
#repo orchestrator
#repo core-service
#repo downstream-service

The Agent will:

Map the full call chain
Annotate critical parameters at each hop
Highlight timeout or idempotency risks
Identify the Top 3 probable failure points

You get:

An executable debugging path
A validation checklist
Logging enhancement suggestions

Why This Is an Engineering-Grade Capability

Because it addresses:

Multi-repository collaboration
Microservice architectures
Layered component systems
Complex upstream/downstream dependencies

Not just code generation.

Many AI tools are optimized for generating snippets.

But real productivity gains come from understanding entire systems.

Cross-repo capability is essentially:

Structured reasoning and evidence aggregation across multiple codebases.

That’s what an agentic IDE should provide.

A Practical Question

If you’re still:

Switching between repositories constantly
Copying code into models
Re-explaining context repeatedly
Manually tracing call chains

How much time are you wasting?

Ten minutes per context switch.
Five times a day.
Twenty-five times a week.

What does that add up to in a year?

Conclusion

Cross-repository capability is not a “nice-to-have.”

In multi-repo environments, it’s a productivity inflection point.

If your workflow involves:

Multiple repositories
Frontend-backend separation
Shared component libraries
Microservice call chains

Then you should experience this once:

Investigate the problem thoroughly — without switching projects.

That’s CodeFlicker’s cross-repo research capability.