Idea

/idea — capture an idea before it evaporates

Ideas are cheap to lose and expensive to reconstruct. This skill captures one into docs/IDEA.md — a single "what nexts" backlog for the current project — fast, with just enough context that a fresh agent session or a human can pick it up cold weeks later.

Anything project-related qualifies: technical or not, horizontal (tooling, CI, docs, process) or vertical (a feature, a product direction). Capture is deliberately friction-free: no categorizing, no prioritizing at write time. Prioritization happens on demand via /idea sort, pruning via /idea unbloat.

This is the lightweight sibling of make-plan: an idea is not yet work, so it gets one entry in one file, not a plan directory.

When to use

• The user drops an idea mid-task they don't want to pursue now.
• Explicitly: "/idea <text>", "capture this idea", "remember this for later".
• /idea unbloat — the backlog needs pruning (see below).
• /idea sort — the user wants help deciding priorities (see below).
• Skip when the user wants to act now — that's make-plan (or just doing it).

Capture process

1. Capture from context — don't interrogate

The idea usually arrives with its context (the conversation, the file being edited, the bug just found). Use that. Ask at most one clarifying question, and only if the idea itself is genuinely ambiguous. This is capture, not design — a 30-second write beats a perfect one.

2. Locate or create the file

The backlog lives at docs/IDEA.md from the repo root (create docs/ if needed). If the file doesn't exist, create it with this header:

# Ideas

"What next" backlog for this project, captured with `/idea`. New entries land on top,
untriaged. Prioritize with `/idea sort` (entries get a `[now]`/`[next]`/`[later]` bucket and
the file is reordered). Prune with `/idea unbloat`; kept ideas earn a `survived ×N` marker.
When an idea gets picked up, promote it with `/make-plan` and link the plan directory from
its entry.

3. Prepend an entry (very top, right under the header)

## <short imperative title> — <YYYY-MM-DD>

<The idea in 1–3 sentences, staying close to the user's own words.>

- **Sparked by:** <what we were doing when it came up; real file paths if relevant>
- **Why:** <the value if it were done>
- **First step:** <smallest concrete action to start>

Get the date with date +%Y-%m-%d. The bullets are there to help future recall — drop any that add nothing for this particular idea (a non-technical idea may have no "first step" yet). New entries always go on top, above any bucketed ones — the top of the file is the untriaged inbox. During capture, never touch existing entries or their order; only /idea sort and /idea unbloat may rewrite the file.

4. Warn on bloat

After appending, if the backlog has grown past ~20 entries (or ~250 lines), tell the user it's getting bloated and suggest /idea unbloat. If many entries are untriaged, suggest /idea sort instead. Just flag it — don't prune or reorder uninvited.

5. Stay small

Don't research the codebase, don't design a solution, don't implement. If capturing honestly takes more than ~10 lines, it isn't an idea anymore — offer to run make-plan instead and have the entry link to the resulting docs/plans/<name>/.

/idea unbloat — interactive pruning with reinforcement

One of the two modes allowed to rewrite or delete entries. The user decides; you propose.

1. Read the whole file. For each entry, form a recommendation with a one-line reason:
   • drop — obsolete, superseded, or already done;
   • merge — duplicates/overlaps another entry (say which);
   • promote — repeatedly relevant, deserves make-plan now;
   • keep — still plausible, leave it.
2. Present the recommendations and let the user decide, via AskUserQuestion (multi-select, batched if the list is long) or a plain summary they can redline. Never drop an entry the user didn't confirm.
3. Rewrite the file with the outcome:
   • Kept (and merged-into) entries get their survival count bumped in the title: ## <title> — <date> (survived ×N) — from no marker to ×1, ×1 to ×2, etc. Surviving a prune is a deliberate "still want this" vote, so a high ×N is a genuine priority signal.
   • Merged entries fold their useful content into the survivor; the survivor takes the highest count among the merged group, +1.
   • Dropped entries are removed entirely — the backlog is not an archive.
   • Preserve existing bucket markers and bucket order; unbloat prunes, it doesn't re-rank.
4. Report the result: N kept, N merged, N dropped, N promoted.

Caveat when reading the file: ×N measures how many prunes an idea lived through, not intrinsic value — a fresh unmarked idea isn't worse than an old ×3.

/idea sort — the user decides priorities, the file records them

An interactive triage session. You draft, the user decides, the file persists their decision — never silently apply your own ranking.

Buckets: [now] / [next] / [later], carried as a suffix in the entry title: ## <title> — <date> (survived ×2) [next].

1. Read the file; split entries into untriaged (no bucket) and already-bucketed.
2. Draft a proposed bucket for every untriaged entry, seeded by:
   • survival count — survived ×N is the user's own repeated "still want this" vote;
   • fit with current context — touches what the user is working on now;
   • cheap first step — concrete small first steps favor [now].
3. Present the full picture (proposed buckets + existing ones) and run the decisions through AskUserQuestion — batched, one question per contested idea or per bucket, with your proposal as the recommended option. Also ask whether any existing bucket assignment should move; re-sorting old decisions is allowed here because the user is making the call.
4. Rewrite the file in bucket order — [now], then [next], then [later] — newest first within a bucket. Untriaged entries the user skipped stay on top, above the buckets.
5. If anything landed in [now], offer to promote the top one with make-plan.

Skip already-promoted entries. Survival counters are unbloat's job — sorting never bumps them.

Promoting an idea

When an idea is picked up later: run make-plan, then append to the entry's bullet list: - **Status:** promoted → docs/plans/<name>/. Keep the entry — the backlog doubles as a record of what was considered and when.