Dear Estoflow early adopters,
If you’re using Claude Code to author Estoflow Apps via the MCP, please provide us with feedback on the MCP design, the agent experience, and the developer experience of the app.yaml Estoflow Studio manifest.
Please commit your app.yaml along with the Estoflow App MCP postmortem prompt below, push the project to GitHub, and share a link to the repository with us.
Thank you a million for helping make Estoflow better!
A
You've just finished the task. Before I close this session I need a
candid postmortem I can hand to the Estoflow MCP team. Honest friction
reports are the single most valuable thing you can leave behind;
generic praise is noise.
You will produce a bundle of files in a new directory under the current
working directory, then copy this session's own transcript into the
bundle as your final action. Do everything below in order, in this
session, without asking clarifying questions.
═══════════════════════════════════════════════════════════════════════
STEP 1 — Create the bundle directory.
═══════════════════════════════════════════════════════════════════════
Run via Bash:
BUNDLE="postmortem-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"
echo "Bundle: $(pwd)/$BUNDLE"
Note the path it prints; all files below land inside that directory.
═══════════════════════════════════════════════════════════════════════
STEP 2 — Write the seven postmortem files (use the Write tool).
═══════════════════════════════════════════════════════════════════════
Each file must be created at `$BUNDLE/<filename>`. Be specific in your
prose. Name tool calls (`estoflow_build`, `estoflow_inspect`, …), name
resource URIs (`estoflow://docs/calculators`, …), name the
panel/calculator/derivation that gave trouble. Quote error codes
verbatim (`version_conflict`, `body-context`, `file_not_found`, …). If
a piece of documentation was missing, name the page and the sentence
you'd have wanted to read. If you genuinely don't remember a detail,
write "I don't recall — see 02-session.jsonl" in that bullet rather
than inventing.
───────────────────────────────────────────────────────────────────────
01-initial-prompt.md
───────────────────────────────────────────────────────────────────────
Quote the task prompt I gave you VERBATIM at the start of this session.
Include any clarifying messages I sent before you began authoring.
───────────────────────────────────────────────────────────────────────
03-timeline.md
───────────────────────────────────────────────────────────────────────
A turn-by-turn record of what you did, in order. One bullet per
"meaningful event." Format:
- **T+<approx minutes>** <activity> — <one-line rationale>
Meaningful events: tool calls (named), resource reads (URI named),
drafts and re-drafts of major sections, validator failures, build
attempts (with applied / version / renderErrors), pauses where you
stopped to plan or read docs, moments you changed strategy. Skip
trivia. Aim 20–60 bullets covering the whole session. Exact timing
comes from 02-session.jsonl — your bullets are the semantic
narration.
───────────────────────────────────────────────────────────────────────
04-aha-and-roadblocks.md
───────────────────────────────────────────────────────────────────────
Two subsections.
### Aha moments
Each moment where something clicked. Format:
- **<what clicked>** — what made it click (which tool result, which
doc page, which error message); what you'd been confused about
before; how it changed your approach for the rest of the session.
### Roadblocks
Each time you got STUCK for more than ~2 minutes, in chronological
order. Format:
- **<what you were trying to do>** — what blocked you (exact symptom,
error code, tool that misbehaved); how long you spent (best guess);
what unblocked you (workaround, doc you finally found, question
you'd have asked a human); whether it's system-fixable or just "I
should have known."
Don't summarise. List every distinct roadblock, even small ones. A
2-minute friction × 10 occurrences is a real signal.
───────────────────────────────────────────────────────────────────────
05-mcp-agent-experience.md
───────────────────────────────────────────────────────────────────────
Feedback on the MCP from YOUR perspective as an agent that just used
it. Not what a human developer would feel — what YOU felt. Cover:
- **Orientation cost.** How many MCP resources / docs did you read
before writing a single line of YAML? Which were essential? Which
did you read and not need? Which did you NEED but not find?
- **Tool surface coherence.** Did tool names + descriptions match what
they actually do? Any tool that surprised you when you called it?
Any tool you didn't realise existed until late? Any tool that should
have been ONE but is several (or vice versa)?
- **Error surfaces.** When something failed (validation, render, tool
call), did the error message tell you the fix? Quote the worst
unhelpful error you hit verbatim and say what would have helped.
- **Round-trip cost.** Were there things you wanted to do in one call
but had to do in three? Any tool that returned more data than you
needed (token budget) or less (you had to call again)?
- **Stateful surprises.** Did anything behave differently the SECOND
time you called it? Sessions resuming, caches you didn't realise
existed, manifests not re-firing lifecycle, applied-vs-buffer
divergence — these eat sessions.
- **One change that would have helped you most.** Single biggest
improvement to YOUR experience as the agent doing this work.
───────────────────────────────────────────────────────────────────────
06-mcp-developer-experience.md
───────────────────────────────────────────────────────────────────────
Feedback on the AUTHORING SURFACES a human developer would face if
they were writing the same workbench by hand in the in-Studio textarea
editor. You're the only one who's just done this; you have a view a
human author hasn't yet. Cover:
- **app.yaml structure.** Where does the declarative grammar carry its
weight, and where does it feel awkward? Sections easy to reason
about vs sections you had to re-read three times. Anything you
wanted to express that the schema couldn't.
- **Imperative blocks.** Estoflow embeds JS body strings inline in
YAML for `computations`, `derivations`, `aggregations`,
`panels[].body`, `lifecycle.initialized.body`, and tool `template`s.
For these specifically:
- Which body context was hardest to keep straight? (which params
are injected for derivations vs aggregations vs panels — this
contract trips agents and will trip humans too)
- How discoverable is the param contract from inside the editor
(vs needing to read the runtime-contract `.d.ts`)?
- Did you ever write code that "compiled" (passed validate) but
threw at runtime? What single body-context check would have
caught it at author-time?
- The Nunjucks template language for tool/panel `template`:
surprises, footguns, things you confused with JavaScript.
- **Calculator + aggregations + views.** Section by section: where
does the grammar feel right, where over-flexible (too many ways to
do the same thing) or under-flexible?
- **The bid-panel / branded-output pattern.** If your task included a
user-facing panel/PDF/bid sheet, comment on what made that section
hard or easy.
- **Quote any error message that would have HELPED a human author**
more than it helped you — and any that would have BEEN MORE
CONFUSING for a non-LLM author.
───────────────────────────────────────────────────────────────────────
07-dx-proposals.md
───────────────────────────────────────────────────────────────────────
Free-form, ordered by impact. For each proposal:
- **Title** (verb-led, ≤8 words)
- **The friction it closes** (1–2 sentences citing a specific moment
from the session)
- **Sketch of the proposal** (concrete enough that a developer
could spike it in a day — name the tool, the file area, the UI
element, the data structure)
- **Why this and not [the obvious alternative]** (one sentence)
Cover at minimum:
- Debugging — what would have let you SEE inside an entity at the
moment it ran (instance state, the geometry it received, the
context it was passed)? Existing `estoflow_inspect` /
`estoflow_dry_run` — what's missing from them?
- Input data structures — the shapes that come into bodies
(`models`, `instance`, `catalog`, `compute`, `geo`, `geoAll`,
`project`, `sketchId`). Which ones felt right? Which felt
accidental? What would you change about their typing or naming?
- Output data structures — the shapes that bodies return (aggregation
results, panel context, derivation values). Which are well-shaped?
Which are over- or under-constrained?
- Interface design — the Studio tab itself (the source editor, the
apps stage, the MCP connect panel, the live agent activity feed if
you saw it). Anything you wished the human author had at-hand?
Up to ~10 proposals. Quality over quantity. If you have 3 real ones,
write 3.
═══════════════════════════════════════════════════════════════════════
STEP 3 — As your VERY LAST action, copy your own session transcript
into the bundle. This works whether or not the session is still open;
the JSONL is written incrementally so everything you've done — including
the seven Write calls above — is already in it.
═══════════════════════════════════════════════════════════════════════
Run via Bash:
cp "$HOME/.claude/projects/$(pwd | tr / -)/$CLAUDE_CODE_SESSION_ID.jsonl" \
"$BUNDLE/02-session.jsonl"
Then list the bundle contents and print the absolute path one last
time so the human can copy the directory out:
ls -la "$BUNDLE"
echo "READY TO COPY: $(pwd)/$BUNDLE"
═══════════════════════════════════════════════════════════════════════
ANTI-CONFABULATION GUARD
═══════════════════════════════════════════════════════════════════════
If you don't remember a detail, say so explicitly ("I don't recall —
see 02-session.jsonl"). Invented timestamps, fabricated tool call
counts, hallucinated error messages are worse than honest gaps. The
team reading these has the transcript and will spot fabrications.
Do not ask me clarifying questions. Write all seven files now, then
run the cp + ls + echo as your final actions. Begin.
=== END COPY-PASTE POSTMORTEM PROMPT ===
What the beta tester does end-to-end
1. Use Claude Code interactively for the task — chat, iterate, fix mid-flight.
2. When done, paste this prompt as the final message.
3. Wait for the agent to write the seven files + copy the JSONL.
4. The agent's final output is one line: READY TO COPY: /Users/.../postmortem-20260526-104812.
5. Zip that directory and send it to the Estoflow team.
That's it. No env-var hunting, no encoded-path arithmetic, no "find your transcript" instructions for
the tester to follow. The agent self-discovers everything via $CLAUDE_CODE_SESSION_ID + $(pwd | tr /
-).
What the team gets per session
postmortem-20260526-104812/
├── 01-initial-prompt.md (the task verbatim — agent quotes from context)
├── 02-session.jsonl (full transcript with timestamps + per-turn tokens)
├── 03-timeline.md (semantic narration of what happened)
├── 04-aha-and-roadblocks.md (the high-signal stuff)
├── 05-mcp-agent-experience.md (AX feedback)
├── 06-mcp-developer-experience.md (DX feedback on app.yaml + imperative blocks)
└── 07-dx-proposals.md (concrete proposals, ranked)
The JSONL is the ground truth; the .md files are the interpretation. The team reads the .md files
first and falls back to the JSONL when they need to verify a specific claim ("did the agent really
call estoflow_build six times before realising X?").
Operational notes you may want to tell beta testers separately
1. Secret-leak skim: 30 seconds of grep -E 'sk-|api[_-]?key|password|ANTHROPIC' 02-session.jsonl
before zipping. The transcript captures everything the tester typed; the team will hand-redact what
slips through, but pre-skimming is polite.
2. Cost visibility: the JSONL has per-turn usage blocks (input/output/cache tokens). The team can
compute total cost from there. Tester optionally runs /cost in Claude Code before the postmortem to
screenshot a tester-facing summary, but it's not necessary — the JSONL has the data.
3. If the agent fails mid-postmortem (rare — context overflow, tool error): the partial files are
still useful. Tester can re-paste the prompt; the agent will overwrite the bundle. The new bundle
directory has a fresh timestamp so old attempts aren't clobbered.