michal/mcpctl
1
0
Fork 0
Code Issues Pull Requests 7 Actions Packages Projects Releases 1 Wiki Activity

docs: keep superseded design-round doc history

Browse Source 
Supporting documents folded into agentic-teams.md (the canonical unified
design record), retained as historical context:

- agentic-teams-review.md (round 2)
- vision-fidelity.md (round 3 diagnosis + research)
- epic-task-artifact-model.md (Epic/epictask/task + context philosophy)
- session-summary-vision-fidelity.md (session narrative)

All superseded by docs/agentic-teams.md, which remains the source of truth.
This commit is contained in:
Michal
2026-08-08 09:03:58 +01:00
parent 5e1c6b3681
commit d24c30761b
4 changed files with 854 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
docs/vision-fidelity.md Normal file
View File

@@ -0,0 +1,222 @@
# 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)?