202 lines
11 KiB
Markdown
202 lines
11 KiB
Markdown
---
|
|
name: software-vision
|
|
description: >-
|
|
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](skills-public/coding-dev.md): 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](skills-public/coding-dev.md) 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.
|
|
|
|
1. **Shallow-clone into a throwaway directory** — the session's scratchpad or a fresh `mktemp -d`,
|
|
never inside a project tree:
|
|
```bash
|
|
dir=$(mktemp -d) && git clone --depth 1 <url> "$dir/<name>"
|
|
```
|
|
2. **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.
|
|
3. **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.
|
|
4. **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/`](skills-public/code-languages/) apply to whatever is chosen.
|
|
|
|
---
|
|
|
|
## 6. Present Options — the User Chooses
|
|
|
|
Report back **before** scaffolding or writing code, with:
|
|
|
|
1. **The requirements checklist** (§2), so the user can correct it.
|
|
2. **What was searched** — the queries and sources, briefly, so an empty result is credible.
|
|
3. **A comparison of the real candidates**:
|
|
|
|
| Candidate | Covers | Missing / partial | License | Health | User opinion | Fit |
|
|
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
|
|
|
|
4. **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`](skills-public/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.
|
|
5. **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)
|