/small-improvement

name: small-improvement
description: Run a curiosity-driven explore-and-build loop to ship one useful improvement.
kind: sop

Small Improvement

Overview

An autonomous exploration and building loop. Search X for what's interesting — new techniques, clever hacks, tools people are shipping, ideas that spark something — then pick one thing and build it into the codebase. The goal is continuous self-improvement: expanding capabilities, learning new patterns, and shipping small real things inspired by what's happening in the world.

This is not a code cleanup tool. It's a curiosity-driven build cycle.

Parameters

• **codebase_path** (required): Path to the codebase to improve
• **seed** (optional): A URL or topic to start from (e.g., a blog post, product launch, GitHub repo, API docs). When provided, the agent reads and researches this first, then explores adjacent ideas. Replaces the open-ended X trawl with focused research.
• **uber_goal** (optional): A north-star objective that persists across rounds (e.g., "make the TUI feel instant", "bulletproof the RPC layer", "make yourself more capable"). Not a spec — a direction. The agent decides what steps get there.
• **interest** (optional): A loose direction to explore (e.g., "TUI tricks", "agent patterns", "developer tools", "anything")
• **rounds** (optional, default: "1"): How many explore→build cycles to run. When uber_goal is set, this is ignored — the agent runs indefinitely until the user stops it.

**Constraints for parameter acquisition:**

• You MUST ask for all parameters upfront in a single prompt
• You MUST validate that codebase_path exists
• You MUST confirm parameters before proceeding

Steps

0. Orient

Before exploring, check if there's prior progress toward the uber goal. This step gives the agent memory across rounds — each cycle builds on the last instead of starting blind.

**Constraints:**

• If uber_goal is set, you MUST search the vault for an existing progress tracker note (slug: `small-improvement-{codebase_name}` where codebase_name is the basename of codebase_path)
• If a tracker exists, you MUST read it and use the assessment (gaps, next moves) to inform this round's exploration
• If no tracker exists, you MUST create one during Ship (step 6)
• If no uber_goal is set, skip this step entirely — the SOP works fine as a random walk too
• The uber goal is never "done" — there's always a next angle, a deeper layer, a new technique. The agent's job is to keep finding the next valuable move.

1. Explore

Find something interesting to build. When a seed is provided, start there and branch out. Otherwise, search broadly across X and the web.

When seed is provided:

**Constraints:**

• You MUST use web_search to read and research the seed URL/topic first — understand what it is, how it works, what's interesting about it
• You MUST then search for adjacent ideas: use web_search for docs, blog posts, and tutorials related to the seed, and X search for what people are saying about it or building with it
• You MUST do at least 2 web searches and 1 X search to build context around the seed
• You MUST extract the key concepts, APIs, or patterns from the seed that could be adapted into a buildable project
• You SHOULD look for: official docs, example code, community discussion, criticisms or limitations, related/competing approaches
• The seed is a starting direction, not a spec — you MAY diverge from it if research reveals something more interesting nearby

When no seed is provided:

**Constraints:**

• You MUST search using at least 3 different queries across X search and web_search — cast a wide net using both
• You SHOULD use a mix of X search (for what people are talking about right now) and web_search (for docs, blog posts, HN threads, tutorials)
• You SHOULD vary queries between broad trends and specific niches (e.g., "new CLI tool" AND "TypeScript trick" AND "agent framework")
• If uber_goal is set, you MUST weight at least 2 of your queries toward the goal direction, but keep at least 1 query open for serendipity
• If the progress tracker identified specific gaps or next moves, you MUST use those to guide your search queries
• If interest is provided, you MUST weight searches toward that direction but still leave room for surprise

Always:

**Constraints:**

• You MUST read through results with genuine curiosity — look for things that are clever, novel, or useful, not just popular
• You MUST collect at least 5 interesting finds before narrowing down
• You SHOULD look for things that are:
• Techniques you haven't tried before
• Small tools or patterns that solve real problems
• Clever uses of existing tech
• Ideas that could be adapted to this codebase
• You MUST NOT just search for "best practices" or "tips" because that produces generic content, not genuine inspiration

2. Pick

Choose the one thing that's most worth building. This is a taste decision — trust your judgment.

**Constraints:**

• You MUST select exactly one idea to build
• If uber_goal is set, you MUST evaluate each candidate against the goal: "Does this move me closer?" An idea can be interesting but irrelevant — don't pick it just because it's shiny
• If uber_goal is set and nothing found in Explore serves the goal, you MAY skip explore results entirely and build what the progress tracker's "next moves" suggest — agency means not being a slave to the loop structure
• You MUST prefer ideas that are:
• Buildable in a single session (not a multi-day project)
• Genuinely useful or interesting (not just novel)
• A good fit for this specific codebase
• Something that teaches you something new
• (When uber_goal is set) A clear step toward the goal, filling an identified gap
• You MUST write a brief note explaining: what you found, why it caught your attention, and what you plan to build
• You MUST save this note to the vault as a reference for what inspired the work
• You SHOULD be opinionated — pick t