mcpctl/docs/vision-fidelity.md

Vision Fidelity — why agents hand you a plank with a steering wheel, and how to fix it

Status: Discussion / design brainstorm (no code commitments). Purpose: Capture the recurring failure — "we split a grand vision into tasks, completed every task, and got parts instead of a whole" — diagnose the root causes, survey what the field already knows, and shape a concrete answer that fits mcpctl's existing agentic-teams architecture.

This connects directly to docs/agentic-teams.md. The key claim: that doc designed technical correctness verification very well (confidence signal, verification sessions, acceptance gate) but never addressed vision-fidelity, product, or design verification — the exact axis this failure lives on.

---

1. The failure, named precisely

You said it almost perfectly. The meat:

1. you had a grand vision
2. we split the grand vision into tasks
3. we completed all the tasks
4. we are left with a stick with wheels instead of a car

This is not an execution problem. Every task was completed. The failure is upstream (decomposition) and downstream (verification):

• Decomposition is lossy. Splitting "build a car" into tasks compresses a rich, multidimensional vision into flat imperatives ("attach wheels", "install steering column"). The why and the what-good-looks-like don't fit in the task form, so they get dropped. Each split is a lossy compression step, and the errors compound.
• Tasks are auto-graded on the wrong axis. The generated checks are mechanical ("compiles", "lint passes", "renders"). Nothing checks "does this serve the vision / is this genuinely designed / does this feel finished." Minimum-viable-task becomes the ceiling because that's all that's verified.
• Integration is nobody's job. A car is not wheels + chassis + steering + engine as a list — it's those things working together. Task systems execute a list; "the thing that happens when it all comes together" is an afterthought task or nothing at all.
• No feedback loop mid-flight. The agent finishes task 3 and starts task 4 assuming task 3 was right. Nothing re-contextualizes: "here is the original vision, here is what you actually built — do they still match?"

---

2. Root-cause mechanisms

M1. The "task" is a lossy channel

A vision is high-dimensional (function, feel, aesthetic, UX, business intent, constraints). A task is low-dimensional (one imperative sentence + maybe a check). Information has to be discarded in the split, and standard task managers don't attach a pointer back to the vision — so the discard is unrecoverable later.

M2. Verification defaults to the mechanical tier only

