docs: keep superseded design-round doc history
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
230
docs/session-summary-vision-fidelity.md
Normal file
230
docs/session-summary-vision-fidelity.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user