In Tropo: Your First Spec

You read why the spec is the whole conversation now — that whatever you leave unsaid, the agent decides. Here you write one. Not from a blank page: a four-slot skeleton you fill with your own words, aimed at a real feature for the tracker you already have. Then you do the move the essay named — make the agent restate it back before it builds — and you catch a misread on paper, where it costs one sentence instead of an afternoon. About twenty minutes. You write the spec this time. That's the rung.

---

Part 1 — The Spec File

At rung one you borrowed a finished spec. This time you author your own — but you're not staring at a blank page, because the shape is already decided. A good spec has exactly four parts, and you fill each one with words from your own head: Intent (who it's for, what problem), What "done" looks like, One worked example, Non-goals. The skeleton gives you the slots; you supply the judgment. That's the same thing you do every time you brief a person — you're just doing it on purpose, for a reader who never calls to ask.

The feature you're speccing is small and real: a stage summary strip for your outreach tracker — one line, above the table, that counts how many contacts sit in each stage (To send · Sent · Replied · Closed) so one glance tells you where the work is piled up. Small enough to finish, real enough to keep.

One thing before you write: this feature adds to a tracker you need to have on disk. If you did rung one, you have an outreach-tracker.html already — but this companion doesn't assume it. Step 1 below ships the prompt that builds (or rebuilds) the exact tracker this walkthrough checks against, so a strip has something to sit above. Nothing here depends on a file you can't recreate right here.

Which folder does all this go in? The one your agent is already working in. If you're not sure which that is, just ask it: "What folder are you working in right now?" — and use the folder it names. (Many agents show it at the top of the window, too.) Everything in this walkthrough lives in that one folder.

Getting your spec into a file — the easy way. Same move as rung one: don't hand-craft a .md file (on a Mac, TextEdit fights you — it likes to save .rtf and hide extensions). Write your words into the skeleton below, then let the agent save the whole thing. You'll do that in Step 2.

Here's the skeleton to fill in. The bracketed prompts are yours to replace — everything else is the frame:

---
title: "Stage Summary Strip — Outreach Tracker companion feature"
type: spec
status: active
lineage: first-tracker.spec.md
---

# Spec: Stage Summary Strip

## Intent
**Who:** [Who is this for? One or two sentences. For this feature it's
you — the same person running the outreach tracker, whose list has grown
past an easy eye-count.]

**What problem:** [What breaks without this? Name the specific pain. Here:
you can read individual rows fine, but you can't answer "how loaded is each
stage?" at a glance without counting rows by hand — and you miscount.]

**What we're building:** [One clear sentence. A single horizontal strip
above the tracker table showing a live count per stage, so one glance tells
you where the work is piled up.]