Two-tier "definition of done" is rare. Most DoD = "does it compile / pass." The second tier — "is it right for the thing we're building" — is either absent or not media-native (you can't judge a UI by reading code).

M3. Design/product review is a phase, not a gate

Graphic design, if present at all, is bolted on at the end ("make it pretty after it works"). That's the wrong place — by then the structure that design informs is already baked, and you're only re-skinning a wrong-shaped thing.

M4. No "whole-system" (integration) gate

Nothing periodically assembles the partial results, runs the thing, and asks "is this converging toward a car, or drifting toward a collection of parts?"

M5. The vision isn't a living artifact

The vision lives in the first prompt, then decays. There's no versioned, mutating vison document that tasks reference by version, so drift isn't even detectable — there's nothing authoritative to diff against.

---

3. What the field already knows (research synthesis)

3a. Vertical slices / walking skeleton — the single most relevant idea

Software architecture has spent decades on your exact metaphor. The core anti-pattern to "steering wheel on a plank" is:

• Walking skeleton — build the thinnest vertical slice that touches every layer of the whole, end-to-end, FIRST. Not "car engine" then "car chassis" (horizontal layers), but "a single car that moves one meter" (vertical slice), then grow it.
• Vertical slices — every increment delivers a user-visible, working slice across all layers, not a completed layer. This is the Webnesday/Agile/DASA pattern, and it directly answers your #4.

Implication: don't decompose the vision into tasks by layer. Decompose into vertical slices, each of which is a self-contained mini-car. Then "car" is never far away — you always have a car, just a small one you grow.

3b. Definition of Done, two-tiered

The DoD concept from Scrum already says "a task isn't done until all criteria (NOT just code) pass." The field reinforces: split DoD into

• Tier 1 mechanical (builds, tests pass, runs) and
• Tier 2 systemic (matches vision, integrates, is designed, feels finished).

Tier 2 is the one nobody implements, and the one your failure needs.

3c. Human-in-the-loop as a review gate, not per-tool approval

Your own agentic-teams.md already reached the industry-validated conclusion: avoid fine-grained per-tool approval; instead gate at the task outcome with a human accept/reject + comment. The gap it didn't close: the accept/reject is a binary + comment. For vision fidelity, the review gate must be able to say what to change and why, and ideally be media-native (look at the render, not just the diff).

3d. Spec-driven development

When a system has a spec, tasks are checkable against the spec, not against a vibe-diff. For vision fidelity, the "spec" is a vision document with acceptance criteria expressed as observable behaviors, so the second tier of DoD has something concrete to check against.

3e. The "critic" / adversarial agent pattern

Multi-agent research and practice (including the "GPT critic", red-team agents, and design-review agents) show that a separate, non-executing agent that reviews against the vision catches fidelity drift that the working agent's own confirmation bias misses. This maps cleanly onto your agentic-teams persona model: a Design/Product critic persona that doesn't execute tasks but reviews them.

3f. Media-native verification

A core, under-appreciated principle: judge an artifact in its native medium.

• UI → render / screenshot / record → look at it
• Logic → scenario playthrough
• Product → user-journey walkthrough
• Motion → watch it

"Graphic design session" from your hypothesis is really this: a verification modality, not a phase. You can't code-review your way to "feels designed."

---

4. The proposed shape (how I'd answer your hypothesis)

You guessed "a better task management system + a design session per task." I agree with 80% but I'd reframe the 20% that matters most:

The fix is not "better task management." It's (a) decomposing into vertical slices instead of layers, and (b) making vision-fidelity a first-class, media-native review gate — not a phase and not a binary accept/reject.

Design principle set

1. Vision is a versioned, living artifact. A VISION.md per project, versioned. Tasks reference vision version N. Drift = diff artifact-vs-vision, which is now detectable. (This maps to mcpctl's proposal/revision/prompt resource family — revisions are exactly the append-only, semver-bumping log you already built.)

2. Decompose into vertical slices, not layers. Each slice = a self-contained mini-car: touches enough layers to be user-visible and testable end-to-end. Every increment leaves you with a working (small) whole, never a pile of parts. The "car" is always present, just small.

3. Two-tier DoD on every task/slice.

   • Tier 1: mechanical (builds, tests, runs)
   • Tier 2: systemic (matches vision vN, integrates with siblings, is designed, feels finished — each with concrete observable criteria). Tier 2 is evaluated by running the medium, not reading code.

4. A Design/Product critic persona (no execute — only review). Add a persona to agentic-teams that does not edit code. Its job: after a slice reaches AwaitingReview, it plays the artifact in its medium (render/view/run), compares against VISION.md vN, and returns a verdict with specifics (what to change + why), not a bare pass/fail. This slots into the existing lifecycle as a review session between SelfCheck → AwaitingReview.

5. Integration (whole-system) gate on a cadence. Every N slices, run an assembly review: build all merged slices, run the thing, ask "is this a car yet? what's the next smallest thing that makes it more of a car?" Feed the answer back as new slices. This answers your failure #4 directly.

6. Review gate feedback is directional, not binary. Rejecting isn't "no." It's "here's VISION vN, here's what you built, here's the specific delta." Fed back into the task as rework, exactly like your existing reject → InProgress (comment fed back) — but with a richer, media-native, design-specific comment.

---

5. How this maps onto mcpctl / agentic-teams

Your existing piece	The missing piece we add
Task entity + lifecycle	Two-tier DoD stored on the Task; slice > layer framing
Verification sessions (risk-scaled)	Media-native verification; Tier-2 check runs the artifact, not just tests
Confidence signal / escalation	Confidence ALSO scores vision-fidelity, not just "will it merge cleanly"
Persona model (QA, security engineers)	New Design/Product critic persona (review-only, non-executing)
Accept/reject gate + comment	Directional, media-anchored feedback ("here's the delta vs vision vN"), not binary
revision resource (semver append-only)	Vision as a live, versioned artifact created/managed via the same mechanism
proposal queue / dashboard	Vision-fidelity escalations surface on the same dashboard as other QA

Net: the platform already has the bones of the answer. The single most important missing concept is a review-only persona whose job is to judge the assembled artifact against a living vision document, in its native medium, with directional feedback — plus decomposition into vertical slices so you're always a small car away from the real one, never a pile of parts.

---

6. Open questions to discuss

1. Slices vs tasks in Task Master — does Task Master's expand/dependency model support the vertical-slice decomposition, or does its default push you toward layers? Worth testing with a real example ("build a car" → what tasks does it actually emit today?)
2. Where does the Design/Product critic live in the lifecycle — always, or risk-gated like QA/security?
3. How to make Tier-2 verification media-native in a headless agent — do we need render/screenshot infra, or can a design-aware persona judge from a structured artifact without pixels?
4. Vision as a resource — is prompt/revision the right home for VISION.md, or does it deserve its own resource type?
5. Cost — a review-only persona and integration gates add tokens/time. Where is it worth it (product/UI work) vs. where it's overkill (pure backend APIs)?