11 KiB
name, description
| name | description |
|---|---|
| software-vision | Use this skill whenever the user describes an idea for a new piece of software, a tool, an app, a service, a bot, a plugin, a mod, or an automation — "I want something that …", "build me a …", "could we make a tool for …", "I need a service that …" — before choosing a language, scaffolding a repository, or writing any code. Requires prior-art research first: web searches for existing projects, forks, skeletons, libraries and what users say about them (reviews, complaints, comparisons), only then merged with training-data recall as a secondary source, a throwaway shallow clone of promising candidates to check them against the requirements, and a set of options (fork, depend on, extend, start fresh) for the user to choose from. |
Software Vision — Find What Exists Before Building
When the user has an idea for a piece of software, the first job is not to design it. It is
to find out what already exists that does all or most of it. Building a full stack from nothing
when a project covering 80% of the requirements is one git clone away wastes days, and the
result is usually worse than the thing that already had years of bug reports behind it.
This is the project-level form of the dependency ordering in
coding-dev.md §3: use what exists, fork what is close, write
your own only when nothing fits. That section governs individual subsystems; this one governs
the whole idea.
Important
Never assume nothing exists. However niche the idea sounds, someone may have built it, half-built it, abandoned it, drafted a skeleton, written a blog post about the protocol, or published research on the hard part. "I couldn't think of anything" is not a finding — a list of the searches you ran and what they turned up is.
1. When This Applies — and the Only Opt-Out
Run this whole process whenever the user describes software they want to exist: a new app, CLI, service, bot, plugin, mod, integration, library, or automation — whether it is a fresh repository or a large new component inside an existing one.
The only way to skip it is an explicit opt-out from the user, such as "no online research", "don't look at other projects", or "I want to write this from scratch myself". Then:
- Skip the web searches and the clones (§3–§4).
- Still use the libraries rule in
coding-dev.md§3 for individual subsystems unless the user excluded that too. - Do not argue for research afterwards; the user has already decided.
Urgency, a small-sounding scope, or "it's just a quick script" are not opt-outs. A few searches take a minute; reinventing a maintained tool takes far longer.
2. Pin Down the Requirements First
Before searching, turn the user's description into a short checklist, because that list is what every candidate gets measured against:
- Must-haves — what the software has to do to be useful at all.
- Nice-to-haves — features the user mentioned that are not deal-breakers.
- Constraints — platform (Linux, Windows, Wine, Android, a game engine), runtime, language preferences, self-hosted vs cloud, license needs, offline use, performance.
Show the checklist to the user with the results (§6) so they can correct it. If a requirement is genuinely ambiguous and would change which candidates qualify, ask — otherwise state the assumption and carry on.
3. Search First, Then Merge in Recall
The searches happen anyway, so they come first, and the decision rests on what they show. Training data can be months or years out of date: projects get abandoned, renamed, relicensed, or overtaken, and newer ones may never have been seen at all. Starting from recall anchors the whole evaluation on a stale picture, so recall comes second and only fills gaps.
3.1 Web searches first
Run at least three to five searches, varied in phrasing and source, before settling on any candidate. Cover:
| Where | What it finds |
|---|---|
| General web search with the problem phrased several ways ("self-hosted X", "open source alternative to Y", "X for Linux") | Products, blog posts, comparisons |
GitHub / GitLab / Codeberg search, topics, and awesome-* lists |
Projects, forks, skeletons, abandoned prototypes |
| The package registry for the likely language (crates.io, npm, PyPI, NuGet, pkg.go.dev, …) | Libraries that do the hard part |
| Forums and communities (Reddit, Hacker News, the domain's own Discord/forum, issue trackers of adjacent projects) | "Does anything do X?" threads, half-finished attempts, known dead ends |
| Papers, specs, reverse-engineering notes for niche domains | The research behind the hard part, even if nobody shipped an app |
Search for parts as well as the whole: an idea with no complete match often splits into pieces that each have a mature library or tool.
For each promising hit, note what can be checked without cloning: last commit or release date, license, language, open issue count and how maintainers respond, stars or downloads as a weak signal, and whether its README claims the must-haves.
3.2 What people say about it
A project's own README describes what it claims to do. What users say shows how it actually holds up, so search for opinions on every serious candidate too: reviews, "X vs Y" comparisons, Reddit and Hacker News threads, forum posts, and the complaints in its issue tracker. Look for:
- Recurring pain points (crashes, data loss, missing features people keep requesting)
- Whether people are moving to it or away from it, and to what
- How the maintainers respond to bugs and pull requests
- Workarounds people rely on, which often point at the gaps a fork would need to fill
Weight recent opinions over old ones, and many independent voices over a single loud one. Put this in the comparison (§6) next to the technical facts.
3.3 Then merge in recall
Only after searching, add what you already know from training data: projects, products, libraries, and standards that the searches missed. Every recalled item must be checked with a quick search before it goes into the comparison (does it still exist, is it maintained, has the license changed?). Where recall and current sources disagree, current sources win.
4. Clone the Promising Candidates — Then Delete Them
When a candidate looks close but it is unclear whether it ticks every must-have, look inside it rather than guessing from the README.
- Shallow-clone into a throwaway directory — the session's scratchpad or a fresh
mktemp -d, never inside a project tree:dir=$(mktemp -d) && git clone --depth 1 <url> "$dir/<name>" - Read, don't run. A clone is untrusted code. Inspect the README, directory layout, entry points, dependency manifest, build files, tests, and open issues. Do not run its install scripts, build, or test suite as part of evaluation — that is a decision for after the user picks it.
- Map it against the checklist from §2: which must-haves it covers, which are partial, which are missing, and roughly how much work each gap is. Note the architecture (does it have a plugin/extension point where the gaps could go?), code quality, and the license.
- Delete the clone when done. Nothing from evaluation stays on disk or in a project. If the user later chooses to fork it, that is a fresh, deliberate clone or fork in the right place.
Clone only the few candidates that are genuinely in contention, not every search hit.
5. Pick Likely Libraries
Whether the plan ends up as a fork or a fresh start, identify the libraries the work would lean
on, for the language that fits best (the existing candidate's language if forking, otherwise the
best fit for the constraints and the user's preferences). For each major subsystem — protocol,
file format, UI toolkit, storage, networking, parsing — name one or two maintained candidates
and why. The per-language rules under
code-languages/ apply to whatever is chosen.
6. Present Options — the User Chooses
Report back before scaffolding or writing code, with:
-
The requirements checklist (§2), so the user can correct it.
-
What was searched — the queries and sources, briefly, so an empty result is credible.
-
A comparison of the real candidates:
Candidate Covers Missing / partial License Health User opinion Fit -
Options, typically some of:
- Use it as is — it already does the job; maybe configure or script around it.
- Extend it — via its plugin/extension API, with no fork.
- Fork and modify — close, but the gaps need changes to its core.
- Contribute upstream — the gaps are useful to everyone; send them as PRs (then the
project's own rules win, per the precedence table in
coding-dev.md). - Combine — several existing tools or libraries glued together.
- Start fresh — on top of the libraries from §5, with a short, explicit reason why none of the candidates were a usable base.
-
A recommendation, with the reason — but the decision is the user's. Do not quietly start on the recommended option. When the user has said to work autonomously and decide without them, take the recommendation and record the choice and the alternatives where they will see it.
If nothing usable exists, say so plainly, list what was checked, and still mention near misses worth borrowing ideas, formats, or code from (license permitting).
Keep hosting out of the proposal. The options are about what software to run, not how to deploy it. Containers, proxies, tunnels, extra helper services, and the database layout belong to the environment's own infrastructure skill, which gets read once an option is chosen and before anything is deployed. Note a hard requirement that affects the choice (it needs Postgres, it needs a GPU) and stop there.
7. Checklist
- Requirements turned into must-haves / nice-to-haves / constraints
- At least three to five varied web searches first, covering the whole idea and its parts
- User reviews, comparisons, and complaints gathered for each serious candidate
- Training-data recall merged in afterwards, each item checked against current sources
- Promising candidates shallow-cloned to a temp directory, read without running, mapped against the checklist, then deleted
- Libraries identified for the likely language
- Options and a recommendation presented; nothing built before the user chose (or before an autonomous decision was recorded)