agentrel 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:
- Stop the clock on that step.
- Record a blocker: what was missing, and where a reader would have to go to find it.
- Record the recovery cost — the realistic time to search docs, read source, or ask.
- 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:
- Result — happy path, realistic, grade, entry point
- Step table — every step with source, elapsed, status
- Blockers — each with what was missing, recovery cost, and the fix
- The three biggest wins — ranked by seconds saved per hour of work
- 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.