# Ttfv Trace

> Measure how long a cold developer needs to get from landing page to a first successful API call, and report exactly where the time goes. Walks the quickstart step by step as a first-time reader would, times each step, records every blocker and undocumented prerequisite, and grades the result against published time-to-first-call benchmarks. Use when asked how long onboarding takes, to measure or improve time to first value or time to first call, to find onboarding and quickstart friction, or to test whether a getting-started guide actually works.

- Skill: `agentrel/ttfv-trace` (Agent Skill)
- Install (CLI): `npx skillmds@latest add agentrel/ttfv-trace`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agentrel/ttfv-trace/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: agentrel (https://skillmd.com/u/agentrel)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agentrel/ttfv-trace

---


# Time-to-first-value trace

Walk a quickstart the way a stranger would and time it. Most teams have never measured
this; the industry-standard method is still a stopwatch, which is why nobody does it twice.

The output is a per-step timing table with the blockers named. That table is the finding —
a single number tells a team they are slow, the table tells them which paragraph to fix.

## Applies to

| | |
|---|---|
| **Project types** | Anything with a self-serve onboarding path — APIs, SDKs, CLIs, frameworks, developer platforms |
| **Stage** | Any product with a published quickstart. Most valuable immediately before a launch or paid campaign, since traffic pointed at slow onboarding wastes the spend |
| **Needs** | A quickstart, getting-started guide, or a README with setup steps |
| **Skip if** | No public onboarding path exists yet, or the product is sales-led with an implementation team — there is no cold-developer journey to time |

Also worth running after any change to auth, installation, or the first-call flow. Those
edits are where onboarding silently regresses.

## How to use

```
/agentrel:ttfv-trace                             trace this repository's quickstart
/agentrel:ttfv-trace https://docs.acme.com       trace a public onboarding path
/agentrel:ttfv-trace ./docs/getting-started.md   trace a specific document
```

Produces `ttfv-report.md` and a printed timing summary. Read-only.

Safe commands are executed for real timings. Paid signups and destructive steps are never
run — those rows are marked `(estimated)`.

## The rule that makes this work

**Follow only what is written.** You know how APIs generally work. The developer you are
simulating does not know how *this* one works. Every time you supply knowledge the
documentation did not, you hide the exact friction you were sent to find.

When a step needs information that is not on the page:

1. Stop the clock on that step.
2. Record a **blocker**: what was missing, and where a reader would have to go to find it.
3. Record the recovery cost — the realistic time to search docs, read source, or ask.
4. Supply the missing knowledge, restart the clock, and continue.

A trace that completes with zero blockers and a suspiciously fast time usually means you
used prior knowledge. Re-read the steps and check.

## 1. Find the entry point

Start where a real developer starts, not at the most convenient file.

| Target | Entry point |
|--------|-------------|
| Public product | The docs landing page, or the site's "get started" link |
| Repository | `README.md`, then `docs/quickstart*` or `docs/getting-started*` |
| Explicit path | Whatever the user names |

Record the entry point in the report. If finding it took more than one click or one obvious
guess, that is blocker zero, and it is a common one.

## 2. Walk and time each step

Segment the path into steps. A step is one thing a developer does: read a page, install a
package, create an account, copy a snippet, run a command.

For each step record:

| Field | Notes |
|-------|-------|
| Step | What the developer does |
| Source | `file:line` or URL where the instruction lives |
| Elapsed | Realistic time for a competent stranger — see the cost model |
| Status | `clean`, `friction`, or `blocked` |
| Note | Only when not clean |

Run the commands where it is safe to do so — installs, builds, and local runs give real
timings and catch broken instructions. Do not create paid accounts, do not spend money, and
do not run anything destructive. Where a step cannot be executed, estimate with the cost
model and mark the row `(estimated)`.

### Cost model

Use these when timing cannot be measured directly. They are deliberately generous to the
product being audited.

| Action | Time |
|--------|------|
| Read a short page and decide what to do | 30 s |
| Read a long or dense page | 2 min |
| Copy and adapt a snippet | 45 s |
| Install a package (measure where possible) | measured |
| Create an account, no verification | 90 s |
| Create an account with email verification | 4 min |
| Find and create an API key | 2 min |
| Resolve an undocumented prerequisite | 6 min |
| Debug a broken example | 10 min |
| Read source to find an answer docs omit | 12 min |
| Ask in a support channel and wait | 4 h |

Never count your own reading speed. You read faster than the developer you are simulating,
and the point is their clock.

## 3. Grade the total

Benchmarks are published and widely cited. Grade against them rather than inventing a scale.

| Total TTFV | Grade | Reading |
|------------|-------|---------|
| under 2 min | **Strong** | A reference onboarding path |
| 2–5 min | **Competitive** | Where most well-run APIs land |
| 5–15 min | **Friction** | Losing casual evaluators |
| 15–45 min | **Poor** | Only motivated developers complete this |
| 45 min+ | **Blocking** | Onboarding is the primary adoption constraint |
| Not completable | **Broken** | The quickstart does not work as written |

Report two figures and label them clearly:

- **Happy path** — total assuming no blockers, i.e. the time the team thinks they have
- **Realistic** — total including blocker recovery, i.e. the time a stranger actually spends

The gap between them is usually the most useful number in the report, because it is the
part the team cannot see from the inside.

## 4. Write the report

Write `ttfv-report.md` with:

1. **Result** — happy path, realistic, grade, entry point
2. **Step table** — every step with source, elapsed, status
3. **Blockers** — each with what was missing, recovery cost, and the fix
4. **The three biggest wins** — ranked by seconds saved per hour of work
5. **Method** — what was executed, what was estimated, what was skipped and why

Then print:

```
TIME TO FIRST VALUE

  Happy path      4m 10s
  Realistic      19m 40s      ← what a stranger actually spends
  Grade          Poor
  Blockers       3

  Largest cost   Undocumented ANTHROPIC_REGION env var   +6m
  Fastest win    Add the env var to the quickstart       ~15m work

Report → ./ttfv-report.md
```

## 5. Rank the fixes

Order by seconds saved per hour of engineering. This nearly always puts documentation edits
above product changes, which is the correct and frequently unwelcome answer.

State it plainly: a missing sentence that costs every developer six minutes is worth more
than a week of SDK work.

## Notes

- **Never spend money and never create paid accounts.** Mark those steps `(estimated)`.
- **Never modify the audited project.** One report file in the working directory, nothing else.
- Where a sandbox or playground exists, trace **both** paths — the no-signup path and the
  real-credentials path. Teams often optimise one and forget the other.
- If the quickstart is genuinely fast, say so and stop. A 90-second onboarding needs a
  one-paragraph report, not a manufactured list of concerns.