mcpctl/docs/session-summary-vision-fidelity.md

# Session Summary — Vision Fidelity in Agentic Teams (full discussion)

> **Status:** Consolidated session record — captures everything discussed, in
> order, so it reads as one coherent thread.
> **Date:** 2026-08-08 · pi session · mcpctl repo
>
> **IMPORTANT — canonical doc:** since this summary was written,
> `agentic-teams.md` was updated and is now the **single authoritative, unified
> design document** that **supersedes** this summary plus `vision-fidelity.md`,
> `epic-task-artifact-model.md` and `agentic-teams-review.md`. Read
> `agentic-teams.md` for the source of truth; this summary is the session
> narrative and highlights the sections the canonical doc added beyond it.

---

## Part 1 — The problem statement

We started with a recurring failure with LLM coding agents:

> 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

Every task completed, yet no car. The diagnosis (see `vision-fidelity.md` for
the full write-up): **this is not an execution problem — it's decomposition +
verification.**

### Root causes
1. **Decomposition is lossy** — a multidimensional vision compresses into flat
   imperatives; the *why* and *what-good-looks-like* get dropped.
2. **Tasks are graded mechanically** — "compiles / lint / renders," never "does
   this serve the vision / is this designed / does this feel finished."
3. **Integration is nobody's job** — a car is parts *working together*, but
   task systems execute a list.
4. **No feedback loop** — the agent assumes task 3 was fine and never re-checks
   against the original vision.
5. **Design/product review is a phase, not a gate** — applied at the end, when
   the wrong shape is already baked.

### Research synthesis (from the write-up)
- **Vertical slices / walking skeleton** — decompose into `mini-wholes`
  (user-visible, end-to-end slices), not layers. Always have *a* small car, not
  a pile of parts.
- **Two-tier Definition of Done** — mechanical tier + systematic tier (matches
  vision, integrates, is designed, feels finished). Tier-2 evaluated by running
  the medium, not reading code.
- **Review-gate HITL over per-tool approval** — consistent with round-2.
- **Spec-driven + media-native verification** — judge an artifact in its native
  medium (render/run for UI).
- **Critic-agent pattern** — a non-executing persona that reviews against the
  vision catches drift the working agent's confirmation bias misses.

---

## Part 2 — Grounding in the repo (the "other window")

We confirmed this connects to real, existing machinery:

- **mcpctl agent platform** — persistent agent personas, project prompts,
  `ResourceRevision` (versioned log), `ResourceProposal` (review/approve
  queue), personalities (same agent, different judgment via prompt overlays).