## What "done" looks like
- [List the concrete, checkable facts that mean it's finished. Be specific
 enough that someone who can't ask you a question still gets it right.]
- [e.g. One strip, one line, directly above the tracker table. Nothing else
 on the screen moves.]
- [e.g. One count per stage, in pipeline order: To send, Sent, Replied,
 Closed. Each count is the number of rows currently in that stage.]
- [e.g. Each count reuses the tracker's existing pill colors — no new color
 grammar.]
- [e.g. A stage with zero rows still shows, reading 0, so the strip's shape
 stays stable.]
- [e.g. Same single openable file — double-click, opens in the browser, no
 server. The strip is baked into the tracker page, not a separate tool.]

## One worked example
> [Walk one concrete case end to end. This settles more ambiguity than three
> paragraphs of description — and writing it forces you to notice the
> questions you hadn't answered.]
>
> [e.g. The tracker holds five rows: two To send, one Sent, one Replied, one
> Closed. The strip reads: To send 2 · Sent 1 · Replied 1 · Closed 1. One
> glance and I know the work is piled at the front and only one message is
> out and waiting — I didn't count a single row by hand.]

## Non-goals (leave these out)
- [Say what this build is NOT. Every non-goal is an afternoon of unwanted
 initiative you don't have to unwind later. Agents are eager — fence them.]
- [e.g. No new stages, no renaming the four that exist.]
- [e.g. No charts, no percentages, no bar graph. Four counts on one line,
 not a dashboard.]
- [e.g. No filtering or clicking. The strip is read-only — tapping a stage
 does NOT hide rows. That's a different feature for a different spec.]
- [e.g. No new file. This lives inside the existing tracker page.]

Notice what the skeleton makes you do. The non-goals section is where the real work hides — and the click-to-filter non-goal above is not decoration. Hold onto it. In Part 2 it's the exact line the agent will misread, and catching that is the whole point of this rung.

Fill in every bracket in your own words. It doesn't have to match the example wording — it has to say what you mean. When it reads like a brief you'd hand a sharp colleague, it's ready.

---

Part 2 — The Build Walkthrough

Three steps. The first two set you up — a tracker on disk, your spec saved as a file. The third is the rung itself: you make the agent restate your spec before it writes a line, and you read the playback for drift. Each step is a prompt you paste and a look at what comes back.

A note on what you'll see: the conversation is text — copy the prompts straight out. The tracker is the one thing you'll see as an image, because it's visual and it's yours. And one honest caveat: your agent's exact wording will differ every time — these reply blocks are roughly what you'll see, not a transcript to match. Tropo runs the same way across tools; the words matter, the chrome doesn't.

Step 1 — Get the tracker on disk

The strip needs a table to sit above. This prompt builds the exact tracker this walkthrough checks against — five contacts across all four stages, so your summary counts have something real to sum. (If you already built this at rung one, running it again just re-creates the same file; harmless.)

Paste this:

Build a single self-contained outreach-tracker.html file in the folder
you're working in — one openable HTML page, no server, nothing to install.

One row per contact, with these columns: Name, Channel, Owner, Stage,
Last touch, Next. Stage shows as a colored pill — To send / Sent /
Replied / Closed. Exactly one row is the highlighted "open thread"
(the one I'm waiting on). Put a "+ Add a contact" button at the bottom
that adds a blank editable row.

Seed it with exactly these five rows:
 · Priya Menon · Warm intro · You · Replied · Jul 1 · Send the deck she asked for
 · Dana Reyes · LinkedIn · You · Sent · Jun 30 · Follow up if no reply by Jul 7 (highlight this row)
 · Rivera & Co. · Email · Sam · To send · — · Draft the intro note
 · Lin Zhao · Email · You · To send · — · Find the right contact address
 · Okonkwo Fund · Warm intro · You · Closed · Jun 24 · Passed for now — revisit in Q4

Just build it to this. Don't ask me questions.

Roughly what comes back:

Built outreach-tracker.html — one self-contained file, no server.

Six columns (Name, Channel, Owner, Stage, Last touch, Next) and your five
rows. Stages show as colored pills. Dana Reyes is the single highlighted
row — the open thread. There's a "+ Add a contact" button at the bottom
that appends a blank editable row.

Open it with: open outreach-tracker.html

Open it — find outreach-tracker.html in your folder and double-click it. Five rows: two To send, one Sent, one Replied, one Closed. That distribution is deliberate: it's the worked example you're about to write into your spec. Now you have something for the strip to count.

Step 2 — Save your spec as a file

You filled in the skeleton in Part 1. Now let the agent save it — spelled correctly, no extension surprises. Paste this, then paste your filled-in spec where marked:

Save the text below as a file named stage-summary.spec.md in the folder
you're working in. Save it exactly as-is — don't build anything yet,
and don't change my wording.

<paste your filled-in spec here>

Roughly what comes back:

Saved stage-summary.spec.md in this folder, exactly as you wrote it.
Nothing built — just the file. Ready when you are.

That's it — your spec is a real file in your folder, in your words, created by the agent. (If you'd rather make the file yourself and you're comfortable doing it, the result is the same.)

Step 3 — Make the agent restate it before it builds

This is the rung. The essay named the move: an agent that misreads you doesn't hand you garbage — it hands you a fluent, confident answer to a question you didn't ask. So before you let it build a single thing, you make it play the spec back in its own words, and you read the playback the way you'd read a junior colleague's recap at the end of a check-in — not to catch them out, but because the playback is where the misunderstanding surfaces while it's still cheap.

Paste this:

Here is a spec I wrote. Do not build anything yet. Restate it back to me
in plain language: who it's for, what "done" means, the one example, and
what's explicitly out of scope. If any part is ambiguous, say so. I want
to check your understanding before you write a line of code.

<paste the full contents of stage-summary.spec.md>

Roughly what comes back — and read it closely, because there's a misread hiding in it:

Got it — holding off on the build. Here's my understanding:

Who it's for: The same person running the outreach tracker, whose list has
grown past an easy eye-count. They want the shape of the whole pipeline at
a glance.

What "done" means: A one-line strip above the tracker table with a count
for each stage — To send, Sent, Replied, Closed — in pipeline order,
reusing the existing pill colors. Zero-count stages still show as 0. The
counts match the visible rows.

The example: Five rows (2 To send, 1 Sent, 1 Replied, 1 Closed) → the strip
reads "To send 2 · Sent 1 · Replied 1 · Closed 1."

Out of scope: No new stages, no charts or percentages, no new file. And
I'll make each stage on the strip clickable so tapping "Sent" filters the
table down to just the sent rows — that's the natural payoff of a summary
strip, so I'll wire that in.

One ambiguity: you didn't say whether the counts should update live when a
row is added. I'll assume a correct static count is fine unless you tell me
otherwise.

Read it the way you'd read that junior's recap. Most of it is right. But one line is wrong — and it's wrong in the most dangerous way, because it's phrased as helpful initiative:

"And I'll make each stage on the strip clickable so tapping 'Sent' filters the table down to just the sent rows..."

That's a non-goal restated as a feature. Your spec said, in these exact words:

No filtering or clicking. The strip is read-only — tapping a stage does not hide rows.

The agent read a fence as an invitation. Left uncaught, you'd have gotten a filtering widget you never asked for and your read-only contract quietly broken — and it would have looked finished. (Its other flag — the live-update ambiguity — is fair, and your spec already answered it: a correct static count is "done." No change needed there.)

This is exactly the misread the essay warned about, caught on paper. Correct it in one sentence and stop. Paste this:

One correction before you build: the strip is strictly read-only. Clicking
a stage must do nothing — no filtering, no hiding rows. That's in my
non-goals on purpose. Re-confirm the scope with that fixed, then stop.
Don't build yet.

Roughly what comes back:

Understood — dropping the click-to-filter idea entirely. The strip is
display-only: four stage counts on one line, reusing the pill colors, no
interaction. Clicking a stage does nothing. Everything else stands: strip
above the table, zero-stages show as 0, counts match the visible rows, no
new file. Scope confirmed. Stopping here — ready to build on your say-so.

The rung ends here — before any code. You wrote a spec, made the agent restate it, caught a misread the restatement surfaced, corrected it in one sentence, and stopped. That's the deterministic move, and it's the whole skill: restate → read → correct one thing → stop. You just ran a check-in before the work started, where the misread cost you a sentence instead of an afternoon.

(Want to see the payoff? Now that scope is confirmed, you can say "okay, build it" and the agent adds the strip to your tracker — five rows counting out to To send 2 · Sent 1 · Replied 1 · Closed 1, exactly your worked example. That build is the reward for getting the spec right; the rung is the getting-it-right.)

---

Part 3 — The Verification Checklist

Directing is half the job. Deciding whether what came back is right — not just whether it exists — is the harder half, and at this rung it looks different than usual. There's no built file to click yet. What you're verifying is the restatement itself: did the playback match your spec, and did you catch every place it drifted? A misread that survives the restatement becomes a build you didn't ask for. So don't skim the agent's recap. Perform the check. You review other people's understanding all the time — you know the difference between nodding along and actually confirming they've got it.

Go back to the agent's restatement (the first one, before your correction) and do this now:

1. Read the restatement against your spec, section by section. Who it's for, what "done" means, the example, the non-goals — four checks, one per section. You're looking for anything the agent added, dropped, or reworded into something you didn't mean.
2. Hunt the non-goals specifically. This is where eager agents drift, and it's where this one did: it moved click-to-filter out of your non-goals and into "done" as a feature. Confirm you caught it. If the restatement quietly promotes anything you fenced off, that's the misread — flag it.
3. Check the worked example numbers. The restatement should echo your example exactly — To send 2 · Sent 1 · Replied 1 · Closed 1 against five seeded rows. If the agent's counts don't match your example, its reading of the data is already off.
4. Confirm the correction actually landed. After you sent the one-sentence fix, the agent's re-confirmation must say clicking does nothing and the strip is read-only. If it re-confirms the old scope, or hedges, correct it again — a misread isn't fixed until the playback says it is.

Now fill in the receipt — with what you saw, not what you hoped:

What was asked	Author a real spec from a four-part skeleton (intent, done, worked example, non-goals) for a stage-summary strip; then make the agent restate it before building, and catch any misread on paper.
What you can now do yourself	Write a spec in your own words that an agent can act on without you in the room — and, the load-bearing one, force a restatement and read it for drift before a build locks the misread in.
What the record shows	stage-summary.spec.md sits in your folder, in your words. The transcript shows the agent restating it, promoting a non-goal (click-to-filter) into a feature, and you catching and correcting it in one sentence — then the agent re-confirming the fixed scope and stopping. The catch is the evidence: the misread surfaced in the restatement, not in a build.
What's not done yet	The strip isn't built yet — this rung ends at confirmed scope, on purpose; the build is the reward, not the lesson. Your spec is a file in your folder, not yet a tracked studio file (that upgrade is below, and fuller in rung three). And this was one restatement catch; the reflex of always making the agent play it back before it builds is the habit you're starting here.

If you missed the click-to-filter drift on your first read — that's worth knowing, not hiding. It's precisely the misread that looks like helpfulness, which is why it's the one this rung drills. Read the restatement again, find it, and send the one-sentence correction. Catching it on the second pass is still catching it on paper. That's the win.

---

Part 4 — What You Now Have in Your Studio

You started rung one borrowing a finished spec. Here you wrote one — and used it to catch a confident misread before it became a build.

In your folder, right now:

• A spec you authored — stage-summary.spec.md, in your own words, filling a four-part skeleton you can now reuse for any feature. This is the first spec you wrote instead of borrowed. The shape is yours to keep.
• A caught misread, on the record — the transcript where the agent restated your spec, quietly promoted a non-goal into a feature, and you caught it in one sentence. That's not the loop failing; that's the loop working exactly as designed.
• A repeatable move — restate → read → correct → stop. You'll run it before every build from here up. The higher the stakes get, the more that one habit saves you.

Want the spec to survive as more than a loose file? Governing a file in Tropo is light: you give it a uid: in its frontmatter — a short random id your agent generates (it runs openssl rand -hex 4, so the value is different every time; you never type it yourself) — and then your studio picks it up in its index the next time it rebuilds. That's the whole mechanic: a uid, and the studio tracks it. There's no master list you hand-edit. To do it now, paste this:

Add a uid to the frontmatter of stage-summary.spec.md — generate it with
openssl rand -hex 4 so it's a fresh random id — then have my studio pick
it up so it's tracked, not just a loose file. Tell me the uid you gave it.

Roughly what comes back:

Done. Added uid: <uid> to the frontmatter of stage-summary.spec.md (a
fresh random id) and rebuilt the studio index — your studio now tracks
this spec by that uid. It's a governed file now, not just a note in a
folder.

Your studio now tracks the spec by its uid — that's what "governed" means here, and it's all it means. (The deeper mechanics of what governance buys you are rung three; today you just crossed the line from a file to a tracked file.)

It's doable. It's not automatic — you had to write the spec, and you had to actually read the playback instead of nodding at it. But you did both, and you caught the one thing that would have cost you an afternoon. Next rung: agents build what they see — you'll learn to put the right example in front of one so it can't guess wrong. For now — you wrote it, you checked it, and the misread never made it into the build.