# IDEA-016: Smart Spec Pipeline — Collaborative Requirements Elicitation

**Date:** 2026-03-04
**Source:** user
**Status:** raw

## Idea

Replace the current single-pass spec-writer agent with a multi-agent, iterative pipeline that produces 100%-resolved requirements before any implementation begins. The pipeline combines research, architecture assessment, interview loops, and validation gates — and logs every decision permanently.

---

## Section 0: Backlog as the Starting Point for Every Discussion

When a requirement discussion begins — regardless of where it came from — it starts as a backlog entry (IDEA-NNN), not immediately as a REQ file.

The IDEA file is a **living document** that grows throughout the discussion:
- Initial idea captured in raw form
- Researcher and Architect findings appended as sections
- Interview questions and answers added incrementally
- Deferred sub-questions become linked child IDEAs
- New requirements that emerge during discussion are captured as separate IDEAs (not grafted onto the current one)
- Trade-off tables, architect assessments, and decision rationale all live here

The IDEA only graduates to a formal REQ when the judge confirms it's 100% resolved. Before that moment it stays in backlog — enriched, not replaced.

This means: backlog entries are never "just raw ideas". They are the single source of truth for the full discussion history from first thought to final spec.

```
IDEA (raw) → IDEA (researched) → IDEA (in discussion) → IDEA (architect assessed)
                                                                    │
                                                              Judge validates
                                                                    │
                                                              REQ (ready)
```

---

## Section 1: The Core Problem with Current Spec Writer

The current spec-writer is a single-pass agent: receives a description, produces a REQ file, done. This is too shallow. Real requirements have:
- Hidden complexity only an architect can see
- Ambiguities that only surface through questions
- Dependencies on what's already built
- Trade-offs that need explicit decisions

A spec written without architecture input and without user clarification is incomplete by definition. The downstream agents (coder, QA) pay the price.

---

## Section 2: The New Pipeline

```
Requirement arrives (from user, from Eva, from backlog)
       │
       ▼
  [1] Researcher + Architect
       │  Deep-dive: what exists, what's the complexity,
       │  what are the approaches, pros/cons table
       ▼
  [2] Spec Writer (draft)
       │  Produces draft REQ + list of open questions
       ▼
  [3] Interview Mode (with user or agent)
       │  Iterative: questions → answers → new questions
       │  User can defer any sub-question to backlog
       ▼
  [4] Back to [1] if new information changes the scope
       │  (loop until no new questions from architect)
       ▼
  [5] Requirements Analyst / Judge
       │  Independent validation of completed spec:
       │  - Every AC is testable and unambiguous?
       │  - Architect confirmed complexity?
       │  - All open questions resolved or deferred?
       │  - No hidden assumptions?
       │  If questions remain → back to [3]
       ▼
  [6] Gate: 100% resolved or explicitly deferred to backlog
       │  Nothing passes this gate with unresolved ambiguity
       ▼
  REQ marked "ready" → Architect → Coder
```

---

## Section 3: Interview Mode

The interview is not a one-shot Q&A. It's a structured dialogue:

- Agent asks questions **one at a time** or in small batches (not a wall of 20 questions)
- After each answer, agent may generate follow-up questions
- User can answer: resolve / defer to backlog / mark as out of scope
- Deferred questions become IDEA entries automatically with the discussion context
- New requirements that emerge during interview are captured as new IDEAs, not added to current REQ scope without explicit user approval
- All answers are logged permanently (see Section 5)

The user in this loop can be:
- A human
- Another agent (e.g., Eva running spec cycles on itself)
- A Telegram/Discord bot interface

---

## Section 4: Architect's Role in Spec Phase

Currently architect only enters after spec is complete. This is backwards for complex requirements.

During spec phase, architect provides:
- **Complexity estimate** (before code is written, not after) — story points or T-shirt sizes
- **Approach options** — list of 2-3 ways to implement, with trade-off table
- **Risk flags** — what could go wrong, what's unknown
- **Dependency check** — does this conflict with or depend on existing REQs?

Spec writer gets architect's confidence score. If architect says "I don't know how to implement this" → spec cannot move to ready. It goes back to research.

---

## Section 5: Decision Log — Always Record Why

Every decision made during spec elicitation must be permanently logged with context:

- What was the question?
- What options were considered?
- Why was this option chosen?
- Who decided (user / agent / deferred)?
- Timestamp

When an IDEA returns from backlog after 1 month, the log tells the full story. No one needs to reconstruct the context from memory.

Storage: `.ievo/memory/DECISIONS.md` (already exists) + per-REQ discussion log at `spec/requirements/REQ-NNN-discussion.md`.

---

## Section 6: Backlog Revival Cycle

When an idea is pulled from backlog into active work:

1. Load the original IDEA + all discussion logs from when it was created
2. Run a "context refresh" — what has changed in the project since then?
3. Check: is this idea still relevant? Does the original approach still make sense?
4. Full spec pipeline again (Section 2), but seeded with the prior discussion context
5. Architect explicitly states: "Given what was built since then, the original approach is [still valid / needs revision / obsolete]"

This prevents stale decisions from silently polluting new implementations.

---

## Section 7: The Gate / Judge Agent

A dedicated judge agent that acts as a hard gate before any REQ moves to "ready":

- Cannot be bypassed (pipeline rule, not a suggestion)
- Checklist: every AC testable? architect confidence = high? all questions resolved or deferred? no implementation details leaked into spec?
- If anything fails → back to interview loop with specific feedback
- Judge produces a validation report (`VALIDATION-REQ-NNN.md`)

The judge is the only agent that can flip a REQ from "draft" to "ready".

This gate also applies when Eva writes specs for itself — the same validation runs, with Eva as both the "user" in the interview and the subject of the spec.

---

## Section 8: Rigid Pipeline Enforcement

To prevent agent "glitches" (skipping steps, hallucinating completion):

- Each pipeline stage has an explicit entry condition and exit condition
- An agent cannot claim to complete a stage without producing the required artifact
- Exit artifacts are checked by the next stage agent before starting
- The judge is the final hard gate — no REQ reaches "ready" without VALIDATION-REQ-NNN.md

This is inspired by the same idea as test coverage gates in CI — the pipeline just won't proceed without proof of completion.

---

## Why

The current spec pipeline produces shallow, incomplete requirements. Downstream agents waste time on ambiguities that could have been resolved upfront. Decision context is lost within days. This redesign makes the spec phase as rigorous as the implementation phase — because the cost of a wrong spec is far higher than the cost of a wrong line of code.