- **gstack skills** (installed skill library) — `/autoplan` (auto-review
  pipeline: CEO → Design → Eng → DX), `/plan-ceo-review` (grand-vision
  guardian, nuclear scope challenge, 10x vision), `/plan-design-review`
  (rates each design dimension 0-10, generates visual mockups, "text
  descriptions are not a substitute for showing what it looks like"), `/spec`.
- **`agentic-teams.md` + `agentic-teams-review.md`** — the durable design
  record, landed on **async, artifact-driven, human-as-fuse** (section 1 of
  the review round is the through-line).

**Key realization:** the platform reviews the *plan* hard before build, but
**nothing reviews the *built result* against the vision after implementation**,
and **no vision artifact exists as a first-class, versioned resource**. That's
the gap today's design fills.

---

## Part 3 — Where we landed: the Epic model

We reframed VISION.md → **Epic**, in Jira nomenclature — and it's the thing we
discussed in *this* window's second half. Full spec in
`epic-task-artifact-model.md`.

### The Epic is the vision
- The **back-and-forth discussion before coding starts** *is* the vision; the
  Epic captures its conclusion. It's project-scoped.
- Holds the **agreed "done" criteria** (checkable outcomes + intent/quality
  attributes) written at vision time, plus scope-change history (revisions) and
  **accepted-tradeoff decisions**.

### Epic lifecycle — "done" only two ways
An Epic reaches **done** only when:
1. **100% of the vision is delivered**, OR
2. The **user explicitly accepted tradeoffs** (e.g. an issue we couldn't fix) —
   recorded on the Epic, so done is honest + auditable.

**The comparison moment is the `exec` trigger.** Delivered-whole vs Epic → gaps
route to:
- **reopen** under-delivering tasks, or
- **new tasks** for never-decomposed pieces, or — when it's a hard "we
  couldn't fix X" — a **joint `exec` debugging session** (the pi / Claude-Code
  live experience). This gives `exec` a concrete, principled trigger.

---

## Part 4 — Data model: task / epictask / Epic

Hierarchy (details in `epic-task-artifact-model.md` §2):

```
Epic (the vision)
  └── epictask — roadmap node; tasks hang off it; chains to other epictasks
        └── task — the unit of work (own lifecycle from round 1)
```

- **tasks link to epictasks**; **epictasks chain to each other** → visualizing
  all epictasks gives a **spider-web roadmap** (dependency graph, not flat).
- Walking any task up the chain reaches the Epic's "done" criteria, so
  **tier-2 / vision DoD is reachable from every task**.

### Reopen vs new-task
| Gap cause | Outcome |
|---|---|
| A task under-delivered its acceptance criteria | **Reopen** (directional comment back) |
| A piece was never decomposed (breakdown gap) | **New task** under the epictask |
| Hard problem / needs joint effort | **`exec` joint session** |

---

## Part 5 — Artifacts + IPython-style context (prime-agent philosophy)

Borrowed from [prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)'s
**"context as variables / prompt-as-a-variable"** (details in §4 of the model
doc):

- **Artifacts are objects, not plain text** — `files|test`, logs, and also
  **PR & commits** as structured objects with an `expand` operation (not
  dumped into context).
- **"Cat" → variable/artifact** — a named, retrievable reference, **not
  auto-injected**.
- **Rule: context does NOT auto-populate from artifact content.**

### Eviction / flush priority (recoverability-driven)
1. **User's words** — highest retention.
2. **Agent's words** — next.
3. **Artifact context** — evict first, *because artifacts are durably stored
   and recoverable via `expand`*. **Eviction priority follows recoverability.**

The elegant win: dropping artifact-context first is *cheap* because it's
recoverable — most compaction schemes don't formalize this, and it turns a
hand-wavy "compaction" into a principled hierarchy.

---

## Part 6 — Open questions / tensions (carried forward)

1. **Epic as a resource vs a prompt** — own resource type (RBAC + revisions) or
   reuse project prompt/skill? Lean: own resource.
2. **Epic-level vs epictask-level "done"** — should epictasks carry their own
   acceptance criteria so the spider web shows per-node completeness? Lean: yes.
3. **Comparison unit: task-level or epictask-chain-level?** A gap can cross
   multiple linked epictasks; a single "reopen" may not express "this chain is
   incomplete." Decide whether comparison happens per-task or per-chain.
4. **`exec` as a deliberate carve-out** — the async model is default, but the
   Epic-gap triggers sync `exec` *by design*. Name this so it doesn't conflict
   with the round-2 async decision (LE-4).
5. **Accept-tradeoffs needs structure** — record *what, why, who, de-scoped-by*
   as a revision on the Epic.
6. **Naming (LE-7)** — `epictask` spelling; and `task` vs repo's `.taskmaster`
   tasks.
7. **Artifact storage** — server-side mcpctl-owned for binaries/builds (per
   LE-8/LE-5); commits/PRs stay in git/repo and are referenced as objects.
8. **Post-build re-verification** — the remaining product-side gap: nothing
   re-checks the rendered/built result against the reviewed mockup/vision after
   implementation (the `design-review`/`qa` path is opt-in, not wired into the
   Epic-comparison loop).

---

## Referenced artifacts produced today

| File | Purpose |
|---|---|
> See `docs/agentic-teams.md` — now the single unified document (supersedes
> `vision-fidelity.md`, `epic-task-artifact-model.md`, `agentic-teams-review.md`,
> and this summary).

## Part 7 — What the canonical `agentic-teams.md` added beyond today's thread

When reviewing the updated `docs/agentic-teams.md` (which folds in everything
we discussed), these sections were found to be **new / more evolved** than the
session thread above — worth reading there:

1. **Two-level verification model (§3)** — formalised table: **Tier 1**
   Correctness/Security/Ops (inside the task lifecycle) vs **Tier 2** Vision
   Fidelity/Design (at the Epic, media-native). They do not replace each other.
2. **SRE/Release review stage (§6)** — Tier-1 stage inside the task loop that
   reviews **deployment-as-code** (IaC, release manifests, container config)
   against the project's **actual deployment model/infra** (Kubernetes vs
   Portainer vs EC2 vs local). Worked example: a **missing network egress
   policy** silently blocks traffic and a developer LLM deep-dives the wrong
   debugging path — so the SRE persona must carry per-project infra gotchas.
3. **Task lifecycle expanded (§6)** — `InProgress → Build/Run → Self-Testing →
   QA → Security → SRE/Release → Done → AwaitingReview → accept→Merged / reject→InProgress`, with stage feedback bouncing back to InProgress.
4. **Script artifacts (§11)** — a `script` artifact kind (tool-as-a-script,
   like a skill but *as code*) at three scopes: task / project / agent. Captures
   a procedure once instead of re-deriving it; context-saving via `expand`;
   learned-and-reused.
5. **Baseline scorecard / "basics rules agent" (§11b)** — a provisioned
   default list of baseline rules (e.g. "always make unit tests") checked by a
   scorecard agent; distinct from Tier-1 QA/Security/SRE and Tier-2 critic — a
   baseline-behaviour/standards gate.
6. **Artifact term collision (§11)** — the noun collision resolved: **build-artifact
   store** (durable storage for binaries) vs **context-artifact** (lazily-loaded,
   expandable object in the LLM window). Two axes, one noun; must not be conflated.
7. **Hotfix motivating example (§4)** — delta-check vs full-rescan economic
   argument for memory + coverage ledger.
8. **Collaboration modes (§5)** — standup (on-demand, artifact-driven), joint
   debugging/architecting, present architectural decisions, ask-the-human-for-help,
   work-alone-when-confident.
9. **Consolidated open questions (§15)** — now 16 items, including brain
   ownership, naming (LE-7), prompt delivery, exec carve-out, Epic vs epictask
   done, Epic-as-resource, comparison unit, accept-tradeoffs structure, artifact
   storage, merge recovery, dashboard surface, Tier-2 media-native infra, MVP
   order, script-artifact design, incentive & scorecard.
10. **MVP path (§16)** — 8 steps now include the vision layer (Epic/epictask/task)
    first, then runtime adapter, lifecycle + QA/Security/SRE, Tier-2 critic +
    Epic-comparison, collaboration modes, confidence/dashboard, memory/coverage +
    context-artifacts, then script artifacts + baseline scorecard.