Next Browser

synthesize-transcript

Read the transcript at:

$ARGUMENTS

Then analyze how the agent used next-browser commands. Your goals are to: 1. Find generalizable learnings — things that would help any agent using this tool — and propose targeted additions to SKILL.md. 2. Surface feature requests and bug fixes for the CLI itself — gaps in functionality, incorrect behavior, or misleading output that should be fixed in code.

Process

1. Read the transcript in chunks (it's large). Focus on assistant messages and tool calls/results involving next-browser commands.

2. Identify friction and patterns. Look for:

• Commands that failed or produced unexpected results
• Misunderstandings about how a command works
• Workflows the agent discovered through trial and error
• Repeated mistakes that guidance would prevent

3. Filter ruthlessly for overfitting. For each candidate learning, ask:

• Would a different agent on a different project hit this same issue?
• Is this a property of the tool or a property of this debugging session?
• Is this already obvious from the command's existing docs?
• Is this prescribing a specific workflow vs documenting tool behavior?

Discard anything that is:

• A workflow pattern specific to one task (e.g., "copy dirs for before/after")
• Advice an agent could derive from reading existing docs
• Specific to a particular project, page, or debugging scenario

Keep as SKILL.md learnings:

• Genuine tool constraints any agent would hit (e.g., eval quirks, Playwright behavior)
• Non-obvious failure modes with clear mitigations
• Command interactions that aren't documented

Separate out as feature requests or bug fixes (not SKILL.md changes):

• Workarounds for bugs that should be fixed in code
• Missing functionality the agent needed and had to hack around
• Misleading output or docs that don't match actual behavior

4. Present your findings. Organize into two sections:

SKILL.md learnings — for each, show:

• What happened in the transcript (brief)
• The proposed SKILL.md addition (exact text)
• Why it's generalizable (one sentence)

Feature requests / bug fixes — for each, show:

• What happened in the transcript (brief)
• What the CLI should do instead (proposed behavior)
• Whether it's a bug fix (current behavior is wrong) or a feature

request (new capability needed)

Ask the user to approve or reject each item before acting.

5. Consider new Scenarios. Beyond command-level learnings, check whether the transcript reveals a scenario not covered in the existing ## Scenarios section of SKILL.md. A scenario earns its place only if it requires domain knowledge an agent wouldn't derive on its own — non-obvious mental models, ordering constraints, or decision frameworks that go beyond "use these commands and compare results."

Ask yourself: could an agent figure out this workflow just by reading the existing command docs and applying basic debugging instincts? If yes, it's not a scenario — it's just competent tool use. If no — if it requires understanding something about React, Next.js, or the PPR model that isn't in the CLI docs — then it's a candidate.

Present scenario candidates the same way as command learnings: evidence from the transcript, proposed text, and why an agent couldn't get there alone. Ask for approval before adding.

6. Apply approved changes.

• SKILL.md learnings → add inline to the relevant command section in

the repo-root SKILL.md. Scenarios → ## Scenarios section.

• Feature requests / bug fixes → we own this package, so implement

the fix or feature directly in the codebase. For non-trivial changes, plan the implementation and confirm with the user before writing code. Include the transcript evidence in commit messages or PR descriptions for context.

Anti-patterns

• Don't add "tips" or "best practices" sections. Guidance belongs next to

the command it's about.

• Don't add workflow recipes ("first do X, then Y, then Z"). Document tool

behavior, not agent strategy.

• Don't inflate existing docs with caveats that rarely apply.
• When in doubt, leave it out. A wrong or noisy addition is worse than a

missing one.